新增一个配置开关时，先让 Codex 别把所有环境一起改了

教程定位

这篇教程解决什么问题

新增一个配置开关，看起来只是多加一行变量，实际很容易把所有环境一起带偏。开发环境为了调试希望默认打开，测试环境希望稳定覆盖，生产环境必须默认关闭；但项目里可能同时存在 `config/default.ts`、`config/test.ts`、`.env.example`、部署平台变量、容器启动参数和功能模块里的兜底值。你让 Codex “加一个开关”，它可能顺手把默认值写进公共配置层，结果本地、测试、生产全都继承了同一个行为。

这篇文章讲的不是“改功能前审计配置”，也不是“设计一个完整功能开关系统”。它解决一个更窄的问题：当你已经决定要新增一个配置项，怎样让 Codex 先找清配置层级、默认值合并逻辑和各环境覆盖点，再输出一份可审查的配置改动方案和环境对照表。

最终你会拿到两样东西。第一份是配置改动方案：新增哪个配置键，放在哪一层，默认值在哪里定义，哪些环境必须显式覆盖，哪些文件只更新示例或文档。第二份是环境对照表：开发、测试、预发、生产分别会读到什么值，值从哪里来，缺失时会发生什么，谁需要确认。

核心原则很简单：不要让 Codex 直接改“看起来最方便”的公共默认值。先让它证明配置值如何合并，再决定在哪里加默认、在哪里覆盖、哪里不能碰。多环境应用里，配置改动最大的风险不是语法错，而是环境扩散：一个为了本地调试开的开关，被公共默认值带进生产；一个为了测试稳定关掉的开关，把预发验证也关掉；一个生产必须显式配置的变量，被代码兜底成了宽松默认。

本文用一个虚构的“订单备注 AI 摘要”功能举例。需求是新增 `orderSummary.enabled` 开关：开发环境默认打开，自动化测试默认关闭，预发可以手动打开，生产默认关闭且必须通过部署变量显式开启。样例不会包含真实密钥、真实域名、真实客户数据或内部配置值。你可以把方法迁移到搜索实验、后台入口、异步队列、新版接口、AI 功能、导出任务和第三方集成开关上。

使用场景

什么情况下最适合用这一套

你维护一个有开发、测试、预发、生产四套环境的应用。产品希望给订单详情页加一个“AI 摘要备注”的能力，但第一步只是把配置开关接好，不急着对所有用户开放。

你们希望环境默认值是这样的：

| 环境 | 期望值 | 原因 | | --- | --- | --- | | 开发 | 默认打开 | 方便本地联调入口和 mock 返回 | | 自动化测试 | 默认关闭 | 避免快照、固定返回和旧用例被新入口影响 | | 预发 | 默认关闭，可由部署变量打开 | 需要按验收计划打开，不跟随代码自动开启 | | 生产 | 默认关闭，显式审批后再打开 | 不能因为代码发布直接影响用户 |

问题是，项目的配置不是一层。你看到仓库里有这些东西：

如果你直接对 Codex 说“帮我新增一个功能开关”，它可能会在 `defaults.ts` 里写：

这对本地开发很舒服，却可能让所有未覆盖环境都继承 `true`。更隐蔽的是，生产部署变量如果漏配，代码会继续用公共默认值，直到上线后你才发现入口已经露出来。

这篇教程适合这些情况：

不适合这篇的情况也要说清楚。如果你还不知道功能要不要做、开关粒度按租户还是按用户、谁审批打开生产，这属于产品和发布策略问题。本文只处理配置落点和环境覆盖，不替你决定生产什么时候打开。

1. 你要新增配置项，而不是只读取一个已有变量。
2. 不同环境的默认值不同，不能把一个值写进全局默认层就结束。
3. 配置有合并顺序，例如 default -> env specific -> runtime env -> deployment override。
4. 你希望 Codex 先输出方案，让人审查后再动配置文件。
5. 你最担心的是“顺手影响所有环境”，而不是业务代码本身。

• `packages/config/src/defaults.ts` 里有公共默认值。
• `apps/web/src/config/runtime.ts` 会读取浏览器运行时注入变量。
• `services/api/src/config/env.ts` 会把 `process.env` 合并进配置对象。
• `config/test.ts` 会覆盖测试环境变量。
• `.env.example` 和 `deploy/production.example.env` 记录了变量名。
• CI 文件里还有 `FEATURE_ORDER_AI_SUMMARY=false`。

orderSummary: {
  enabled: true
}

材料准备

开始前先把材料和边界备齐

给 Codex 的材料要围绕“配置如何生效”，不要只贴需求句子。最少准备四类输入。

第一类是功能开关需求。说明新增配置项的名字、语义、期望类型和各环境默认值。比如 `orderSummary.enabled` 是布尔开关，控制订单详情页是否显示 AI 摘要入口；开发默认打开，测试默认关闭，预发和生产默认关闭。

第二类是现有配置文件。包括公共默认配置、环境专属配置、配置 schema、配置 loader、运行时配置读取、前端构建配置、后端 env 解析。你不需要一次贴完整仓库，但要给 Codex 搜索范围和候选路径。

第三类是环境变量样例。可以提供 `.env.example`、`.env.test.example`、`deploy/staging.example.env`、`deploy/production.example.env`，但不要提供真实 `.env`、真实 token、真实内部域名或客户数据。样例值用 `true`、`false`、`placeholder`、`https://example.invalid` 就够了。

第四类是部署配置线索。包括 Docker Compose、CI 工作流、Kubernetes values 示例、Vercel 或平台变量说明、启动脚本。很多“配置扩散”不是代码造成的，而是部署层覆盖了同名变量，或者部署层没有覆盖，导致公共默认值生效。

开始前你还要给 Codex 两条硬边界：

建议先把需求整理成这样：

• 第一轮只读分析，不改文件。
• 输出方案时必须标注“证据路径”和“不确定项”，不能编造真实环境取值。

我要新增订单备注 AI 摘要开关。

配置语义：
- 配置键：orderSummary.enabled
- 环境变量候选名：FEATURE_ORDER_AI_SUMMARY
- 类型：boolean
- 影响范围：订单详情页入口、后端摘要接口调用保护

期望环境值：
- development: true
- test: false
- staging: false，允许部署变量打开
- production: false，必须显式审批后通过部署变量打开

请先只读分析配置层级、合并顺序、默认值来源和各环境覆盖点。
不要修改代码，不要写入真实环境，不要新增生产变量。

实操流程

按这套步骤把工作跑起来

第一步，让 Codex 画出配置层级，而不是直接加变量。

你要问的是“配置在哪里合并”，不是“哪个文件看起来像配置文件”。让 Codex 找这些信号：`loadConfig`、`mergeConfig`、`defaults`、`env`、`runtimeConfig`、`process.env`、`import.meta.env`、`ConfigModule`、`zod`、`joi`、`dotenv`、`NODE_ENV`、`APP_ENV`。输出要包含合并顺序，例如：

只有知道合并顺序，才能判断新增开关放在哪里。公共默认层适合“所有环境都一样的安全默认值”；环境专属层适合本地和测试差异；部署变量适合预发和生产的显式打开。不要在还没看清合并顺序时让 Codex 写代码。

第二步，要求它列出同类配置的既有写法。

新增开关要跟随项目习惯。让 Codex 找已有 feature flag 或模块配置，例如 `invoiceExport.enabled`、`newSearch.enabled`、`betaDashboard.enabled`。重点看三件事：变量命名如何映射到配置键，布尔值如何解析，缺失时默认值来自哪里。

如果项目已有 `parseBooleanEnv(process.env.FEATURE_X, false)`，就不要让 Codex 新写一个 `process.env.FEATURE_X === "true"`。如果项目要求配置 schema 里声明类型，就不要只在业务代码里读取变量。配置开关不是临时判断，应该进入统一配置层。

第三步，把环境期望值转成“落点决策”。

不要只告诉 Codex “开发 true，生产 false”。要让它回答每个值放在哪里：

| 环境 | 期望值 | 建议落点 | 原因 | | --- | --- | --- | --- | | development | true | `config/development.ts` 或本地示例 | 只服务本地联调，不污染公共默认 | | test | false | `config/test.ts` | 保持自动化测试稳定 | | staging | false | 公共安全默认 `false`，部署变量可覆盖 | 预发按验收计划打开 | | production | false | 公共安全默认 `false`，生产变量显式覆盖 | 防止代码发布直接开放 |

这里的关键是公共默认值通常应该选“最安全值”，而不是“最方便开发的值”。对用户可见功能来说，公共默认 `false` 更稳；开发环境想打开，就在开发覆盖层打开。

第四步，检查前后端是否需要同一个配置语义。

很多开关同时影响前端入口和后端接口。如果只在前端配置里加 `enabled`，用户看不到入口，但接口可能仍可被调用；如果只在后端加开关，前端可能显示入口后被接口拒绝。让 Codex 分清两个层面：

它们可以来自同一个环境变量，也可以分别配置，但语义必须一致。输出方案要写清楚“前端读取什么，后端读取什么，二者是否有共享配置或接口返回”。如果项目是服务端把 flag 下发给前端，就不要让前端直接读取部署变量。

第五步，找出所有环境覆盖点。

让 Codex 不只看 `config/`，还要看 `.env.example`、测试配置、CI、Docker Compose、部署示例、启动脚本。新增开关经常要同步这些地方：

但“同步”不等于每个文件都写同一个值。`.env.example` 是说明，不代表真实默认；生产部署示例可以写 `FEATURE_ORDER_AI_SUMMARY=false`，并注释“需审批后改为 true”；开发配置可以是 `true`。

第六步，让 Codex 先输出方案，不立即改文件。

配置改动适合先审方案。让 Codex 输出：

如果方案里出现“修改公共默认为 true”，你要追问：哪些环境会继承它？测试和生产是否有明确覆盖？如果没有，就应改成公共默认 `false`，再在开发覆盖层打开。

第七步，再让 Codex 按方案改配置，并要求最小改动。

确认方案后，再让它只改必要文件。提示词里要限制范围：

配置文件容易被“顺手整理”。Codex 可能看到排序不统一，就把整个对象重排；看到注释不一致，就批量改文档。你要明确本轮只新增这个开关，避免把审查范围放大。

第八步，生成环境对照表。

改完后，让 Codex 用代码证据生成对照表。表格建议包含这些列：

| 环境 | 读取值 | 值来源 | 是否显式覆盖 | 缺失时行为 | 人工确认 | | --- | --- | --- | --- | --- | --- | | development | true | `config/development.ts` | 是 | 缺失仍回落到公共 false | 确认本地示例变量名 | | test | false | `config/test.ts` | 是 | 测试稳定关闭 | 确认 CI 没有覆盖成 true | | staging | false | 公共默认或部署变量 | 否，除非平台设置 | 默认关闭 | 验收时由发布负责人打开 | | production | false | 公共默认或生产部署变量 | 否，除非审批设置 | 默认关闭 | 确认生产平台未误设 true |

这张表是交付物，不是装饰。它让代码评审者一眼看到：这个改动不会因为公共默认值扩散到生产；测试也不会被开发默认值污染；预发和生产的打开动作是部署层决策，不是代码发布副作用。

第九步，检查缺失行为和布尔解析。

布尔配置最常见的坑是字符串解析。`"false"` 在 JavaScript 里是真值，`Boolean("false")` 会得到 `true`。让 Codex 使用项目已有解析函数，或者至少输出解析规则。可接受的写法通常是明确识别 `"true"`、`"1"`、`"false"`、`"0"`，无法识别时报错或使用安全默认。

还要检查缺失行为。对生产默认关闭的开关，缺失时应该关闭，而不是抛出影响启动；对必须显式配置的高风险功能，缺失时可能应该启动失败。你的这次需求如果是普通入口开关，生产缺失回落 `false` 是合理的；如果是支付、权限、数据删除相关开关，策略要另行确认。

第十步，把“打开生产”从代码改动里拆出去。

这篇文章的重点是配置文件怎么改，不是如何发布生产开关。代码层新增开关默认关闭，可以合并；生产打开开关应该是单独动作，带审批、记录和回滚方案。让 Codex 在交付里明确写出：“本次配置改动不打开生产功能；生产启用需要单独修改部署变量。”

这样做的好处是审查边界清楚。评审这次代码的人只需要确认配置层级和默认值没有扩散；发布负责人另行确认什么时候把预发或生产变量改为 `true`。

1. 需要新增或修改的文件。
2. 每个文件改什么。
3. 为什么这个值放在这一层。
4. 哪些环境会受到影响。
5. 哪些地方只更新示例，不改变运行行为。
6. 哪些真实部署值需要人工确认。

• 展示开关：是否显示入口、按钮、菜单、提示。
• 执行开关：是否允许调用接口、创建任务、触发外部服务。
• 配置 schema：声明类型和默认值。
• 公共默认配置：放安全默认值。
• 开发覆盖配置：本地打开。
• 测试覆盖配置：测试关闭。
• `.env.example`：告诉新人变量名和含义。
• 部署示例：告诉预发、生产如何显式打开。
• CI：避免测试被本地默认值影响。
• 不改业务逻辑，除非本轮目标包含接入读取。
• 不改真实 `.env`。
• 不改生产平台配置。
• 不整理无关配置格式。
• 不把旧开关顺手重命名。

公共默认值 defaults.ts
-> 环境专属 config/${APP_ENV}.ts
-> process.env 覆盖
-> 前端 runtime-config.json 覆盖

输入示例

可以直接参考的输入材料

下面是一段可以直接交给 Codex 的安全虚构输入。它包含配置文件、环境变量样例、部署配置和开关需求，但不包含真实密钥。

任务：
请先只读分析，再给出配置改动方案。暂时不要修改文件。

需求：
新增订单备注 AI 摘要开关。
- 配置键：orderSummary.enabled
- 环境变量名：FEATURE_ORDER_AI_SUMMARY
- 类型：boolean
- 开关语义：控制订单详情页是否显示 AI 摘要入口；后端摘要接口也要能读取同一语义，防止入口隐藏但接口仍可用。

期望默认值：
- development: true
- test: false
- staging: false，可通过部署变量打开
- production: false，必须审批后通过部署变量打开

候选文件：
- packages/config/src/defaults.ts
- packages/config/src/loadConfig.ts
- packages/config/src/schema.ts
- config/development.ts
- config/test.ts
- apps/web/src/config/runtime.ts
- services/api/src/config/env.ts
- .env.example
- deploy/staging.example.env
- deploy/production.example.env
- .github/workflows/test.yml

已知片段：
defaults.ts 里已有：
featureFlags: {
  newSearch: false,
  invoiceExport: false
}

development.ts 里已有：
featureFlags: {
  newSearch: true
}

test.ts 里已有：
featureFlags: {
  newSearch: false,
  invoiceExport: false
}

deploy/production.example.env 里已有：
FEATURE_NEW_SEARCH=false
FEATURE_INVOICE_EXPORT=false

交付：
1. 配置层级和合并顺序。
2. 同类开关写法。
3. 配置改动方案。
4. 开发、测试、预发、生产环境对照表。
5. 不能直接改生产或真实 .env。

提示词

可复制使用的提示词

如果你已经确认方案，第二轮可以这样让 Codex 动手：

你是协助我做配置改动的 Codex。请先只读分析，不要修改文件。

我要新增一个配置开关，但不同环境默认值不同。请你重点防止“改公共默认值导致所有环境一起受影响”。

请按以下步骤输出：

1. 找出当前项目的配置层级和合并顺序。请给出文件路径和证据，不要只猜。
2. 找出 2-3 个同类 feature flag 或模块配置，说明它们的变量命名、布尔解析、默认值和环境覆盖方式。
3. 基于我的期望环境值，提出新增配置的落点方案：公共默认层、development、test、staging、production 示例、CI 分别是否需要改。
4. 明确哪些改动会改变运行行为，哪些只是更新示例或文档。
5. 输出环境对照表：development、test、staging、production 分别读到什么值、值从哪里来、缺失时如何处理、需要谁人工确认。
6. 列出不确定项和需要我确认的真实部署变量。不要编造生产环境实际值。

边界：
- 不修改真实 .env。
- 不修改生产平台配置。
- 不重排无关配置。
- 不把生产开关打开。
- 如果公共默认值会被生产继承，请明确提示风险。

这是我的需求和材料：
[粘贴开关语义、期望环境默认值、配置文件路径、环境变量样例、部署配置片段]

请按上一轮确认的方案做最小配置改动。

范围：
- 只新增 orderSummary.enabled / FEATURE_ORDER_AI_SUMMARY 相关配置。
- 公共默认值保持安全关闭。
- development 覆盖为 true。
- test 覆盖为 false。
- staging/production 示例写明默认 false，不打开真实生产。
- 使用项目现有布尔解析和 schema 写法。

完成后输出：
1. 修改文件列表。
2. 每个环境最终值和来源。
3. 我需要人工确认的部署变量。

输出样例

AI 应该输出到什么程度

下面是用上面提示词可能得到的一份好输出。它是示意，不代表你的项目一定使用这些路径。

这份输出合格的地方在于，它没有急着写代码，而是先证明配置合并顺序；它把公共默认值设成安全关闭；它区分了“运行行为变更”和“示例说明变更”；它没有假装知道真实生产变量。

一、配置层级和合并顺序

证据：
- packages/config/src/loadConfig.ts 中 loadConfig(appEnv) 先读取 defaults，再按 appEnv 读取 config/${appEnv}.ts，最后用 readEnvOverrides(process.env) 覆盖。
- packages/config/src/schema.ts 声明 featureFlags 下的布尔字段。
- apps/web/src/config/runtime.ts 不直接读取 FEATURE_*，而是读取服务端下发的 publicConfig.featureFlags。
- services/api/src/config/env.ts 使用 parseBooleanEnv 解析 FEATURE_* 变量。

合并顺序：
defaults.ts
-> config/${APP_ENV}.ts
-> process.env / 部署变量
-> web runtime publicConfig

二、同类配置写法

1. featureFlags.newSearch
- 公共默认 false。
- development.ts 覆盖 true。
- test.ts 覆盖 false。
- 生产示例 FEATURE_NEW_SEARCH=false。

2. featureFlags.invoiceExport
- 公共默认 false。
- 没有开发覆盖。
- deploy/production.example.env 中显式 false。

结论：
新增用户可见开关应采用公共默认 false，再由 development 覆盖 true 的方式。

三、配置改动方案

建议修改：
1. packages/config/src/schema.ts
   新增 featureFlags.orderSummary: boolean，使用现有 schema 默认 false。
   运行行为：声明配置类型，防止未知字段绕过。

2. packages/config/src/defaults.ts
   新增 featureFlags.orderSummary = false。
   运行行为：所有未覆盖环境安全关闭。

3. config/development.ts
   新增 featureFlags.orderSummary = true。
   运行行为：本地开发默认打开。

4. config/test.ts
   新增 featureFlags.orderSummary = false。
   运行行为：测试环境明确关闭，避免继承开发配置。

5. services/api/src/config/env.ts
   在 readEnvOverrides 中映射 FEATURE_ORDER_AI_SUMMARY 到 featureFlags.orderSummary，使用 parseBooleanEnv。
   运行行为：允许 staging/production 通过部署变量显式打开。

6. .env.example
   新增 FEATURE_ORDER_AI_SUMMARY=false，并注释开发可设为 true。
   说明性质：示例，不代表真实环境。

7. deploy/staging.example.env 和 deploy/production.example.env
   新增 FEATURE_ORDER_AI_SUMMARY=false。
   说明性质：部署示例，生产打开需要单独审批。

不建议：
- 不要把 defaults.ts 设置为 true。production 如果未配置部署变量会继承 true，存在环境扩散风险。
- 不要在 apps/web 直接读取 import.meta.env.FEATURE_ORDER_AI_SUMMARY，因为当前项目由服务端下发 publicConfig。

四、环境对照表

| 环境 | 最终默认值 | 值来源 | 是否会因本次代码发布打开 | 缺失时行为 | 需要确认 |
| --- | --- | --- | --- | --- | --- |
| development | true | config/development.ts | 会在本地打开 | 未设置 env 时仍为 true | 本地是否接受默认打开 |
| test | false | config/test.ts | 不会 | 未设置 env 时关闭 | CI 是否有 FEATURE_ORDER_AI_SUMMARY=true |
| staging | false | defaults.ts 或 deploy/staging.example.env | 不会 | 未设置 env 时关闭 | 验收时由发布负责人显式设置 |
| production | false | defaults.ts 或 deploy/production.example.env | 不会 | 未设置 env 时关闭 | 确认生产平台当前未设置 true |

五、不确定项

- 我无法读取真实 staging/production 平台变量，只能根据示例文件判断。
- 如果生产平台已存在 FEATURE_ORDER_AI_SUMMARY=true，本次代码上线后可能打开功能，需要发布前人工确认。
- 后端摘要接口是否已经读取 publicConfig，需要在接入业务逻辑时另查。

人工验收

人要怎么检查和改到可用

第一，检查公共默认值是否安全。对用户可见、调用外部服务、写数据、影响权限或改变计费的功能，公共默认值通常应该是关闭。开发想打开，可以放在开发覆盖层。不要为了少写一个环境文件，把 `true` 放进所有环境都会继承的 defaults。

第二，检查 Codex 是否真的理解合并顺序。有些项目不是 `default -> env -> process.env`，而是 `process.env -> default`，或者前端构建时变量已经固化，运行时部署变量不会再生效。你要打开 loader 文件确认，不要只看 Codex 的文字总结。

第三，检查布尔解析。尤其是 JavaScript、TypeScript 项目，不能用 `Boolean(process.env.FEATURE_X)` 解析开关。字符串 `"false"` 会变成 `true`。如果项目已有解析工具，必须复用；如果没有，要至少保证 `"true"` 和 `"false"` 被明确处理。

第四，检查前后端语义是否一致。前端入口隐藏不等于后端能力关闭；后端拒绝不等于前端不会展示。新增开关如果要保护整个功能，必须说明前端展示和后端执行分别从哪里读值。必要时让服务端返回一个受控的 public flag，而不是让前端猜部署变量。

第五，检查测试环境是否被开发配置污染。很多项目的测试会默认使用 `NODE_ENV=test`，但也可能加载 `.env.local` 或开发默认值。自动化测试需要稳定，通常应该显式关闭新入口，除非这轮任务就是新增对应测试。

第六，检查部署示例和真实部署的边界。修改 `deploy/production.example.env` 不等于修改生产。Codex 不能替你确认平台里已有变量是什么值。上线前要让有权限的人确认真实预发和生产变量，尤其是是否已经存在同名变量。

第七，检查这次改动有没有混入打开动作。PR 里如果既新增开关，又把生产示例改成 `true`，又改了发布脚本默认打开，就不是“新增配置项”，而是“发布功能”。这需要更高等级的审查和批准。

第八，检查文档是否说清默认值意图。好的注释不是“订单摘要开关”，而是“默认关闭；开发环境可打开；生产启用需单独审批”。下一个维护者看到它，才不会为了本地调试去改公共默认层。

失败反例

这些失败反例要提前避开

【反例 1：为了本地省事，把公共默认值设成 true】

错误做法：

这段代码本地确实方便，但所有没有显式覆盖的环境都会继承 `true`。如果生产平台没有配置 `FEATURE_ORDER_AI_SUMMARY=false`，功能就会随代码发布一起打开。正确做法是公共默认 `false`，开发环境单独覆盖 `true`。

【反例 2：只改前端入口，不保护后端执行】

错误做法是只在前端写：

这样开关关闭时用户看不到按钮，但接口可能仍能被手动调用、旧入口调用或测试脚本调用。如果这个功能会创建摘要任务、消耗额度或调用外部服务，后端也要读取同一语义的开关，并在关闭时拒绝执行或返回明确状态。

【反例 3：用 Boolean 解析字符串环境变量】

错误做法：

当部署变量写成 `FEATURE_ORDER_AI_SUMMARY=false` 时，`enabled` 仍然是 `true`，因为非空字符串是真值。正确做法是使用项目已有的 `parseBooleanEnv`，或明确把 `"true"` / `"1"` 解析为 true，把 `"false"` / `"0"` 解析为 false。

【反例 4：把生产打开动作混进配置接入 PR】

有人为了“上线后少一步”，在同一个 PR 里新增配置、接入业务逻辑、把生产部署示例改成 `true`，甚至更新发布脚本默认打开。这样评审者很难判断是在审配置结构，还是在批准生产开放。正确做法是本轮只新增默认关闭的配置能力；生产打开作为单独发布动作，保留审批记录和回滚方式。

// packages/config/src/defaults.ts
export const defaults = {
  featureFlags: {
    orderSummary: true
  }
};

if (config.featureFlags.orderSummary) {
  showSummaryButton();
}

const enabled = Boolean(process.env.FEATURE_ORDER_AI_SUMMARY);

主题边界

它和相邻主题的区别

这篇文章和“改功能前查配置和环境变量”不同。配置审计关注的是改动前的现状调查：变量在哪里读、默认值是什么、环境差异有哪些、哪些风险要先确认。本文关注的是新增配置时的落点设计：公共默认层该放什么值，开发和测试怎么覆盖，预发和生产怎么避免跟随代码自动打开。一个是查清现状，一个是决定怎么改。

它也不同于“功能开关怎么设计”。功能开关设计会讨论开关粒度、按租户灰度、审批人、监控指标、回滚策略和发布节奏。本文只处理配置文件层面的工程问题：新增一个开关时，怎样不让默认值扩散到所有环境。生产什么时候打开、按谁开放、指标怎么看，都应该在发布方案里另写。

它还不同于“拆分中型功能”。功能拆分关注数据库、接口、前端、权限、测试和发布顺序；配置开关只是其中一个安全措施。本文把镜头拉近到配置层级本身：同一个开关在 development、test、staging、production 里如何取值，哪个文件改变运行行为，哪个文件只是示例，哪些真实部署变量必须由人确认。

最简单的判断方式是：如果你的问题是“现在环境变量到底怎么生效”，先做配置审计；如果你的问题是“这个新开关应该写在哪一层，才不会顺手影响所有环境”，看本文；如果你的问题是“生产要不要打开、给谁打开、出事怎么关”，那已经超出配置文件，应该进入发布和风险评审。