Go testing.T.Setenv 为什么不能和 Parallel 一起用：测试隔离、环境恢复与串行边界

测试套件一旦开始并行跑，t.Setenv 就不是某个 goroutine 的私有设置了：它会改变整个 Go 进程看到的环境变量，并在清理阶段恢复原值。因此，直接在调用了 t.Parallel() 的测试里使用它，或者在有并行祖先的子测试里使用它，都会被 testing 包拒绝。

需要改环境变量的测试放在串行边界内；需要并行的测试改为显式传入配置，或在测试进程外准备环境。不要把 Setenv 当成 goroutine 局部变量。

失败通常发生在测试刚进入并行阶段

最容易踩坑的写法如下。它看起来像是先准备环境，再跑断言，实际上 t.Parallel 已经把当前测试标记为并行测试：

func TestEndpoint(t *testing.T) {
    t.Parallel()
    t.Setenv("APP_MODE", "test")

    if got := loadMode(); got != "test" {
        t.Fatalf("mode = %q", got)
    }
}

运行时会得到类似“cannot set environment variable with parallel test”的失败信息。这里不是环境变量不存在，也不是 loadMode 读错了，而是测试框架在执行 Setenv 前发现当前测试已经进入并行状态。

从执行时间线看清 Setenv 和 Parallel 的冲突

t.Parallel() 会让测试暂停，等非并行测试完成后再与其他并行测试竞争执行时机。与此同时，t.Setenv 需要对整个进程调用环境设置，并注册一个清理函数，在该测试结束后恢复原值。

如果两个并行测试分别把 APP_MODE 改成 debug 和 safe，即使每个测试都注册了恢复动作，也无法保证另一个测试读取时看到的是自己的值。恢复动作只能解决“测试结束后还原”，不能把进程级状态变成局部状态。

所以 testing 包选择在运行前直接拒绝这类组合，失败得早，反而比偶发断言失败更容易定位。

并行祖先也会让子测试失去 Setenv 资格

下面的代码没有在子测试里直接调用 Parallel，但仍然不安全：

func TestConfig(t *testing.T) {
    t.Parallel()

    t.Run("default", func(t *testing.T) {
        t.Setenv("APP_MODE", "default")
        // 断言配置读取结果
    })
}

子测试继承了并行祖先的状态。官方 testing 文档明确把“当前测试或任一祖先是并行测试”都列为禁止条件。判断时不要只搜索当前函数有没有 t.Parallel()，还要沿着 t.Run 的调用树往上看。

修复方案：把环境变量测试留在串行组

最小修复是移除这类测试的 t.Parallel()，让环境设置、断言和清理在一个串行测试中完成：

func TestLoadModeFromEnv(t *testing.T) {
    t.Setenv("APP_MODE", "test")

    if got := loadMode(); got != "test" {
        t.Fatalf("loadMode() = %q, want test", got)
    }
}

func TestParseModeInParallel(t *testing.T) {
    t.Parallel()

    if got := parseMode("test"); got != "test" {
        t.Fatalf("parseMode() = %q", got)
    }
}

这两个测试覆盖的是不同层次：前者验证进程环境到配置读取的连接，后者验证不依赖全局环境的解析逻辑。把纯函数部分并行化，通常比强行让环境测试并行更划算。

需要并发覆盖时，改传配置而不是改进程环境

如果目标是验证多个配置组合，优先把配置显式传给被测函数。这样测试数据属于当前调用，不会污染同一进程中的其他测试：

type Config struct {
    Mode string
}

func runJob(cfg Config) string {
    return cfg.Mode
}

func TestRunJobModes(t *testing.T) {
    cases := []struct {
        name string
        mode string
    }{
        {name: "safe", mode: "safe"},
        {name: "debug", mode: "debug"},
    }

    for _, tc := range cases {
        tc := tc
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            if got := runJob(Config{Mode: tc.mode}); got != tc.mode {
                t.Fatalf("runJob() = %q, want %q", got, tc.mode)
            }
        })
    }
}

这种改法的代价是需要调整函数签名，尤其是旧代码把 os.Getenv 深埋在业务函数里时。不过它换来了确定的测试输入，也让生产代码更容易在不同配置下复用。

复测时要核对环境是否真的恢复

Setenv 会自动注册清理动作，但测试仍应验证关键边界：原变量不存在时应恢复为不存在，原变量存在时应恢复为原值。可以用一个串行测试覆盖这两种情况：

func TestSetenvRestoresValue(t *testing.T) {
    const key = "GO_ARTICLE_TEST_MODE"
    old, existed := os.LookupEnv(key)
    t.Cleanup(func() {
        if existed {
            os.Setenv(key, old)
        } else {
            os.Unsetenv(key)
        }
    })

    t.Setenv(key, "temporary")
    if got := os.Getenv(key); got != "temporary" {
        t.Fatalf("during test = %q", got)
    }
}

实际项目里不必重复实现 testing 的恢复逻辑；上面的额外清理只用于演示“测试前后状态”的核对方式。运行 go test -run TestSetenvRestoresValue -count=1 后，再用单独的进程检查该变量，才不会把当前测试进程里残留的环境误认为是外部 shell 的状态。

常见问题：误区与防复发检查

给 Setenv 外面加锁能解决吗

通常不能。锁可以让同一套自定义代码按顺序改值，却不能让 testing 包认为并行测试可以安全调用 Setenv，也不能约束未拿这把锁的库代码。

把 Setenv 放在 Parallel 前面可以吗

不要依赖这种顺序绕过问题。即使设置动作发生在标记并行之前，测试进入并行运行后仍可能与其他测试共享被修改的进程环境。更稳妥的做法是整个测试保持串行，或移除全局环境依赖。

怎样快速找出隐藏的并行祖先

先搜 t.Parallel() 和 t.Run(，再从失败的 Setenv 调用向上检查测试函数。CI 中可以用 go test ./... -count=1 配合目标包的单测命令复跑；若问题只在并行执行出现，优先检查测试间是否读写同一个环境键。

把测试边界写成团队约定

遇到环境变量、当前工作目录、进程级信号或全局注册表时，先把测试标成串行，再评估是否能把依赖改成显式参数。对于纯计算、解析和数据转换测试，可以放心使用 t.Parallel。最后在代码评审里检查一遍：全局状态是否有清理、并行祖先是否存在、失败后是否能复现。