Vite 环境变量前缀不生效时如何区分模式

Vite 环境变量“读不到”时，先不要急着改变量名：通常要同时确认客户端暴露前缀、当前 mode、环境文件所在目录和进程变量优先级。Vite 默认只把以 VITE_ 开头的变量放进 import.meta.env，而 vite dev 与 vite build 的默认 mode 也不同。

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

最稳妥的判断顺序是：先看变量是否符合 envPrefix，再用 import.meta.env.MODE 确认 mode，最后检查 NODE_ENV 和已有进程变量是否覆盖了文件内容。修改 .env 后还要重启开发服务器。

本文速记：① 前缀决定“能不能被客户端看见”；② --mode 决定读取哪组 mode 文件；③ MODE 与 NODE_ENV 不是一回事。

先确认客户端暴露前缀与加载目录

在前端源码里，下面的写法只有第一项默认可见：

const apiBase = import.meta.env.VITE_PUBLIC_API_BASE
const buildLabel = import.meta.env.VITE_BUILD_LABEL
const dbPassword = import.meta.env.DB_PASSWORD

// 前两项是公开配置，第三项不会因写进 .env 就自动暴露
console.log({ apiBase, buildLabel, dbPassword })

Vite 会把自定义变量按字符串注入；数字和布尔值也需要自行转换。DB_PASSWORD 这类未加前缀的值不是“模式没切换”，而是客户端暴露规则主动将它挡住。若团队确实需要另一种公开前缀，可在 vite.config.ts 中配置数组，但不要把 envPrefix 设成空字符串，否则会把所有环境变量带到客户端，形成泄密风险。

同时确认环境文件位于 Vite 的 envDir（默认是项目根目录）。如果把文件放在自定义目录，就要同步配置：

import { defineConfig } from 'vite'

export default defineConfig({
  // 只暴露项目明确允许进入浏览器的前缀
  envPrefix: ['VITE_', 'PUBLIC_'],
  // 让 .env 文件从配置目录加载
  envDir: './config'
})

用 --mode 选择对应的环境文件

文件名和命令必须成对。通用配置放在 .env，测试、预发布和生产配置分别放在 .env.testing、.env.staging、.env.production：

# .env.staging
# 这里放预发布环境允许进入前端的非敏感地址
VITE_API_BASE=https://staging.example.test/api
VITE_BUILD_LABEL=staging

# 选择 staging 文件，而不是依赖当前 shell 的 NODE_ENV
npx vite build --mode staging

vite dev 默认使用 development，vite build 默认使用 production。因此运行开发服务器时，若要读 .env.staging，应明确执行 vite --mode staging；只写 NODE_ENV=staging 并不会把 mode 改成 staging。

文件加载后，mode 专用文件优先于通用 .env，但只在专用文件出现的键仍可从通用文件得到。.env.local 和 .env.[mode].local 适合本地覆盖，并应加入忽略规则。

分开判断 MODE、NODE_ENV 与变量优先级

排障时同时打印三个非敏感值最有效：

const envSnapshot = {
  // MODE 来自 Vite 的 --mode 或命令默认值
  mode: import.meta.env.MODE,
  // PROD/DEV 受 NODE_ENV 影响，但与 mode 不是同一字段
  prod: import.meta.env.PROD,
  dev: import.meta.env.DEV,
  // 只打印公开标识，不打印 token、密码或完整连接串
  label: import.meta.env.VITE_BUILD_LABEL
}

console.table(envSnapshot)

例如 vite build --mode development 的 mode 可以是 development，但它仍然是一次 build；反过来，NODE_ENV=development vite build 会改变构建环境判断，却不会把 mode 自动变成 development。把这两组概念分开记录，才能知道到底是文件名错了，还是脚本设置覆盖了预期。

重启并做安全的结果验证

Vite 在启动时读取环境文件，所以修改后先停止再启动 dev server。然后按下面的清单反向验证：

最后只验证 MODE、DEV/PROD 和构建标签，不要在浏览器控制台打印密钥。所有以 VITE_ 或自定义公开前缀暴露的内容都会进入客户端代码；真正的 API 密钥、数据库密码和签名材料应由后端或服务端函数保存。

相关问题

为什么 .env.production 没有覆盖 .env？先看命令是否真的处于 production mode，再检查 shell 中是否已经存在同名变量。Vite 执行时已有的进程环境变量优先级更高。

能否直接读取 import.meta.env.API_URL？默认不能。除非把前缀配置为包含它的安全范围，否则应改成公开前缀；不要为了省事把前缀设为空字符串。