Vite 环境变量为什么需要 VITE_ 前缀

Vite 之所以默认要求自定义环境变量使用 VITE_ 前缀，不是为了增加记忆成本，而是为了划出一条明确的客户端暴露边界：带此前缀的变量会在构建时进入浏览器代码，未带此前缀的变量默认不会出现在 import.meta.env 中。

因此，VITE_API_BASE_URL 适合放公开的接口地址，DB_PASSWORD、私有 API Key 和服务器令牌则应该留在后端。Vite 官方地址：

官方地址：https://vite.dev/guide/env-and-mode.html

把 VITE_ 理解成“允许进入客户端构建产物的公开配置前缀”，而不是“让变量变得安全的加密开关”，就不会把密钥误写进前端。

先建立客户端暴露边界

Vite 会把环境变量放到特殊的 import.meta.env 对象中。默认规则很简单：以 VITE_ 开头的自定义变量可以被客户端代码读取，其他自定义变量不参与这条暴露路径。这个规则让“哪些值可以进入浏览器”变成代码审查时一眼可见的约定。

例如下面的文件中，只有前缀匹配的变量会沿着客户端构建链路继续向前：

# 公开配置可以被浏览器代码读取；密码必须留在服务端
VITE_API_BASE_URL=https://api.example.test
VITE_APP_TITLE=控制台
DB_PASSWORD=只在后端使用

// 前端只能读取被 Vite 暴露的公开变量
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
const databasePassword = import.meta.env.DB_PASSWORD

console.log(apiBaseUrl) // 可以得到字符串值
console.log(databasePassword) // undefined，不应把它改名后塞进前端

这里的“不能读取”不是权限系统，也不是把秘密加密后藏起来；它只是 Vite 默认不把该变量替换进客户端代码。真正的秘密仍然应该由服务端读取，并通过受控接口返回必要的业务结果。

用 import.meta.env 读取公开配置

变量读取方式是 import.meta.env.变量名。需要注意的是，Vite 会把环境变量解析成字符串，所以布尔值和数字都要在业务边界处显式转换，避免把字符串 "false" 当成布尔值 false 处理。

// 在应用启动边界统一转换公开配置，避免各组件重复判断
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
const debugEnabled = import.meta.env.VITE_DEBUG === 'true'
const retryCount = Number.parseInt(import.meta.env.VITE_RETRY_COUNT ?? '3', 10)

export const runtimeConfig = {
  apiBaseUrl,
  debugEnabled,
  retryCount: Number.isNaN(retryCount) ? 3 : retryCount,
}

这个写法把“配置缺失”和“配置类型”集中在一个位置处理。组件只消费 runtimeConfig，不会在多个文件里各自猜测字符串含义。

按 mode 组织 .env 文件

Vite 会加载通用文件和模式文件。常见组合是 .env、.env.local、.env.production 与 .env.production.local。执行 vite build 时默认处于 production mode，模式专用文件的值优先于通用文件；已经存在于启动进程中的环境变量优先级更高。

# 通用值：所有模式都可使用
VITE_API_BASE_URL=https://api.example.test

# .env.production：生产构建覆盖同名公开配置
VITE_API_BASE_URL=https://api.example.com

# 使用自定义模式时，改为读取 .env.staging
npm run build -- --mode staging

.env.*.local 适合本机差异配置，并应加入 Git 忽略规则。修改环境文件后要重启开发服务器，因为 Vite 会在启动阶段加载这些文件，运行中的进程不会自动重新读取。

排查前缀不生效和类型误判

遇到 undefined 时，按下面的顺序判断，通常不需要改 Vite 配置：

另外，import.meta.env.MODE 和 process.env.NODE_ENV 不是一回事。前者描述 Vite 的 mode，后者描述 Node 环境；不要只改一个变量就假定两者会同步。

谨慎调整 envPrefix

如果团队已经有稳定的公开配置命名，也可以在 Vite 配置里设置 envPrefix，让多个明确的前缀进入客户端。例如允许 PUBLIC_ 与默认的 VITE_：

import { defineConfig } from 'vite'

export default defineConfig({
  // 只扩大公开变量集合，不把后端秘密变成前端变量
  envPrefix: ['VITE_', 'PUBLIC_'],
})

不要把 envPrefix 设为空字符串。空前缀会让环境变量整体暴露，Vite 官方配置文档也明确把它列为安全风险。即使自定义了前缀，也要继续坚持“前端只放公开配置”的边界。

最后的判断清单

• 客户端需要的值是否确实是公开配置，而不是凭据或服务器内部状态？
• 变量名是否以当前配置允许的前缀开头，且大小写完全一致？
• 当前命令使用的是哪个 mode，目标文件是否真的被加载？
• 字符串、数字和布尔值是否在配置入口统一转换？
• 修改 .env 后是否重启了 Vite 进程？

常见问题

为什么 .env 里写了 API_KEY，前端却读不到？

因为默认前缀是 VITE_。如果它是浏览器确实需要的公开地址，可以改成 VITE_API_KEY 这样的命名；如果它是真正的密钥，则不应该暴露给前端，应改成由后端代为调用。

VITE_ 变量能不能放 API Key？

不能把前缀当作保密措施。Vite 会在构建时把公开变量写入客户端资源，拿到网页资源的人也可能看到它。只有不敏感的公开配置才适合使用此前缀。

能不能直接读取 process.env？

在浏览器端代码里应优先使用 import.meta.env。Vite 的客户端替换规则围绕这个对象工作，服务端配置则应留在服务端运行时。