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

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 按照以下顺序加载环境变量（后面的会覆盖前面的）：

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

二、环境文件加载规则

文件加载顺序示例：

# 运行 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 内置了默认的模式映射：

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 any
    
    environment {
        // 根据构建参数设置模式
        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_')))\""
  }
}

九、重要注意事项

1. .env.local 文件：本地覆盖，应该添加到 .gitignore
2. 变量前缀：只有 VUE_APP_ 开头的变量才会被嵌入客户端代码
3. 敏感信息：不要在 .env 文件中存储密码等敏感信息
4. 构建时确定：环境变量在构建时被嵌入，运行时无法更改

十、总结

Vue CLI 通过以下方式确定使用哪个环境文件：

1. 命令决定模式：serve → development，build → production
2. 模式决定文件：模式名对应 .env.[mode] 文件
3. 加载顺序：.env → .env.[mode] → .env.local → .env.[mode].local
4. 优先级：后面的文件覆盖前面的配置

通过理解这个机制，你可以灵活地为不同环境配置不同的变量。