一个项目要从测试环境切到生产,负责人改了 .env.production 里的接口地址,重新构建,上传,刷新。页面能打开,但所有请求都打到测试库。查了半天,代码里写的是:
const apiBase = process.env.API_URL;
浏览器里没有 process,这行在运行时直接报错,或者被打包工具替换成 undefined。改成 import.meta.env.VITE_API_URL 之后还是空,因为 .env 里的变量名写成了 API_URL,没有 VITE_ 前缀,Vite 不会把它暴露给前端。
更吓人的是另一类:有人把第三方服务的密钥写进 VITE_ 开头的变量里,构建后直接出现在 JS 产物中。打开浏览器开发者工具,搜一下就能拿到。前端没有「服务端环境变量」这种东西,所有打进产物的值,用户都能看到。
这篇讲什么:前端项目里的「环境」到底是什么、Vite 的 mode 和 VITE_ 前缀怎么工作、构建期注入和运行期配置各自适合什么场景、同一份产物怎么部署到多个环境、哪些配置必须校验、哪些东西绝对不能进前端。读完你能做到:不再把 .env 当秘密仓库;让测试和生产跑同一份构建产物;配置错了在启动时就报出来,而不是等用户点页面。
版本说明:本文按 Vite 8 写,import.meta.env 的行为和 Vite 5 以后一致。运行期配置的方案不依赖具体框架,静态站点和单页应用都能用。
前端没有「环境」,只有构建产物和运行时输入
服务端应用可以在启动时读环境变量,同一个镜像换个 API_URL 就能跑在不同环境。前端不一样:代码最终变成一堆静态文件,浏览器拿到什么就是什么。所谓「环境」,通常只是构建时写死的一个常量。
这就带来一个根本矛盾:
构建期注入
把值编译进 JS。简单、快、没有额外请求,但每个环境要单独构建一次,产物不可互换,密钥也会进包。
运行期配置
启动时从文件或接口读配置。一份产物到处部署,改配置不用重新构建,但多一次请求,也多一个失败点。
先想清楚你的项目属于哪一类:纯静态、没有后端地址变化的站点,构建期注入就够了;需要「构建一次、测试预发生产逐级晋升」的应用,必须把环境相关的东西挪到运行期。两者的分界线,是「同一份产物能不能在所有环境跑」。
Vite 的 env:mode、前缀和加载顺序
Vite 用 mode 区分环境,默认开发是 development,构建是 production。你可以显式指定:
vite build --mode staging
它会按固定顺序加载这些文件,后面的覆盖前面的:
| 文件 | 什么时候加载 | 是否提交 |
|---|---|---|
.env | 所有模式 | 提交,放公共默认值 |
.env.local | 所有模式,本地覆盖 | 不提交,放个人配置 |
.env.[mode] | 指定模式 | 提交,放环境差异 |
.env.[mode].local | 指定模式的本地覆盖 | 不提交 |
只有 VITE_ 开头的变量会被暴露给客户端代码,通过 import.meta.env 访问。MODE、BASE_URL、DEV、PROD 是内置的,不用自己声明。
# .env.staging
VITE_API_BASE=/api
VITE_FEATURE_NEW_CHECKOUT=false
const base = import.meta.env.VITE_API_BASE;
const isProd = import.meta.env.PROD;
const mode = import.meta.env.MODE; // "staging"
三个高频坑:
- 解构不生效。
const { VITE_API_BASE } = import.meta.env拿不到值。Vite 是在编译时做文本替换,只认完整的import.meta.env.VITE_API_BASE写法。 - 别用
NODE_ENV区分环境。vite build --mode staging构建时,NODE_ENV仍然是production,真正变化的是MODE。用NODE_ENV判断「是不是预发」,一定判断错。 - 不要在运行时读
process.env。浏览器没有这个对象。要么用import.meta.env,要么在构建配置里用define显式替换。
还需要在配置里读非 VITE_ 变量时,用 loadEnv。第三个参数传空字符串表示不过滤前缀:
import { defineConfig, loadEnv } from "vite";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "");
return {
define: {
__BUILD_TIME__: JSON.stringify(new Date().toISOString()),
__APP_ENV__: JSON.stringify(env.APP_ENV ?? mode)
}
};
});
注意 define 的值必须是 JSON 字符串,否则替换进去的是裸文本。也注意它只能替换你代码里的标识符,不能改变第三方库内部对 process.env 的访问;那种情况要靠别名或打包配置处理。
运行期配置怎么落地
常见做法有三种,按复杂度从低到高:
第一种,public 目录下的静态配置文件。放一个 public/config.json,构建时原样复制到产物根目录,文件名不带哈希。应用启动先 fetch 它,拿到配置再初始化。
async function loadConfig() {
const url = `${import.meta.env.BASE_URL}config.json`;
const res = await fetch(url, { cache: "no-store" });
if (!res.ok) throw new Error(`配置加载失败: ${res.status}`);
return parseConfig(await res.json());
}
注意 BASE_URL。部署在 /admin/ 下时,配置文件的路径也要带前缀,否则 404。
第二种,启动脚本生成 config.js。镜像启动时把环境变量写进一个全局对象,页面用 <script src="/config.js"> 同步加载。好处是没有额外请求、不用等异步;坏处是污染全局,且生成脚本要小心转义。
#!/bin/sh
set -eu
API_BASE="${API_BASE:-/api}"
cat > /usr/share/nginx/html/config.js <<EOF
window.__APP_CONFIG__ = {
apiBase: "${API_BASE}",
sentryDsn: "${SENTRY_DSN:-}",
features: { newCheckout: ${NEW_CHECKOUT:-false} }
};
EOF
exec nginx -g "daemon off;"
这段脚本有两个风险:值里带引号会破坏 JS 语法,值里带 ${} 会被 shell 展开。生产环境更稳的做法是用 jq 或一个小 Node 脚本序列化成 JSON,而不是拼字符串。无论哪种,生成完都要能在浏览器里正常解析。
第三种,服务端注入 HTML。nginx 或应用服务器在返回 index.html 时替换占位符。它适合多页应用或 SSR,配置不需要额外请求;代价是 HTML 不能被 CDN 长时间缓存,部署链路也更复杂。
三种方案的共同要求:配置文件不能被长缓存。它通常放在 public 下,文件名没有哈希,一旦被 CDN 缓存一年,改配置等于没改。响应头至少是 no-cache,或者每次发布主动刷新。
配置要校验,错了要早报
环境变量全是字符串,类型、必填、格式都没人保证。典型事故:VITE_FEATURE_X="false" 被当成真值,因为非空字符串在 JavaScript 里就是 true;接口地址少了协议,页面请求变成相对路径;超时时间写成 "30s",parseInt 得到 30,但单位被当成毫秒。
做法是「一个入口、一次解析、失败即停」:
interface AppConfig {
apiBase: string;
sentryDsn?: string;
features: { newCheckout: boolean };
}
function parseConfig(raw: unknown): AppConfig {
if (typeof raw !== "object" || raw === null) {
throw new Error("配置必须是对象");
}
const value = raw as Record<string, unknown>;
if (typeof value.apiBase !== "string" || !value.apiBase.startsWith("/")) {
throw new Error("apiBase 必须是 / 开头的路径");
}
const features = value.features as Record<string, unknown> | undefined;
if (typeof features?.newCheckout !== "boolean") {
throw new Error("features.newCheckout 必须是布尔值");
}
return {
apiBase: value.apiBase,
sentryDsn: typeof value.sentryDsn === "string" ? value.sentryDsn : undefined,
features: { newCheckout: features.newCheckout }
};
}
校验失败时,不要静默用默认值继续跑。默认值会把「配置错了」变成「功能悄悄不对」,排查成本高得多。正确做法是显示一个明确的错误页,写清楚缺了哪个字段、当前部署读到的值是什么(注意不要打印密钥),同时上报监控。
类型化的配置模块还有个好处:业务代码只从这一个模块拿配置,不在各处散落 import.meta.env.VITE_XXX。以后从构建期切到运行期,只需要改这一个文件。
多环境:矩阵要小,命名要直白
环境不是越多越好。常见的最小集合是四个:本地、测试、预发、生产。再多通常意味着流程有问题,而不是环境有必要。
| 环境 | 用途 | 数据 | 谁能部署 |
|---|---|---|---|
| 本地 | 开发自测 | 本地 mock 或测试库 | 个人 |
| 测试 | 联调、QA | 测试数据 | 合并后自动 |
| 预发 | 接近生产的验收 | 脱敏数据 | 自动或一键 |
| 生产 | 真实用户 | 真实数据 | 审批后发布 |
命名要避免「test2」「new-prod」这种临时环境。临时环境一旦存在超过一个月,就会有人把它当正式环境用,配置和密钥也跟着扩散。预览环境可以按 PR 动态创建,合并后自动销毁,命名带上 PR 号,不要手工维护。
每多一个环境,就多一套配置、一套密钥、一套监控。维护成本是乘法,不是加法。能合并的就合并,比如测试和预发共用一个后端,只在前端配置上区分;不能合并的,写清楚谁能改、多久清理一次。
密钥的边界:前端产物是公开的
这一节值得单独强调。任何被打进前端产物的值,用户都能拿到:打开 DevTools、下载 JS、搜字符串,几秒钟的事。所以下面这些东西绝对不能放在 VITE_ 变量里:
- 服务端 API 密钥、签名密钥、数据库连接串。
- 第三方服务的私密 token,除非它本来就设计成公开且有限流。
- 内部接口的访问凭证、管理后台的固定口令。
- 任何「泄露后能直接造成损失」的值。
需要在前端调用第三方服务时,正确做法是经过自己的后端代理:前端调自己的接口,后端拿着密钥去调第三方。密钥留在服务端,前端只拿到业务结果。确实必须公开的 key(比如地图的展示 key),要配置域名白名单、用量限额和告警,并接受它随时可能被滥用。
还有一个容易忽略的泄露渠道:sourcemap。开了 sourcemap 又公开部署,等于把源码和里面的常量一起送出去。要么用 hidden map 并限制访问,要么只上传到错误监控平台。
.env 没用,旧版本的 JS 还在线上。完整场景走查:一份镜像,三个环境
背景是一个容器化部署的单页应用,要求「测试验证过的镜像,直接晋升到预发和生产」,不能每个环境重新构建。原来的做法是三个环境各跑一次 vite build,经常出现测试通过、生产白屏。
第一步,把环境相关配置从构建期挪到运行期。构建时只保留绝对不变的东西,比如构建时间、版本号、前端路由模式。接口地址、监控地址、功能开关,全部改成启动时读取。
第二步,在镜像里加启动脚本,用环境变量生成 config.js。镜像本身不含任何环境地址,同一个镜像可以在三个环境启动。Kubernetes 或 Docker Compose 只需要注入环境变量,不需要重新构建。
第三步,给配置加校验。应用启动先加载配置,校验失败就渲染错误页并上报,不进入业务。上线第一周,预发环境因为 SENTRY_DSN 为空报了配置错误,运维补上后恢复;如果没有校验,这个空值会一直静默,直到真的出错才发现监控没接上。
第四步,处理缓存。config.js 放在静态目录,文件名固定,nginx 给它加 no-cache;带哈希的 JS 和 CSS 继续长缓存。发布后 CDN 只刷新 config.js 和 HTML,不刷新整个目录。
第五步,修一个真实事故。某次生产发布后,部分用户请求打到预发接口。查配置,API_BASE 被写成了预发地址;再查,是运维复制了预发的部署清单,只改了镜像 tag,没改环境变量。后来在部署模板里加了「生产环境必须显式声明 API_BASE,不允许使用默认值」,并在冒烟检查里请求一个只存在于生产的接口,确认返回的不是预发数据。
最终形态:一份镜像、三个环境、配置在启动时注入、校验失败即停、配置文件不缓存。发布流程从「每个环境构建一次」变成「构建一次,晋升三次」,每次晋升只需要改环境变量和重启容器。
错误现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
import.meta.env.VITE_X 是 undefined | 变量没有 VITE_ 前缀,或 .env 文件名与 mode 不匹配 | 确认文件名、变量前缀,打印 import.meta.env.MODE |
解构出来的变量是 undefined | Vite 只替换完整的 import.meta.env.VITE_X 表达式 | 改成逐行完整写法,别解构 |
| 密钥出现在构建产物里 | 用了 VITE_ 前缀,值被编译进 JS | 在 dist 里搜变量值,确认泄露范围后轮换 |
| 预发构建跑到生产,或反过来 | 每个环境重新构建,或模式参数传错 | 看构建命令的 --mode,对比产物里的环境标识 |
config.json 404 | 文件没被复制到产物,或路径没带 BASE_URL | 直接访问配置地址,确认部署目录和前缀 |
| 改了配置,用户还是旧值 | 配置文件被 CDN 或浏览器长缓存 | 看响应头 Cache-Control,刷新 CDN |
| 布尔开关永远为真 | 环境变量是字符串,"false" 也是真值 | 在配置解析层显式转换并校验类型 |
浏览器报 process is not defined | 代码或依赖在运行时读 Node 全局变量 | 改用 import.meta.env,或在构建配置里处理该依赖 |
边界与代价
运行期配置不是默认答案。一个纯静态博客,接口地址固定,构建期注入最简单,少一次请求、少一个失败点。只有当「同一份产物要跨环境晋升」成为硬需求时,运行期配置的复杂度才值得付。判断标准:如果每个环境单独构建不会带来事故,就别折腾。
运行期配置多了一个启动依赖。配置文件加载失败,应用就起不来;网络慢,首屏就多等一个往返。要给它设置超时、做失败提示,最好能在 HTML 里内联一个最小兜底配置。别让它成为白屏的新原因。
环境变量本身也容易失控。项目跑两年,.env 里可能攒了三十个变量,一半没人知道还有没有用。定期清理,给每个变量写一行注释说明用途和负责人;新加变量必须同时在示例文件和部署清单里出现,否则下一个人一定漏。
功能开关是另一个坑。用配置控制功能上线很灵活,但开关长期不清理,代码里会留下一堆「永远不会开」和「永远开」的分支。每个开关要有默认值、负责人和清理时间,发布稳定后就删掉。
最后,配置要尽量少。每多一个环境相关变量,就多一个部署时可能漏改的地方。能从代码推断的、能由后端返回的、能做成默认值的,都不要变成环境变量。
小结
no-cache;发布时刷新 CDN,否则改配置等于没改。当天可以动手的练习:
- 建
.env.staging,用vite build --mode staging构建,确认MODE和自定义变量的值。 - 故意把变量名去掉
VITE_前缀,观察代码里读到什么,再改回来。 - 写一个
config.json加启动加载函数,把接口地址从构建期挪到运行期。 - 在构建产物里搜一个假密钥,确认
VITE_变量会被打进去,然后改成服务端注入。 - 给配置解析加布尔转换和必填校验,故意传
"false",确认按布尔值处理。
下一篇讲CSS 工程化。配置和部署解决的是「同一份代码怎么在不同环境跑」,样式解决的是「同一套界面怎么在多人协作下不打架」。两者都属于工程化里「把隐式约定变成显式规则」的部分,只是一个管运行环境,一个管样式作用域。