环境变量与配置优先级

建议用时：25 分钟（含练习）

学习目标

能够用环境变量保存地址、模型和凭证，并判断系统、用户、项目和进程级配置来源。

本节产出

一份脱敏配置清单与优先级图

核心知识：文件里写了，不代表进程正在用

你修改了一个配置文件，程序仍然访问旧地址。这类问题常被误认为缓存或服务故障，实际可能是程序从另一个位置读取了配置，或者运行中的进程没有重新加载。排查时要从“哪个进程在什么时刻读取了哪个值”出发，而不是到处创建同名变量。

术语

环境变量

环境变量是进程获得配置的一种方式。父进程启动子进程时通常会传递一组环境值，但已经运行的进程不会因为你在另一个终端修改变量，就自动获得新值。桌面应用、终端、容器和远程服务也可能拥有不同环境。因此“我在终端里能看到变量”并不证明目标应用也能看到。

.env 文件只是常见的配置文件约定，并不是操作系统自动加载的魔法文件。是否读取、从哪里读取、文件名优先级和何时读取，都由框架、启动脚本或加载库决定。不要假定任何目录里的 .env 都会生效，也不要假定它一定覆盖已有进程环境。

图中“应用规定的优先级”是关键。如果你没有核对这项规则，就无法解释为什么修改文件没有改变结果。不同工具可以采用不同顺序，课程不提供一个冒充通用标准的优先级表。

用明确的教学规则练习推导

假设一个虚构程序规定：显式参数优先，其次进程环境，再其次项目配置文件，最后使用默认值。这只是本练习给定的规则。

因此，修改项目文件不会改变本例的最终地址。正确修复需要在获准的配置来源中更新环境，按程序要求重新启动或重新加载，再检查实际生效结果。不能只删掉看起来碍事的文件，因为它可能还服务于其他环境。

构建时配置与运行时配置

构建时配置

一些前端框架会在构建时将特定环境变量写入浏览器代码。构建完成后，只修改服务器环境可能不会改变已经生成的静态文件。

运行时配置

相反，运行时由服务端读取的变量可能在重启后生效。

具体行为要核对框架说明和应用代码。

凡是进入浏览器代码的值，应视为用户可以查看。不能给密钥加一个“公开变量前缀”后，期望它仍然保密。把秘密留在后端也只是第一步，还要限制读取权限、日志输出与使用范围。本课的练习只使用虚构地址和无敏感配置，不需要创建真实密钥。

案例：桌面应用和终端各用一套配置

你在终端运行教学脚本，它访问新地址；同一台电脑上的桌面工具仍访问旧地址。先确认两个进程由谁启动，再检查它们各自的配置位置。桌面工具可能在登录时就已启动，或者使用自己的设置文件，并没有读取当前终端环境。

不要直接打印全部环境来比较，因为里面可能包含其他服务的凭证。更安全的诊断输出可以只显示：目标变量是否存在、非敏感服务主机、配置来源类别、应用版本和最近加载时间。对于密钥，可以记录是否存在或由受保护系统提供的凭证标识，而不是显示完整值。

如果调整后仍不生效，再确认运行的是不是同一个项目副本。有多个 worktree、多个容器或旧进程时，编辑正确的文件也可能只改变了一个未被使用的目录。应以进程启动路径和实际请求证据为准。

动手练习

1. 按本节给定的虚构优先级，分别为显式参数、进程环境和项目文件提供不同的非敏感颜色值，手工推导最终采用哪一个。
2. 为一个实际使用的工具查阅配置文档，记录它是否读取环境变量、配置文件路径如何决定、修改后如何重新加载。
3. 写一条脱敏诊断记录，帮助同伴确认生效来源，且不包含任何密钥值或全部环境输出。

参考答案与推演

展开

完成检查

• 能区分进程环境与 .env 文件，知道文件需要程序主动加载。
• 配置优先级来自具体应用文档或代码，不来自猜测。
• 能区分构建时公开值与服务端运行时秘密。
• 诊断不打印全部环境，能定位真正运行的进程和目录。

参考与来源

• Node.js：Environment Variables：了解 Node.js 中的环境变量和 .env 约定。
• Next.js：Environment Variables：查看一个具体框架的加载顺序及浏览器公开变量规则。