Vite 构建模式隔离多环境变量文件

Vite 多环境配置的关键，不是把 if (isProduction) 写满业务代码，而是把“当前构建模式”“变量文件”“浏览器可见范围”分开管理。日常开发使用 vite，测试构建使用 vite build --mode staging，生产构建使用默认的 production mode；每个 mode 只覆盖自己的文件。

官方地址：https://vite.dev/

用 mode 把环境文件分层，而不是在代码里判断环境

先把环境名称当成配置选择器，而不是把它等同于“开发或生产”。Vite 开发服务器默认使用 development mode，vite build 默认使用 production mode；测试环境可以单独命名为 staging。这三个名称只描述变量文件的选择，不能替代业务上的权限判断。

另一个容易混淆的字段是 NODE_ENV。例如 vite build --mode development 仍然是一次 build 命令，mode 是 development，而命令阶段的 NODE_ENV 可能仍为 production。需要判断打包命令时看 mode，需要判断开发优化分支时再看 import.meta.env.DEV 或 import.meta.env.PROD。

用 --mode 选择构建目标并固定文件覆盖关系

推荐把公共值放进 .env，本机私有覆盖放进 .env.local，测试值放进 .env.staging，测试机私有值放进 .env.staging.local。Vite 会加载通用文件和当前 mode 文件，mode 专属文件优先；已经存在于执行环境中的变量优先级更高。

# .env：所有 mode 都能读取的非敏感默认值
VITE_API_PREFIX=/api

# .env.staging：测试构建专用的公开地址
VITE_API_BASE=https://staging-api.example.com

# .env.production：生产构建专用的公开地址
VITE_API_BASE=https://api.example.com

构建脚本可以把选择关系写得很直白：

# 测试环境使用 staging 文件，不改变业务代码
npm run build -- --mode staging

# 生产环境使用 production 文件
npm run build

新增或修改 .env 后要重启开发服务器。把 *.local 加入 .gitignore，避免个人覆盖值和本机令牌进入仓库。

只把 VITE_ 变量暴露给浏览器代码

前端代码通过 import.meta.env.VITE_API_BASE 读取公开配置，读取到的值都是字符串，需要在使用处自行转换布尔值或数字。没有 VITE_ 前缀的 DB_PASSWORD、JWT_SECRET 等变量不会默认暴露给浏览器。

// 只放可公开的接口地址和功能开关
const apiBase = import.meta.env.VITE_API_BASE
const retryLimit = Number(import.meta.env.VITE_RETRY_LIMIT ?? 2)

// 机密应由后端或服务端函数读取，不能写入 VITE_ 文件
const publicConfig = { apiBase, retryLimit }
export default publicConfig

“没有前缀所以安全”只说明它不会自动注入客户端，不代表它可以随便提交到仓库。CI、部署平台和后端运行时仍要按密钥管理规则保存敏感值。

在 vite.config.js 里用 loadEnv 读取构建侧配置

Vite 配置文件的求值早于应用代码，不能假设所有 .env 字段已经自动出现在 process.env。当代理、source map 或 base 需要跟随 mode 变化时，在配置函数中调用 loadEnv：

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 按当前 mode 读取 envDir 下的公开变量
  const env = loadEnv(mode, process.cwd(), 'VITE_')

  return {
    // 代理目标跟随 staging 或 production 文件变化
    server: {
      proxy: {
        '/api': { target: env.VITE_API_BASE, changeOrigin: true }
      }
    },
    // 只有明确配置为 true 时才打开 source map
    build: { sourcemap: env.VITE_SOURCEMAP === 'true' }
  }
})

这里的第三个参数限定了加载前缀；如果需要读取构建工具自己的私有字段，可以显式调整前缀并把它留在配置侧，仍不要把密钥返回给客户端。发布前按下面的顺序检查：命令是否带对 --mode、文件名是否匹配、变量是否真的以 VITE_ 开头、配置文件是否调用了 loadEnv、以及变量值是否仍是字符串。

相关问题

为什么改了 .env.production 但开发页面没有变化？

开发服务器默认是 development mode，不会读取 production 专属值；应修改 .env.development，或用对应的 mode 启动命令。

VITE_API_BASE 放进 .env.local 就一定不会泄露吗？

不会。它虽然可以不提交到 Git，但只要带有 VITE_ 前缀，值就会被打进客户端代码；只能放公开地址和公开开关。

什么时候必须调用 loadEnv？

当变量要参与 vite.config.js 的代理、路径、插件或构建选项时调用；应用组件读取公开变量则使用 import.meta.env。