Go testing.T.Setenv 为什么不能和 Parallel 同时使用

我在给 Go 测试补环境变量时，最容易误判的一点是：t.Setenv 看起来挂在当前测试对象上，实际修改的却是整个测试进程的环境。只要当前测试调用了 t.Parallel()，或者它的祖先已经进入并行测试，testing 就会拒绝这类组合。

Setenv 适合串行测试；并行测试应把配置作为局部输入传入，而不是让多个用例共同读写 os.Environ。

Setenv 和 Parallel 冲突的根因是进程级状态

testing.T.Setenv 的便利之处在于它会保存旧值，并注册清理函数；但它没有创造一份“当前测试专属的环境”。os.Getenv、os.Setenv 看到的仍是同一个进程环境。并行测试之间如果同时切换同名变量，任何一个用例都可能读到另一个用例写入的值。

所以限制的重点不是“Setenv 不能出现在子测试里”，而是不能出现在并行执行域里。官方文档把边界写得很明确：它不能用于并行测试，也不能用于拥有并行祖先的测试。

先把并行测试与环境变量测试拆开

最稳妥的拆分方式是：需要验证环境变量读取逻辑的测试保持串行，需要大量组合覆盖的测试保持并行，但不要让后者依赖进程环境。

func TestLoadModeFromEnv(t *testing.T) {
    // 这个用例不并行，Setenv 的作用范围只覆盖当前串行测试。
    t.Setenv("APP_MODE", "test")

    got := loadModeFromEnv()
    if got != "test" {
        t.Fatalf("load mode = %q, want test", got)
    }
}

func TestHandlerModes(t *testing.T) {
    cases := []string{"test", "readonly", "fallback"}
    for _, mode := range cases {
        mode := mode
        t.Run(mode, func(t *testing.T) {
            // 并行用例只携带局部值，不修改 APP_MODE。
            t.Parallel()
            got := loadMode(Config{Mode: mode})
            if got != mode {
                t.Fatalf("mode = %q, want %q", got, mode)
            }
        })
    }
}

这里的分工很重要：第一组测试覆盖“程序从环境读取”的适配层，第二组测试覆盖“业务收到配置后的行为”。它们测试的是两个边界，不必用一个全局变量把两者绑在一起。

需要并行时，把环境配置改成局部输入

如果生产代码把 os.Getenv 深埋在业务函数里，测试自然会被进程状态牵制。可以在边界处读取一次，再把结果装进普通结构体；并行测试只构造不同的结构体，不再触碰环境。

type Config struct {
    Mode string
}

func loadMode(cfg Config) string {
    // 业务函数只依赖参数，避免并行测试共享进程环境。
    if cfg.Mode == "" {
        return "default"
    }
    return cfg.Mode
}

func loadModeFromEnv() string {
    // 环境读取集中在适配层，便于用一个串行用例测试。
    return loadMode(Config{Mode: os.Getenv("APP_MODE")})
}

这不是为了绕过 testing 的保护，而是把真正的依赖关系写出来。并行测试需要的是“本用例的 Mode”，不是“此刻整个进程的 APP_MODE”。如果必须覆盖多个环境组合，参数化子测试比反复 Setenv 更容易复现。

最后用清单排查测试隔离问题

遇到“Setenv 不能和 Parallel 同时使用”时，可以按下面几项定位，而不是先把 t.Parallel() 随手删掉：

• 搜索当前函数及其父级 Test、Run 是否调用了 t.Parallel()。
• 确认被测函数是否直接读取 os.Getenv，以及读取是否发生在并行回调内部。
• 把“环境读取测试”和“配置行为测试”分成两类，前者串行，后者参数化。
• 不要在额外 goroutine 中通过 os.Setenv 绕过 t.Setenv；那只会隐藏共享状态竞争。

最后看清理边界：Setenv 的恢复由测试清理机制负责，但它并不改变环境变量的进程级属性。只要测试仍需要并行，就应优先消除这项全局依赖。

常见问题

t.Setenv 是不是只能在顶层测试里使用？

不是。串行子测试也可以使用，但它不能处在并行测试或并行祖先之下。限制针对的是执行域，不是“顶层/子测试”这个层级名称。

把 t.Setenv 放到 t.Parallel 前面可以吗？

不要把调用顺序当成隔离方案。当前测试一旦进入并行执行，进程环境仍然是共享的；更清晰的做法是拆出串行环境测试，或改为传递 Config。

为什么不直接手工恢复 os.Setenv？

手工恢复仍然面对同一个进程级竞争，而且失败路径容易漏恢复。串行环境测试使用 Setenv，业务行为测试使用局部输入，边界更容易检查。

官方事实可从 pkg.go.dev/testing 的 T.Setenv 与 T.Parallel 文档核对；实践中只要记住“环境是进程级、Config 可以是测试级”，这个限制就不难安排。