Vite 环境变量暴露边界与构建替换

Vite 的环境变量要先按“谁能看到”来分，而不是按文件名判断是否安全。带有 VITE_ 前缀的变量会通过 import.meta.env 暴露给客户端代码；生产构建时，这些引用还会被静态替换进前端资源。它适合放公开 API 地址、功能开关或构建标识，不适合放 API 密钥、数据库密码和签名私钥。

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

判断标准很简单：只要浏览器需要它，就假设用户、代理和抓包工具都能看到它。真正的秘密应留在服务端，由服务端代替浏览器访问受保护的资源。

先划分资产：哪些配置可以进浏览器

可以把配置分成三层。第一层是公开配置，例如前端请求的服务地址、应用显示名和非敏感功能开关；第二层是可观测标识，例如构建环境名、版本号或公开的追踪标识；第三层是服务端秘密，例如第三方服务密钥、数据库凭据和签名材料。前两层进入浏览器后仍要接受公开审视，第三层不能通过环境变量下发。

例如下面的文件可以表达“哪些值是公开的”，但注释里的秘密不能因为放在 .env 就变成私密：

# .env.production：只放可以公开给浏览器的构建配置
VITE_API_BASE=https://api.example.com
VITE_FEATURE_REPORT=true

# 不要这样写：构建后可能进入客户端资源
# VITE_PAYMENT_SECRET=replace-me

# 服务端秘密应由后端环境读取，不要加 VITE_ 前缀
PAYMENT_SECRET=server-only-value

这里的域名只是配置示例。实际项目应把服务端秘密交给后端或边缘函数，并让前端调用一个经过鉴权的业务接口。

识别暴露路径：前缀和 envPrefix 是入口

默认情况下，Vite 会把名称以 VITE_ 开头的变量挂到 import.meta.env 上；没有这个前缀的变量不会按这条默认规则暴露。项目可以用 envPrefix 自定义暴露前缀，因此安全审查不能只搜索 VITE_，还要查看 Vite 配置中的前缀设置。

// vite.config.js：只允许明确的公开前缀进入客户端代码
import { defineConfig } from 'vite'

export default defineConfig({
  // 前缀越具体，误把服务端变量下发的机会越小
  envPrefix: ['VITE_', 'PUBLIC_']
})

如果团队把前缀扩展为过于宽泛的值，保护边界就会变薄。命名本身不是权限控制，前缀只决定哪些值会被构建工具放进客户端；它不会替你判断字符串是不是密钥。

构建时发生什么：静态替换与模式文件

Vite 会加载通用文件和模式文件，例如 .env、.env.local、.env.production，并允许通过 --mode 选择构建模式。变量通常以字符串形式进入 import.meta.env，所以布尔值需要显式转换，不能把非空字符串直接当成布尔判断。

// config.ts：显式转换字符串，避免“false”被当成真值
const apiBase = import.meta.env.VITE_API_BASE
const reportEnabled = import.meta.env.VITE_FEATURE_REPORT === 'true'

// 生产构建选择对应模式文件，值会在构建阶段写入资源
console.log({ apiBase, reportEnabled })

“静态替换”意味着发布后再修改服务器上的 .env.production，通常不会改变已经生成的前端资源；要换值，需要重新构建，或者把这类配置改成由服务端接口在运行时返回。另一个细节是，动态拼接变量名不适合作为读取方式，构建工具需要看到明确的属性访问，才有稳定的替换边界。

按风险分级落地防护

低风险配置可以直接进入客户端，但仍应避免把内部网络拓扑、调试开关和不必要的路径暴露出去。中风险配置要限制作用域，例如只下发公开接口地址，并让后端继续执行权限判断。高风险秘密必须移出 Vite 客户端构建，改由后端保存和使用；前端拿到的只能是短期、最小权限的业务结果。

// server-route.js：服务端持有秘密，浏览器只调用业务接口
export async function createPayment(request) {
  // 从服务端进程环境读取，不把密钥拼进前端响应
  const secret = process.env.PAYMENT_SECRET
  if (!secret) throw new Error('缺少服务端支付配置')

  // 这里调用第三方服务并返回最小必要结果
  return callProvider({ secret, orderId: request.orderId })
}

发布前可以形成一张简短清单：搜索所有自定义前缀；确认每个前缀变量都能公开；检查 envPrefix 是否过宽；区分构建期值和运行期值；在构建产物抽查变量名而不是把秘密交给前端。

常见问题

没有 VITE_ 前缀就一定安全吗？

不是。它只是不会按 Vite 默认前缀规则暴露，代码、插件、接口响应或其他打包配置仍可能泄露；最终要看数据是否进入客户端可见范围。

把密钥放到 .env.local 能避免泄露吗？

它有助于避免提交到版本库，但如果变量带有暴露前缀并被前端引用，构建后仍可能进入客户端资源。文件位置和客户端可见性是两件事。

想在发布后改 API 地址怎么办？

不要把它误当成已生成资源里的动态配置。可以重新构建，也可以让前端启动时读取受控的运行时配置接口；后者仍不能返回服务端秘密。

总结：先按可见性划分资产，再检查暴露前缀，最后确认模式文件和静态替换是否符合发布方式。Vite 能帮助你把公开配置注入前端，但不会替你完成秘密管理。