Vue脚手架模式与环境变量

在真实项目里，「如果每次切换环境都手动改代码，不仅低效，还极易把测试地址带到线上。Vue CLI 把「模式 + 环境变量」做成了一套约定大于配置的体系，只要理解规则，就能让同一份源码在任意环境自动作出正确的行为。

一、模式（mode）

Vue CLI 把「运行命令」抽象成三种默认模式：

• development：对应 vue-cli-service serve
• production：对应 vue-cli-service build
• test：对应 vue-cli-service test:unit

模式本身不携带任何变量，它只是约定文件名前缀。

当你执行：

npm run serve        # 实际等价于 vue-cli-service serve --mode development
npm run build:staging # 自定义命令，等价于 vue-cli-service build --mode staging

CLI 会按以下顺序寻找文件：

1. .env.[mode].local
2. .env.[mode]
3. .env.local（永远被 git ignore）
4. .env

同名变量后者覆盖前者，因此你可以把公共值写在 .env，把敏感值写在 .env.local，把环境特有值写在 .env.staging，一条命令即可切换。

二、环境变量

1. 只有 VUE_APP_ 开头的变量才会被打包

任何机器级环境变量（PATH、HOME …）都会被忽略，避免污染前端运行时。

想让变量进 bundle，必须加前缀：

# .env.staging
VUE_APP_API_BASE=https://staging.api.example.com

在代码里直接用：

axios.defaults.baseURL = process.env.VUE_APP_API_BASE

构建时 CLI 会把 process.env.VUE_APP_API_BASE 替换为字符串字面量，零运行时开销。

2. 运行时不可动态修改

变量在 npm run build 那一刻就被写死，前端无法通过 process.env.XXX = 'new' 去改。

需要运行时可变配置？把变量写成 JSON 文件或接口返回，再在前端异步加载即可。

三、一个文件，一条命令，三种环境

假设我们要同时支持 dev / staging / prod：

根目录
├─ .env                 # 公共配置
├─ .env.development     # 本地开发
├─ .env.staging         # 预发
├─ .env.production      # 线上
└─ package.json

文件内容示例：

# .env
VUE_APP_TITLE=MyApp# .env.development
VUE_APP_API_BASE=http://localhost:3000# .env.staging
VUE_APP_API_BASE=https://staging.api.example.com# .env.production
VUE_APP_API_BASE=https://api.example.com

自定义脚本：

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

执行：

npm run build:staging

CLI 自动读取 .env.staging 与 .env 合并，输出包里只有 https://staging.api.example.com。

四、CI/CD 中的最佳实践

1. 不把敏感密钥写进仓库

   把 .env*.local 加入 .gitignore，在 CI 里用环境变量注入：

   echo $STAGING_KEY >> .env.staging.local

2. 单一 Dockerfile，多阶段构建

   通过 ARG MODE 动态决定 --mode，同一份镜像可在测试、预发、生产之间漂移。

3. 可视化差异

   在构建日志里打印 console.log('Build mode:', process.env.NODE_ENV, process.env.VUE_APP_API_BASE)，一眼确认变量是否生效。

五、常见问题

• 变量名可以改前缀吗？

  可以，在 vue.config.js 里设置 envPrefix: 'APP_' 即可。

• 为什么本地 .env 改了值不生效？

  vue-cli-service serve 会缓存旧进程，重启 dev-server 或加 --no-cache 即可。

• 如何读取非 VUE_APP 变量？

  在 vue.config.js 用 chainWebpack 手动注入：

  config.plugin('define').tap(args => {args[0]['process.env.CUSTOM'] = JSON.stringify(process.env.CUSTOM)return args})