Vite 环境变量为什么不会自动暴露给客户端

Vite 环境变量不会“自动全部暴露”给客户端，通常是因为变量名没有使用默认的 VITE_ 前缀。比如 VITE_PUBLIC_API_URL 可以通过 import.meta.env.VITE_PUBLIC_API_URL 读取，而 DB_PASSWORD 默认不会进入客户端代码。这个限制不是故障，而是 Vite 用来避免把服务端配置误打进前端包的一道边界。

先确认 Vite 只筛选带 VITE_ 的变量

排查时先不要修改配置，直接把“文件里存在”和“客户端可见”分开。Vite 会把符合前缀规则的值提供给 import.meta.env，并且环境变量按字符串处理；变量名没有 VITE_，在前端读取时得到 undefined 是预期结果。

// 只读取允许进入客户端的公开配置
const apiUrl = import.meta.env.VITE_PUBLIC_API_URL
const dbPassword = import.meta.env.DB_PASSWORD

console.log(apiUrl)       // 公开地址，仍然是字符串
console.log(dbPassword)   // undefined：默认前缀筛选不会暴露它

再核对 .env 文件与 mode 是否对应

如果变量已经带了 VITE_ 仍然读不到，第二层通常是文件或模式不匹配。Vite 默认在开发命令使用 development mode，构建命令使用 production mode；因此 .env.development 不会替代所有环境的 .env，vite build --mode staging 则会寻找 .env.staging。

1. 确认变量位于项目实际的 env 目录，而不是误放在父目录。
2. 确认执行命令的 mode，例如 vite --mode staging 或 vite build --mode staging。
3. 修改 .env* 后重启开发服务器，避免旧进程继续使用已加载的值。

还要注意优先级：命令行中已经存在的环境变量可能覆盖 env 文件中的同名值。遇到“文件写了新地址但页面还是旧地址”，先检查启动命令和 shell 环境，再怀疑 Vite 没有加载。

检查 envPrefix 是否被自定义

Vite 配置支持 envPrefix。一旦项目把默认的 VITE_ 改成其他前缀，排查重点就从“有没有 VITE_”变成“当前配置到底允许哪些前缀”。配置可以是字符串，也可以是字符串数组；这项设置不是读取服务端秘密的开关，而是定义哪些名字会进入客户端代码。

import { defineConfig } from 'vite'

export default defineConfig({
  // 只增加业务公开配置的前缀，不要把 SECRET_ 纳入其中
  envPrefix: ['VITE_', 'PUBLIC_']
})

建议全项目搜索 envPrefix，确认没有在多个配置文件或不同 mode 分支中产生不同结果。尤其不要为了让变量“能读到”就写一个过宽的前缀；前缀匹配到的值会随客户端构建产物一起发布。

把服务器秘密移出客户端代码

如果浏览器确实需要调用某个服务，应该只暴露公开地址或短期、受权限控制的业务结果。数据库密码、私钥、内部服务 Token 等不能通过改成 VITE_DB_PASSWORD 来“解决读取问题”，因为这样做只是把秘密从未定义变成可被用户查看。

更稳妥的结构是：浏览器读取 VITE_PUBLIC_API_URL，请求后端接口；后端在服务器环境读取 DB_PASSWORD，完成数据库操作后只返回必要数据。发布前还可以对构建产物执行一次关键词搜索，检查是否出现不应公开的变量名或值。搜索结果为空不能替代密钥轮换和权限控制，但能及时发现明显的命名错误。

• 读不到变量：先看前缀。
• 前缀正确仍为空：看 mode、文件位置和重启。
• 为了读到秘密而放宽前缀：停止修改，改用服务端接口。

常见问题

为什么 .env 里写了 VITE_API_URL，代码还是 undefined？

检查是否写成了 VITE_API_URL = value 这类带多余空格的格式、文件是否位于当前项目的 env 目录、启动命令是否使用了另一个 mode，并在改动后重启 Vite。

Vite 环境变量为什么都是字符串？

Vite 将读取到的自定义环境变量以字符串提供。数字、布尔值和 JSON 需要在业务代码中显式转换，并处理空值和格式错误。

能不能把 envPrefix 设置成空字符串？

不要这样做。过宽的前缀会让更多环境变量进入客户端构建结果，增加凭证泄露风险；应为公开配置设置清晰、专用的前缀。