Vite import.meta.env 控制客户端变量暴露范围的方法

如果目标是控制 Vite 客户端能看到哪些环境变量，核心做法是把“公开配置”和“服务端密钥”分成两套命名空间：默认只使用 VITE_ 前缀的变量，必要时再通过 envPrefix 增加一个明确的公开前缀。凡是会进入 import.meta.env 的值，最终都有可能被打包进浏览器资源，因此前缀只是暴露边界，不是加密手段。

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

判断一项配置能不能放在 Vite 客户端环境文件里的标准很简单：用户能在浏览器中拿到它，就不能把它当作秘密。API 密钥、数据库密码和服务端签名材料应由后端持有，前端只拿公开地址、功能开关或非敏感标识。

先把客户端暴露边界画清楚

Vite 会把环境变量加载为字符串，并通过 import.meta.env 提供给经过 Vite 处理的代码。默认规则是：名称以 VITE_ 开头的变量会暴露给客户端，其他普通变量不会直接出现在客户端环境对象中。MODE、DEV、PROD 和 BASE_URL 等内置值属于另一组运行信息。

这里的“暴露”不是把值放到某个公开接口，而是构建时把值替换进前端资源。只要浏览器能下载 JavaScript，用户就有机会读取其中的公开配置。因此，下面这张结构图里的服务端密钥区域必须停在客户端边界之外。

默认模式：只让 VITE_ 变量进入客户端

在项目根目录可以这样区分公开配置和服务端配置：

# .env
# 这个地址会被前端代码读取，因此只能放公开入口
VITE_API_BASE_URL=https://api.example.com

# 这个值留给服务端进程，不能在 import.meta.env 中取用
SERVER_SIGNING_SECRET=change-me-on-the-server

客户端读取时要使用完整、静态的属性名：

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
// 公开地址可以进入浏览器资源，服务端请求仍需在后端完成

const signingSecret = import.meta.env.SERVER_SIGNING_SECRET
// 非 VITE_ 变量不会按默认规则暴露给客户端

console.log({ apiBaseUrl, signingSecret })
// 这里仅用于说明读取结果，生产代码不要打印敏感数据

这个模式的好处是边界容易审查：看到 VITE_ 就知道它是公开配置。不要因为变量写在 .env.local 就把它当成秘密；.local 主要表达本地文件不应提交到版本库，并不能阻止构建工具把已匹配的公开变量打包给浏览器。

需要自定义命名空间时，用 envPrefix 收窄规则

如果团队不想使用 VITE_，可以在 Vite 配置里指定公开前缀。关键取舍是“增加一个明确前缀”，而不是把前缀配置成空字符串或过于宽泛的值：

import { defineConfig } from 'vite'

export default defineConfig({
  // 只有这两个前缀表示允许进入客户端的公开配置
  envPrefix: ['VITE_', 'PUBLIC_'],
})

此时 PUBLIC_ANALYTICS_ID 可以被客户端读取，但 DB_PASSWORD 仍然不会因为存在于环境文件中就自动进入前端。配置自定义前缀后，团队要把它当成公开 API 约定：前缀下的所有值都默认可见，不要再把同一前缀用于私密字段。

这里最容易出现的反例是设置一个过宽的前缀，例如把所有变量都暴露。这样虽然减少了“为什么取不到”的排查成本，却把安全边界交给了每个环境文件的命名习惯，后续很容易把数据库、云厂商或签名凭据一起打进资源。

用 mode 管理不同环境的公开配置

Vite 会按 mode 加载环境文件。通常可以把公共公开配置放到 .env，把本地覆盖放到 .env.local，再用 .env.staging 和 .env.production 表达不同部署环境：

# .env.staging
# 预发布环境的公开接口地址
VITE_API_BASE_URL=https://staging-api.example.com

# .env.production
# 生产环境的公开接口地址
VITE_API_BASE_URL=https://api.example.com

构建预发布包时显式指定 mode：

# 使用 staging 文件生成预发布前端资源
npm run build -- --mode staging

下面的关系图强调了 mode 的职责：它选择环境文件和构建上下文，但不会把敏感值变成安全值。无论是 development、staging 还是 production，只要变量匹配公开前缀，最终都应按“浏览器可见”来设计。

代码读取要保持静态，类型要自己转换

Vite 在构建时会做静态替换，所以应直接写出完整的环境变量名。不要把键名拼到 import.meta.env 后面期待运行时动态查找：

const envKey = 'VITE_API_BASE_URL'
// 动态键不适合作为 Vite 构建时替换的入口
const dynamicValue = import.meta.env[envKey]

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
// 使用完整属性名，构建器可以明确替换这个公开变量

此外，环境变量读取结果都是字符串。功能开关和数字配置要在边界处转换，不要把非空字符串直接当成布尔值：

const debugEnabled = import.meta.env.VITE_DEBUG === 'true'
// 明确比较字符串，避免 "false" 被当成真值

const retryCount = Number(import.meta.env.VITE_RETRY_COUNT ?? '3')
// 设定默认值后再转换，避免配置缺失时得到 NaN

如果项目使用 TypeScript，可以在 src/vite-env.d.ts 中补充公开变量的类型提示：

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_DEBUG?: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

类型声明只改善编辑器提示和编译期检查，不改变浏览器可见性，也不会替代前缀设计。

排查“变量没生效”时按四个边界检查

1. 看命名：变量是否确实使用 VITE_ 或配置中的自定义公开前缀？如果没有，按默认规则读取不到是预期行为。
2. 看 mode：当前命令是否加载了预期的 .env.[mode]？vite build 默认使用 production，预发布需要显式指定 --mode staging。
3. 看优先级：mode 专用文件会覆盖通用文件，已经存在于启动进程中的环境变量优先级更高。不要只改文件却忽略了命令行或 CI 注入值。
4. 看生命周期：修改环境文件后重启 Vite 开发服务器。已生成的生产资源不会因为文件变化自动重新构建。

如果变量已经暴露但不该暴露，不要在前端增加“隐藏字段”或简单混淆。撤掉公开前缀、把敏感操作移到服务端接口，并重新构建资源，才是真正收回边界。

一张表判断变量放在哪里

结论：前缀是公开配置的门，不是秘密保险箱

Vite 的客户端变量边界可以归纳为三条：默认只让 VITE_ 进入客户端；自定义 envPrefix 时只增加清晰、有限的公开前缀；所有命中公开前缀的值都按可见数据处理。mode 负责选择环境文件，类型声明负责提示，二者都不能把客户端资源变成密钥存储。

相关问题

为什么 .env.local 里的变量在浏览器中仍然能看到？

因为 .local 主要用于本地覆盖和版本控制约定，匹配公开前缀的值仍会被 Vite 注入客户端。不要把文件名后缀当成安全边界。

自定义 envPrefix 后，原来的 VITE_ 变量还有效吗？

应以当前 Vite 版本的配置规则为准，并把公开前缀明确写进团队约定。实践上不要用过宽的前缀，也不要让同一变量同时承担公开和私密两种用途。

能不能在前端读取数据库密码再调用数据库？

不应该。只要前端需要数据库密码，密码就会随资源或请求暴露。正确边界是由服务端持有凭据，前端调用经过授权的服务端接口。