Vite 环境变量治理：别把构建时配置当运行时开关

一、环境变量最容易被误用

Vite 项目里读取环境变量非常方便，import.meta.env一用就能拿到配置。但方便也带来误解：很多团队会把它当成运行时开关，以为改一下服务器环境变量就能让已经构建好的前端包改变行为。

实际上，Vite 的大部分环境变量是在构建时注入的。代码打包完成后，变量值已经固化到静态资源里。要改变它，通常需要重新构建，或者额外设计运行时配置加载机制。

二、先区分构建时和运行时

flowchart LR A[.env 文件] --> B[Vite 构建] B --> C[静态 JS/CSS] D[config.json] --> E[浏览器启动后请求] E --> F[运行时配置]

构建时变量适合影响代码分支、构建产物、第三方 SDK 是否打包。运行时配置适合影响 API 地址、灰度开关、租户配置、区域配置。两者混在一起，会导致发布事故：运维以为改了变量就生效，前端其实还在用旧包。

建议团队把变量命名也区分开。例如VITE_BUILD_ANALYTICS=false表示构建时开关，runtimeConfig.apiBaseUrl表示启动后读取的运行时配置。名字清楚，沟通成本会低很多。

工程上更需要注意的是，构建时变量和运行时配置在同一个文件里混写会带来隐藏陷阱。比如.env里同时放了VITE_API_URL和VITE_FEATURE_NEW_UI，前者显然需要运行时灵活切换，后者却适合构建时决定。混在一起让运维和前端对同一个变量的理解完全不同。建议从一开始就物理隔离：

// env.config.ts — 只有明确声明为运行时的配置才会在浏览器启动后重新加载 const BUILD_TIME = { APP_NAME: import.meta.env.VITE_APP_NAME, COMMIT_HASH: import.meta.env.VITE_COMMIT_HASH, } as const let runtimeConfig: RuntimeConfig | null = null export async function loadRuntime(): Promise<RuntimeConfig> { if (runtimeConfig) return runtimeConfig const res = await fetch("/config.json", { cache: "no-store" }) if (!res.ok) throw new Error(`配置加载失败: ${res.status}`) runtimeConfig = await res.json() return runtimeConfig }

这种拆分方式在实际项目中踩过的坑是：/config.json的请求如果被 CDN 缓存了旧的部署版本，前端拿到了旧 URL 去调新部署的后端接口，就会出 404 或鉴权异常。解法是在 config.json 上加cache: "no-store"或文件名带 hash，确保每次页面刷新都能拉到最新配置。

三、不要把敏感信息塞进前端变量

const apiKey = import.meta.env.VITE_PRIVATE_API_KEY

只要变量以VITE_暴露给客户端，它就可能出现在打包产物里。前端环境变量不适合存放密钥、数据库密码、服务端令牌。即使变量名里写了 private，也不会真的变私密。

可以建立一个环境变量声明文件：

type PublicEnv = { VITE_APP_NAME: string VITE_RELEASE_VERSION: string VITE_ENABLE_MOCK: "true" | "false" }

再配合校验函数，在启动时检查必填项：

const required = ["VITE_APP_NAME", "VITE_RELEASE_VERSION"] as const for (const key of required) { if (!import.meta.env[key]) { throw new Error(`Missing env: ${key}`) } }

这能让问题在构建或本地启动阶段暴露，而不是上线后才发现页面调用了空地址。

四、运行时配置要有缓存和回退策略

如果确实需要运行时配置，可以让页面启动时请求/config.json。但这又带来新问题：配置文件加载失败怎么办，是否允许缓存，版本如何匹配，CDN 是否会返回旧配置。

{ "apiBaseUrl": "https://api.example.com", "featureFlags": { "newDashboard": false }, "release": "2026.07.04" }

运行时配置应尽量小而稳定，适合放公开信息。前端启动时可以先读取配置，再挂载应用；如果配置失败，展示明确错误页，而不是让应用在半初始化状态下运行。

还要把配置版本写入日志和错误上报。排查线上问题时，仅知道前端包版本不够，还要知道当时加载的是哪份运行时配置。尤其是多环境、多区域部署时，这个信息非常关键。

部署新配置时建议走灰度：先更新一个次要子域名的 config.json，验证无误后再切主域名。直接全量推配置，如果有一个 API 地址拼写错误，所有页面启动即白屏，且因为配置加载失败日志没机会上报，排查会非常困难。

五、总结

Vite 环境变量治理的核心，是把构建时变量和运行时配置分开，并明确哪些值会进入客户端产物。

前端配置不是能读到就能随便用。变量的生命周期、可见性、缓存策略和回退方式都设计清楚，发布才不会被一个小配置拖住。