当前位置：首页 > news >正文

Vue CLI 环境变量和文件加载规则.env文件

news 2025/9/6 12:09:43

Vue CLI 通过一套明确的环境变量和文件加载规则来确定使用哪个 .env 文件。以下是详细的工作原理：

一、核心决定因素

1. 模式 (Mode) 是主要决定因素

Vue CLI 根据你运行的命令或手动设置的模式来决定加载哪个环境文件：

# 开发模式 → 加载 .env.development
npm run serve        # 或 vue-cli-service serve# 生产模式 → 加载 .env.production  
npm run build        # 或 vue-cli-service build# 测试模式 → 加载 .env.test
npm run test:unit    # 或 vue-cli-service test:unit

2. 环境变量优先级

Vue CLI 按照以下顺序加载环境变量（后面的会覆盖前面的）：

.env - 所有环境的默认配置
.env.[mode] - 特定模式的配置（如 .env.development）
命令行参数 - 最高优先级

二、环境文件加载规则

文件加载顺序示例：

# 运行 vue-cli-service serve (开发模式)
1. 加载 .env
2. 加载 .env.development
3. 加载 .env.local (如果存在)
4. 加载 .env.development.local (如果存在)# 运行 vue-cli-service build (生产模式)  
1. 加载 .env
2. 加载 .env.production
3. 加载 .env.local (如果存在)
4. 加载 .env.production.local (如果存在)

三、模式的具体判断逻辑

1. 默认模式映射

Vue CLI 内置了默认的模式映射：

命令	默认模式	加载的文件
`vue-cli-service serve`	`development`	`.env.development`
`vue-cli-service build`	`production`	`.env.production`
`vue-cli-service test:unit`	`test`	`.env.test`

2. 自定义模式

你可以创建自定义模式并使用对应的环境文件：

# 创建自定义环境文件
.env.staging          # 预发布环境# 使用自定义模式
vue-cli-service build --mode staging

四、环境变量命名规则

1. 文件中的变量命名

在 .env 文件中，变量需要以 VUE_APP_ 开头：

# .env.development
VUE_APP_API_URL=https://api-dev.example.com
VUE_APP_DEBUG=true# .env.production
VUE_APP_API_URL=https://api.example.com
VUE_APP_DEBUG=false

2. 在代码中访问

// 在 Vue 组件或 JS 文件中使用
console.log(process.env.VUE_APP_API_URL)
console.log(process.env.VUE_APP_DEBUG)
console.log(process.env.NODE_ENV) // 自动注入：'development' 或 'production'

五、手动指定模式

1. 通过命令行参数

# 显式指定模式
npm run serve -- --mode staging
vue-cli-service serve --mode staging# 构建时指定不同模式
vue-cli-service build --mode development  # 开发环境构建
vue-cli-service build --mode staging      # 预发布环境构建

2. 通过 package.json 脚本

{"scripts": {"serve": "vue-cli-service serve","build": "vue-cli-service build","build:staging": "vue-cli-service build --mode staging","build:dev": "vue-cli-service build --mode development"}
}

六、环境文件示例

1. 基础环境文件结构

project-root/
├── .env                 # 全局默认配置
├── .env.development     # 开发环境配置
├── .env.production      # 生产环境配置
├── .env.staging         # 预发布环境配置
├── .env.local           # 本地覆盖配置（不提交到git）
└── .env.development.local # 开发本地配置

2. 文件内容示例

.env (全局默认)

# 所有环境共享的配置
VUE_APP_NAME=My Vue App
VUE_APP_VERSION=1.0.0

.env.development (开发环境)

# 开发环境配置
NODE_ENV=development
VUE_APP_API_URL=https://api-dev.example.com
VUE_APP_DEBUG=true
VUE_APP_SENTRY_DSN=  # 开发环境可能不需要 Sentry

.env.production (生产环境)

# 生产环境配置
NODE_ENV=production
VUE_APP_API_URL=https://api.example.com
VUE_APP_DEBUG=false
VUE_APP_SENTRY_DSN=https://sentry.example.com/your-dsn

.env.staging (预发布环境)

# 预发布环境配置
NODE_ENV=production  # 注意：构建模式仍然是 production
VUE_APP_API_URL=https://api-staging.example.com
VUE_APP_DEBUG=true   # 预发布环境可能需要调试

七、在 Jenkins 中配置不同环境

1. Pipeline 示例

pipeline {agent anyenvironment {// 根据构建参数设置模式VUE_CLI_MODE = params.BUILD_MODE ?: 'production'}stages {stage('Build') {steps {script {// 根据不同的模式使用不同的环境文件if (env.VUE_CLI_MODE == 'staging') {sh '''echo "Building for staging environment"npm run build:staging'''} else if (env.VUE_CLI_MODE == 'development') {sh '''echo "Building for development environment"  npm run build:dev'''} else {sh '''echo "Building for production environment"npm run build'''}}}}}parameters {choice(name: 'BUILD_MODE',choices: ['production', 'staging', 'development'],description: '选择构建环境')}
}

2. 使用环境变量覆盖

stage('Build') {steps {sh '''# 使用环境变量覆盖 .env 文件中的配置export VUE_APP_API_URL=${API_URL}export VUE_APP_VERSION=${APP_VERSION}npm run build'''}
}

八、调试环境变量

1. 查看加载的环境变量

// 在 main.js 或任何文件中添加
console.log('当前环境变量:', process.env)
console.log('API URL:', process.env.VUE_APP_API_URL)
console.log('当前模式:', process.env.NODE_ENV)

2. 创建调试脚本

在 package.json 中添加：

{"scripts": {"env:debug": "vue-cli-service serve --mode development --debug","env:info": "node -e \"console.log('NODE_ENV:', process.env.NODE_ENV); console.log('VUE_APP vars:', Object.keys(process.env).filter(key => key.startsWith('VUE_APP_')))\""}
}