环境变量怎么管理:共用配置、个人覆盖与框架差异(1):共用默认值、个人覆盖与部署配置
- 共用默认值、个人覆盖与部署配置(当前)
- 前后端框架的加载与公开边界
两个人开发同一个项目,API 地址和功能开关大体相同,代理端口、调试服务和测试账号却各有各的设置。如果这些值都放在一份受 Git 追踪的 .env 里,改一次本机代理就会出现一个不该提交的 diff;顺手提交后,另一位开发者拉取代码,还要把自己的配置改回来。
把所有 .env 文件都忽略,又会遇到另一种麻烦:项目新增一个共用配置,代码已经同步,配置却还要另行通知。.env.example 如果只在初始化时复制一次,也可能慢慢落后于应用实际需要的字段。
我更倾向于先按维护责任区分配置:需要协作者共同维护的默认值随代码追踪,只对某个人生效的覆盖值留在本机。这个原则在 Vite、Nuxt、Next.js,甚至不使用 .env 的框架里都成立;不同的是,共用配置可能放在 .env,也可能放在配置模块、schema 或其他默认配置文件中。
文件名本身还回答不了全部问题。.env.local 是否会被读取、谁覆盖谁、变量是否进入浏览器,以及上线后能不能修改,都由后续工具链决定。
先区分配置归属和敏感性
这里的「个人配置」指配置只服务于某位开发者,例如本机代理地址、个人调试端口和临时连接目标;「服务端私密配置」指值不能向浏览器或无权访问的人公开,例如数据库密码。两者可能重合,也可能完全不同。
整个团队共用的一把服务端密钥,在协作范围上是共用的,在敏感性上仍然是秘密。个人选择的界面调试开关,则可以完全不敏感,只是不该影响同事。
图中右上角的共用密钥,是最容易被漏掉的一类。团队需要有共同的获取和授权机制,但这不自动要求把明文值提交到 Git。没有特殊约定时,可以共享字段定义,把真实值通过部署平台、本机文件或密钥管理系统提供。
所以,更准确的约定是:
Git 中维护需要共同评审、同步和复现的配置;本机覆盖文件维护个人差异。敏感值是否适合进入仓库,再按它的权限、存储方式和项目约定单独判断。
这也解释了为什么「没被 Git 追踪」不能直接等同于「秘密」。.gitignore 管的是版本管理,无法阻止构建工具把某个值写进公开的 JavaScript。
.env 文件由谁读取
严格说,环境变量是进程运行环境中的键值;.env 是一种保存这些键值的文本文件。创建文件之后,还需要有加载器解析它,再交给进程环境、配置对象或构建器。
例如,同样是 Node.js 程序,以下两个命令就不同:
# 第一个命令不主动加载 .env;第二个显式加载
node server.mjs
node --env-file=.env server.mjs
Node.js 的 --env-file 文档还规定:启动前已经存在的环境变量优先;指定多个文件时,后面的文件覆盖前面的文件。同一个文件名,换一个加载器,优先级就可能改变。
对一个具体项目,至少要分别确认这些约定:
- 哪些配置需要共同维护,哪些属于个人覆盖。
- 实际启动入口读取哪些文件,以什么顺序合并。
- 哪些值只在服务端使用,哪些会公开给浏览器。
- 哪些值在构建时确定,哪些在服务启动或处理请求时读取。
文件命名只是这些约定的表达方式之一。
Vite 与 Nuxt 的差异发生在哪里
Nuxt 默认使用 Vite 构建前端,但 Nuxt 的配置初始化、服务端运行和客户端配置传递都有自己的入口。使用 Vite,并不意味着应用的所有配置都由 Vite 的 .env 加载器管理。
Vite 按模式合并文件
Vite 的环境文件规则覆盖四类文件:.env、.env.local、.env.[mode] 和 .env.[mode].local。默认开发模式是 development,默认构建模式是 production;指定其他模式时使用 --mode。
这里有一个很容易记反的细节:Vite 的模式文件优先于通用本机文件。.env.production 中的同名字段,会覆盖 .env.local。要覆盖某个模式的配置,应使用对应的 .env.production.local,或在启动前注入环境变量。
Next.js 也支持这些文件名,但中间两层的优先级不同。
图中从上往下查找同名变量,最先找到的值生效。Vite 与 Next.js 的 .env.local 位置不同,所以不能把一张优先级表套到所有项目。
文件名中的 production 也需要写完整。Vite 默认生产构建读取 .env.production;.env.prod 是自定义模式文件,要配合 vite build --mode prod 使用。mode 与 NODE_ENV 是两个概念,不能仅通过把 NODE_ENV 改成 prod 来替代模式选择。
Nuxt 先加载自己的配置
Nuxt 4 的 .env 文档规定,开发、构建和生成阶段默认加载根目录 .env。选择其他文件时,可以显式运行:
# 在项目根目录运行,选择本次开发使用的配置文件
pnpm exec nuxt dev --dotenv .env.local
这里的 --dotenv 是选择文件,不承诺把 .env 和 .env.local 自动叠加。
对应的 Nuxt v4.6.2 配置加载源码会先调用 c12 的 setupDotenv,填充进程环境,再继续解析配置。以下保留函数外层和环境文件加载分支,省略了 layer 扫描、schema 解析及后续合并逻辑:
// nuxt/nuxt@v4.6.2/packages/kit/src/loader/config.ts:239-270(节选)
export async function loadNuxtConfig(opts: LoadNuxtConfigOptions): Promise<NuxtOptions> {
// ...省略 layer 扫描与配置合并准备
if (opts.dotenv !== false) {
await setupDotenv({
cwd: opts.cwd || process.cwd(),
...(typeof opts.dotenv === 'object' ? opts.dotenv : {}),
});
}
// ...省略 schema 解析与后续配置加载
}
图中比较的是两个配置入口。Nuxt 后续仍会使用 Vite 编译应用;模块或自定义 Vite 配置也可能再引入其他环境文件。Nuxt 的配置初始化有独立加载流程,因此不能把 Vite 的自动合并规则当作 Nuxt runtimeConfig 的默认契约。
用同一组文件检查结果
下面的隔离实验使用 Node.js 26.12.0、Vite 8.3.4 和 Nuxt 4.6.2。所有值都是演示字符串;Vite 侧调用 loadEnv('production', ...),Nuxt 侧调用配置初始化使用的 loadNuxtConfig,每个场景运行在独立子进程中。
| 文件 | 演示字段 |
|---|---|
.env |
PROBE_VALUE=base、PROBE_BASE=shared |
.env.local |
PROBE_VALUE=personal、PROBE_LOCAL=personal-only |
.env.production |
PROBE_VALUE=production |
.env.production.local |
PROBE_VALUE=production-personal |
结果中只保留这三个演示字段,null 表示没有读到该字段:
| 加载入口 | PROBE_VALUE |
PROBE_BASE |
PROBE_LOCAL |
|---|---|---|---|
Vite,production 模式 |
production-personal |
shared |
personal-only |
| Vite,启动前注入同名变量 | injected |
shared |
personal-only |
| Nuxt,默认配置加载 | base |
shared |
null |
Nuxt,显式选择 .env.local |
personal |
null |
personal-only |
| Node,显式依次加载基础与本机文件 | personal |
shared |
personal-only |
Nuxt 改选本机文件后,PROBE_BASE 消失了。这是「选择一份文件」与「合并多份文件」的可观察区别。反过来,如果本机文件只填写个人密钥,而基础文件保存共用 API 地址,不能只加一个 --dotenv .env.local 就认为两者都会生效。
实验输入与结果快照保留了版本、输入和输出。这次验证的是加载函数与 Node CLI,没有启动完整应用,也不代表验证了每个平台适配器的生产行为。
框架的文件加载、变量注入和模板 Git 忽略规则需要分别核对;Vue 或 React 本身不为所有应用规定同一套 env 协议。后端也要表达共用默认值与部署差异,但可以使用配置模块、profile 或 settings 文件,不必照搬同一组 dotenv 文件名。各框架的具体入口见框架加载与公开边界篇。
构建时确定的值,上线后不会自动重读
.env.local 中的 local 表达本机归属,不能直接推导变量在运行时读取。Vite 的客户端公开变量即使来自本机文件,也可能在构建时写成字符串;静态产物被部署到哪里,这个字符串就跟到哪里。
如果目标是同一份产物部署到测试和生产环境,服务端动态读取宿主环境通常更合适。浏览器需要的非敏感配置,可以由服务端白名单接口或页面初始化数据提供;若项目只有静态文件,则需要构建不同产物,或另外设计公开的运行时配置文件及缓存策略。
公开前缀也不是安全包装。VITE_*、NEXT_PUBLIC_*、PUBLIC_*、Nuxt runtimeConfig.public,以及显式声明的客户端字段,表达的都是让客户端获得值的意图。把真实密钥移到 .env.local,不会撤销这个暴露意图。
项目里怎样落地这套约定
我会先检查项目已有加载方式,再决定文件名。对于已经采用 Vite 四文件模式、且允许追踪非敏感共用配置的项目,可以使用下面的划分:
| 文件 | 内容 | 版本管理 |
|---|---|---|
.env |
共用默认值 | 追踪 |
.env.production |
生产环境共用配置 | 追踪 |
.env.local |
个人通用覆盖 | 忽略 |
.env.production.local |
个人对生产模式的覆盖 | 忽略 |
.env.example |
字段说明或占位示例 | 追踪 |
对应规则放进项目根目录 .gitignore:
# 本机环境覆盖
.env.local
.env.*.local
已有 *.local 且还需要忽略其他本机配置时,继续保留即可。共用文件中放 API 基址、非敏感开关和可复现的默认值;个人端口、代理和调试账号留在本机覆盖文件。服务端凭据按项目授权通过本机或部署渠道提供。
如果项目沿用 Nuxt、Next.js、Laravel 等模板的整体忽略策略,也可以继续保留,把共用默认值放在框架配置模块中,并维护 .env.example 或 schema。示例文件需要说明复制和加载方式;更新字段时同步更新配置契约,不能依赖每个人永远记得重新复制。
让启动命令承担加载约定
Nuxt 的 --dotenv 用于选择一份文件。需要叠加共用与本机配置时,应在应用入口之前完成合并,或者采用已有的加载工具,并在项目脚本中固定顺序。
例如,Node.js 22.9+ 可以显式执行下面的命令,基础文件必需,本机文件可选:
# server.mjs 是项目的服务端入口;后面的文件覆盖前面的文件
node --env-file=.env --env-file-if-exists=.env.local server.mjs
将实际入口写进 package.json 的启动脚本后,协作者只需执行统一命令。这个例子展示的是 Node 的加载机制;接入 Nuxt、测试工具或其他 CLI 时,还要检查后续是否存在第二次加载,以及它是否尊重已经注入的进程变量。
README 至少记录实际文件名、优先级、默认启动命令、必须提供的字段,以及部署环境在哪里注入。变量名可以作为契约,真实密钥不需要出现在说明和日志里。
检查 Git 规则确实命中
Git 的忽略机制只影响未追踪文件,不会把已经追踪的 .env.local 自动移出索引。验证时要同时检查共用文件没有被误忽略、本机文件确实被忽略:
# 在项目根目录执行;共用文件预期没有匹配输出
git check-ignore -v --no-index -- .env .env.production .env.example
# 本机覆盖预期输出命中的忽略规则
git check-ignore -v --no-index -- .env.local .env.production.local
这里第一条命令没有匹配时退出码为 1,属于预期结果。--no-index 能检查已追踪路径是否匹配规则;再用 git ls-files -- .env.local 确认索引状态。确实需要移出索引时,git rm --cached -- .env.local 会保留工作区文件,但对应提交仍需要按项目流程评审。
校验字段,避免静默回退
文件加载成功,只说明解析完成。端口范围、URL 格式、布尔值转换,以及生产环境必须提供的字段,还要在应用入口校验。字符串 "false" 转成 JavaScript 布尔值仍然为真,不能直接用 Boolean(process.env.FEATURE_ENABLED) 判断开关。
可以使用框架内建 schema,或项目已有的校验库;缺少必需凭据时明确启动失败或拒绝相应功能。诊断信息只输出字段名和来源状态,避免用整份 process.env 或完整配置对象排查问题。
配置约定怎样持续生效
先决定值属于共享代码、本机还是部署环境,再让启动命令负责加载,让 Git 规则保护本机覆盖,并在程序入口校验字段。构建期已经写入浏览器产物的值,需要重新构建才能改变;运行时配置则依赖实际宿主和执行路径。