前端多环境配置应该如何设计？

简化版

前端多环境配置要先区分构建时配置与运行时配置：前者在打包时静态替换，一个产物通常对应一个环境；后者由启动配置或接口提供，同一产物可跨环境部署。任何进入浏览器的值都不是秘密，密钥和高权限凭证必须留在服务端。

详细版

开发、测试、预发、生产环境通常会改变 API 地址、CDN、监控 release 和功能开关。配置应集中定义、带类型和启动校验，业务代码只消费配置对象，避免散落 if (env === ...)。

以 Vite 为例，只有匹配 envPrefix、默认以 VITE_ 开头的变量会暴露给客户端，而且读取值都是字符串。mode 与 NODE_ENV 是不同概念，vite build --mode staging 仍默认执行生产构建，只是加载 staging 模式配置。

若要求“构建一次，到处部署”，应在页面启动时读取 /config.json 或由部署层注入配置。运行时配置仍会送到浏览器，灵活性不等于保密性。

完整版教学

一、环境与配置是两个维度

环境描述部署位置和交付阶段，例如 development、test、staging、production；配置是该位置使用的具体值。把两者混为一谈，代码里就容易出现大量环境名称判断。

更稳妥的方式是业务只询问“API 基址是什么”“监控是否启用”，而不是询问“我是不是生产环境”。这样新增灰度环境时只换配置，不必修改每个业务分支。

记忆钩子：环境是标签，配置才是行为；前端可见配置都是公开信息。

二、构建时配置如何进入产物

构建工具通常把常量静态替换进 JavaScript。Vite 的 import.meta.env.DEV 等值可被替换后参与 Tree Shaking，以移除只在开发环境执行的分支。

const config = {
  apiBase: import.meta.env.VITE_API_BASE,
  timeout: Number(import.meta.env.VITE_TIMEOUT ?? 5000),
  debug: import.meta.env.VITE_DEBUG === 'true'
}

环境变量默认是字符串，所以字符串 'false' 在布尔判断中仍为真。数值、布尔值和枚举必须显式解析并校验，否则配置存在却仍可能产生错误行为。

三、Vite mode 与 NODE_ENV 为什么不能画等号

Vite 默认 dev 命令使用 development mode，build 使用 production mode；--mode staging 决定加载 .env.staging，不自动把 NODE_ENV 改成 staging。MODE、PROD/DEV 和 Node 环境值表达的含义不同。

命令	mode	默认构建性质
`vite`	development	开发服务器
`vite build`	production	生产构建
`vite build --mode staging`	staging	仍是生产构建

Vite 中 .env.[mode] 高于通用 .env，命令执行前已有的系统变量优先级更高。修改 .env 后还需重启开发服务器，不能假设热更新会重新加载全部环境文件。

四、运行时配置解决什么问题

构建时值已经写死，四个环境往往要构建四次。运行时方案让同一份带 hash 的 JS/CSS 在启动时读取部署环境配置，减少重复构建并降低“同一提交、不同产物”的差异。

同一静态产物 ─┬─> 测试环境 /config.json
              ├─> 预发环境 /config.json
              └─> 生产环境 /config.json

代价是首屏多一次配置获取或 HTML 注入逻辑，还要处理超时、缓存和 schema 不兼容。配置文件通常应及时重新验证；若被长期缓存，部署切换后页面可能继续访问旧 API。

五、安全边界为什么不会因运行时注入改变

浏览器必须拿到 API 地址和公开 appId 才能使用它们，因此用户能从源码、Network 或内存读取。把变量名藏起来、压缩代码或不生成 Source Map 都不能把客户端值变成秘密。

假设一个私钥有 256 位熵，只要它被打进 JS，攻击者无需暴力尝试 2^256 种组合，直接下载产物就能获得原值。密钥应由服务端或边缘函数持有，浏览器只调用受鉴权、限流和授权约束的接口。

监控 DSN、公开 OAuth client id 可能本来就是公开标识，但仍要在服务端配置来源限制、配额和最小权限。判断标准不是字段叫不叫 key，而是泄露后能否独立获得特权。

六、配置治理与发布校验

集中配置层应定义 schema、默认值和必填项，启动时快速失败。生产 API 指向测试域名、release 为空或开关值非法时，应在流水线或启动阶段阻断，而不是等待用户报错。

风险	防护措施	失败时处理
缺少必填值	schema 校验	阻止构建/启动
环境串线	域名白名单、部署审批	阻止发布
配置缓存过旧	短缓存或重新验证	回退并告警
开关误开	分环境权限、审计记录	快速关闭

CI 还应记录 commit、构建号、配置版本和部署目标。这样线上错误才能还原“哪份代码配了哪组配置”，而不是只知道 production 出问题。

七、常见误区与追问

误区：写进 .env 的值默认都是保密的。 暴露给客户端或在构建中替换的值最终都能被用户读取。
误区：vite build --mode staging 会把 NODE_ENV 自动设为 staging。 mode 负责选择配置，NODE_ENV 与它是不同概念。
误区：运行时配置可以安全存放密钥。 只要浏览器需要读取，它仍然是公开值。
追问：为什么环境变量中的 false 判断为真？ 工具通常按字符串暴露，非空字符串在 JavaScript 中是真值。
追问：如何做到一次构建、多环境部署？ 使用外部配置文件或部署层注入，并为加载、缓存与 schema 失败设计兜底。
追问：怎样避免测试 API 发布到生产？ 在 CI 中校验域名和配置 schema，并把环境、产物和审批绑定。
追问：功能开关是否应该全放前端？ 展示类开关可以，权限和安全控制必须由服务端最终裁决。

八、加强记忆

用“时机、类型、安全、追踪”检查多环境配置：先问值在构建时还是运行时确定，再把字符串解析成明确类型；凡是送到浏览器的都按公开信息处理，真正秘密留在服务端；最后记录代码版本、配置版本和部署环境。这个框架比背四个 .env 文件名更能应对工程追问。

简化版

详细版