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_ANALYTICSfalse表示构建时开关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(): PromiseRuntimeConfig { 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 环境变量治理的核心是把构建时变量和运行时配置分开并明确哪些值会进入客户端产物。前端配置不是能读到就能随便用。变量的生命周期、可见性、缓存策略和回退方式都设计清楚发布才不会被一个小配置拖住。