我给自己写了一个本地环境变量管理器：切换环境不再手改一堆配置

目录

1. 缘起：环境切换为什么总靠手动改文件
2. 需求拆解：配置管理首先要避免串环境
3. 技术选型：只给目标进程注入变量
4. 核心实现一：解析配置并合并环境覆盖
5. 核心实现二：校验、脱敏与安全保存
6. UI 定制：启动之前先确认最终配置
7. 三个环境变量工具最容易踩的坑
8. 结尾：配置的价值是让差异显式存在

1. 缘起：环境切换为什么总靠手动改文件

一个项目通常至少有本地、测试和演示三套配置。项目规模不大时，我常用的方式是在 .env 文件里直接改几行：

API_BASE_URL=https://test.example.com
DATABASE_NAME=demo_test
ENABLE_DEBUG=true

这套方法刚开始很快，使用一段时间后却会出现熟悉的问题：

• 改完测试地址，忘记把调试开关恢复；
• 多个项目使用同名变量，开不同终端后互相影响；
• 数据库密码放进明文文件，提交 Git 时才发现；
• 启动脚本使用了旧变量，程序行为和当前文件不一致；
• 同事问“你现在连接的是哪个环境”，只能重新检查几份文件。

我不想再靠注释和记忆管理环境差异，于是做了一个本地工具：把每个环境定义成独立配置，启动程序时只给目标进程注入变量，并在启动前显示最终值的脱敏预览。

2. 需求拆解：配置管理首先要避免串环境

环境变量看起来只是键值对，但不同来源之间会覆盖，敏感值还涉及存储安全。我的功能边界如下：

第一版不修改 Windows 的全局环境变量，也不自动覆盖项目目录中的 .env 文件。它只是一个本地启动辅助工具，所有变化都限定在当前启动的程序及其子进程范围内。

心得：配置工具最安全的默认行为，是让影响范围尽可能短。

3. 技术选型：只给目标进程注入变量

程序使用 .NET 8 和 WinForms，配置文件是本地 JSON，启动目标使用 ProcessStartInfo：

子进程环境变量只对新启动的进程有效，关闭程序后不会继续改变系统设置。这种方式也避免了“先改全局环境，再打开另一个终端”带来的隐式状态。

项目配置和用户私密值分开保存：项目文件可以放在仓库或共享目录，个人令牌则存储在当前 Windows 用户可解密的凭据文件中。工具不会把解密后的内容写进项目配置。

4. 核心实现一：解析配置并合并环境覆盖

配置采用“基础组 + 环境组 + 临时覆盖”的三层结构：

{
  "base": {
    "APP_NAME": "demo",
    "LOG_LEVEL": "info"
  },
  "environments": {
    "local": {
      "API_BASE_URL": "http://localhost:8080",
      "ENABLE_DEBUG": "true"
    },
    "test": {
      "API_BASE_URL": "https://test.example.com",
      "ENABLE_DEBUG": "false"
    }
  }
}

合并顺序必须固定：基础配置先加入，当前环境覆盖同名键，用户在启动页填写的临时值最后覆盖。合并函数同时记录每个键的来源，便于界面解释最终结果。

private static Dictionary<string, ResolvedValue> Merge(
    IDictionary<string, string> baseValues,
    IDictionary<string, string> environmentValues,
    IDictionary<string, string> overrides)
{
    var result = new Dictionary<string, ResolvedValue>(
        StringComparer.OrdinalIgnoreCase);

    foreach (var pair in baseValues)
        result[pair.Key] = new(pair.Value, "base");

    foreach (var pair in environmentValues)
        result[pair.Key] = new(pair.Value, "environment");

    foreach (var pair in overrides)
        result[pair.Key] = new(pair.Value, "override");

    return result;
}

变量名统一限制为字母、数字和下划线，并要求以字母或下划线开头。未知变量不会被自动删除，而是标记为“未被 Schema 使用”，方便清理旧配置。

5. 核心实现二：校验、脱敏与安全保存

每个项目可以定义简单的变量规则：必填、字符串、整数、布尔值、URL 和枚举值。校验发生在启动前，不通过就不能点击“运行”。

private static IEnumerable<string> Validate(
    IReadOnlyDictionary<string, ResolvedValue> values,
    IReadOnlyList<VariableRule> rules)
{
    foreach (var rule in rules)
    {
        if (!values.TryGetValue(rule.Name, out var value) ||
            string.IsNullOrWhiteSpace(value.Value))
        {
            if (rule.Required)
                yield return $"缺少必填变量：{rule.Name}";
            continue;
        }

        if (!rule.IsValid(value.Value))
            yield return $"变量格式不正确：{rule.Name}";
    }
}

敏感字段不直接显示值，而显示首尾少量字符或固定遮罩。日志里只记录变量名、来源和是否存在，不记录真实内容。

保存敏感值时使用 Windows DPAPI，密文只能由当前用户在当前机器解开：

var protectedBytes = ProtectedData.Protect(
    Encoding.UTF8.GetBytes(secret),
    optionalEntropy: null,
    DataProtectionScope.CurrentUser);

这不是跨设备同步方案，也不替代密码管理器。工具的目标只是避免把个人令牌直接写入普通 JSON；用户换电脑或更换 Windows 账户时，需要重新录入敏感值。

6. UI 定制：启动之前先确认最终配置

主窗口左侧是项目与环境列表，右侧是变量表格。每行显示变量名、脱敏值、来源和校验状态。

启动前预览区会明确展示：

• 当前选择的项目和环境；
• 最终变量数量；
• 被覆盖的变量；
• 缺失和格式错误项；
• 将要启动的程序、参数和工作目录。

点击变量行可以展开来源链：例如 API_BASE_URL 来自基础配置，随后被 test 环境覆盖，当前没有临时修改。这个细节比只显示最终值更有用，因为环境串错往往不是值写错，而是覆盖来源不清楚。

运行中的进程显示在历史列表里，关闭进程不会删除配置。用户可以复制一份当前环境为新配置，但复制动作会自动把敏感值标记为“需要重新录入”，不把解密后的明文复制到新文件。

托盘菜单提供“最近环境”和“暂停自动启动”两个入口，但不会在系统启动时自动运行项目。启动行为必须由用户明确触发。

7. 三个环境变量工具最容易踩的坑

坑一：全局环境变量会污染后续进程。 如果工具直接修改系统环境，再打开编辑器、终端和测试程序，所有程序都会继承这次变化。默认只给目标子进程注入，关闭目标后环境自动恢复干净。

坑二：变量名大小写在不同系统上行为不同。 Windows 环境变量通常不区分大小写，Linux 则区分。配置校验和合并时要明确目标平台，不能把 Api_Url 和 API_URL 在所有环境里都当成同一个键。

坑三：把“存在”当成“正确”。 一个非空的 URL 可能指向错误环境，一个看似数字的端口可能超出范围。Schema 至少应该验证类型、格式和允许范围，而不只是检查有没有值。

另外，子进程可以把环境变量传给它启动的其他进程。敏感值一旦进入环境，就可能被诊断工具、崩溃报告或子程序读取。因此工具会提示哪些变量将被继承，并建议只在必要的启动链路中使用密钥。

8. 结尾：配置的价值是让差异显式存在

做完这个环境变量管理器后，我切换项目环境不再依赖修改文件和重开终端。选择环境、检查覆盖关系、确认校验结果，再启动目标程序，整个流程变得可见且可重复。

一个可靠的配置工具应该做到：

1. 变量来源和覆盖顺序清楚；
2. 敏感值默认不显示、不进普通日志；
3. 环境只注入目标进程，不污染系统；
4. 启动前阻止缺失和格式错误；
5. 配置变更可以复制、预览和回退。

如果你也想做类似工具，可以先实现“配置分组 + 子进程注入 + 脱敏预览”，不要一开始就修改系统全局环境或设计云端同步。环境配置越方便，越要让用户知道它影响了谁、保存在哪里、什么时候会失效。

当环境差异不再藏在几份手工修改的文件里，很多“明明本地能跑，换环境就不行”的问题会在启动前暴露出来。