一个项目要从测试环境切到生产,负责人改了 .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 并限制访问,要么只上传到错误监控平台。

怀疑密钥已经进过产物,先确认泄露范围,再轮换密钥,最后清理历史构建产物和 CDN 缓存。只删仓库里的 .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
解构出来的变量是 undefinedVite 只替换完整的 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 里可能攒了三十个变量,一半没人知道还有没有用。定期清理,给每个变量写一行注释说明用途和负责人;新加变量必须同时在示例文件和部署清单里出现,否则下一个人一定漏。

功能开关是另一个坑。用配置控制功能上线很灵活,但开关长期不清理,代码里会留下一堆「永远不会开」和「永远开」的分支。每个开关要有默认值、负责人和清理时间,发布稳定后就删掉。

最后,配置要尽量少。每多一个环境相关变量,就多一个部署时可能漏改的地方。能从代码推断的、能由后端返回的、能做成默认值的,都不要变成环境变量。

小结

前端产物是公开的打进 JS 的值用户都能看到;密钥留在服务端,前端走代理。
Vite 只暴露 VITE_ 前缀用完整表达式读取,别解构;区分 mode,不要拿 NODE_ENV 判断预发。
构建期简单,运行期灵活要跨环境晋升就选运行期;纯静态站点构建期就够,别过度设计。
配置要校验,失败要早一个入口解析、类型转换、必填检查;错了显示错误页,不要静默用默认值。
配置文件不能长缓存文件名固定就配 no-cache;发布时刷新 CDN,否则改配置等于没改。

当天可以动手的练习:

  1. 建 .env.staging,用 vite build --mode staging 构建,确认 MODE 和自定义变量的值。
  2. 故意把变量名去掉 VITE_ 前缀,观察代码里读到什么,再改回来。
  3. 写一个 config.json 加启动加载函数,把接口地址从构建期挪到运行期。
  4. 在构建产物里搜一个假密钥,确认 VITE_ 变量会被打进去,然后改成服务端注入。
  5. 给配置解析加布尔转换和必填校验,故意传 "false",确认按布尔值处理。

下一篇讲CSS 工程化。配置和部署解决的是「同一份代码怎么在不同环境跑」,样式解决的是「同一套界面怎么在多人协作下不打架」。两者都属于工程化里「把隐式约定变成显式规则」的部分,只是一个管运行环境,一个管样式作用域。