Go 测试里修改环境变量为什么不能和 t.Parallel 一起用

Go 测试里，t.Setenv 不能和同一个测试中的 t.Parallel 随意混用，根本原因不是语法顺序，而是环境变量属于整个进程。并行测试共享这个进程，如果一个用例把 APP_MODE 改成 test，另一个用例就可能同时读到这个值。Go 的 testing 包因此会主动阻止这类组合。

t.Setenv 适合明确串行的环境测试；需要并行时，把环境值改成函数参数或配置对象传入，不要让并行用例共同修改进程环境。

t.Setenv 为什么会挡住并行测试

t.Setenv 不是给当前 goroutine 创建一份局部变量。它调用 os.Setenv，影响测试二进制所在的整个进程；测试结束时再借助 Cleanup 恢复调用前的值。因此，恢复机制只能解决“测试结束后还原”，不能解决“测试运行期间被其他并行用例看到”的问题。

func TestReadModeFromEnv(t *testing.T) {
    t.Setenv("APP_MODE", "test") // 修改进程环境，并登记自动恢复

    got := os.Getenv("APP_MODE") // 当前进程内的其他代码也能读到这个值
    if got != "test" {
        t.Fatalf("APP_MODE = %q, want test", got) // 失败时保留实际值
    }
}

官方实现会在设置前检查当前测试及其父测试是否已经进入并行状态。没有冲突时，t.Setenv 仍然是很方便的测试辅助方法；但它的安全范围是“这一段测试生命周期内没有并行环境变量读写”，不是“只有当前函数能看到变量”。

哪几种 t.Parallel 组合会触发冲突

最直接的情况是先调用 t.Parallel()，再调用 t.Setenv()。另一种常见情况是父测试已经并行，子测试虽然没有显式并行，仍然不能设置环境变量，因为它有并行祖先。反过来先设置环境变量、再让当前测试并行，testing 也会拒绝：设置动作会标记当前测试禁止进入并行状态。

func TestBadOrder(t *testing.T) {
    t.Setenv("FEATURE_X", "on") // 先修改进程环境
    t.Parallel()                  // 随后进入并行，触发 testing 冲突
}

func TestParallelAncestor(t *testing.T) {
    t.Parallel() // 父测试进入并行
    t.Run("env", func(t *testing.T) {
        t.Setenv("FEATURE_X", "on") // 子测试继承并行祖先，不能这样写
    })
}

冲突信息通常是 testing: test using t.Setenv ... can not use t.Parallel。不要把它当作偶发竞态，也不要只增大 -parallel 的值；问题在于测试结构同时要求“修改全局状态”和“允许并发执行”。

需要并行时怎么改测试结构

如果目标是验证“读取不同配置会得到什么结果”，不必真的改环境变量。把配置作为参数传进被测函数，表驱动子测试就能安全并行；环境变量到配置对象的映射，另写一个保持串行的测试覆盖即可。

type Config struct {
    Mode string
}

func TestRenderMode(t *testing.T) {
    cases := []struct {
        name string
        mode string
        want string
    }{
        {name: "test", mode: "test", want: "测试模式"},
        {name: "prod", mode: "prod", want: "生产模式"},
    }

    for _, tc := range cases {
        tc := tc // 为每个并行子测试固定当前用例副本
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel() // 这里只读独立参数，不触碰进程环境

            got := renderMode(Config{Mode: tc.mode}) // 显式注入配置
            if got != tc.want {
                t.Fatalf("renderMode(%q) = %q, want %q", tc.mode, got, tc.want)
            }
        })
    }
}

如果被测入口只能读取环境变量，就把那部分用例单独放在非并行测试中。不要为了让整个文件更快而把父测试改成 t.Parallel；父级并行会把限制传给后代。另一个原则是：并行用例可以读取进程启动时就固定的环境，但同一组测试里不能同时有其他用例调用 os.Setenv、os.Unsetenv 或 t.Setenv 改写它。

发布前用检查清单固定边界

提交测试代码前，可以按下面的顺序快速判断：

• 搜索 t.Setenv、os.Setenv 和 os.Unsetenv，确认修改点集中且有恢复逻辑。
• 从每个修改点向上检查父测试，确保没有隐藏的 t.Parallel 祖先。
• 环境变量测试只验证覆盖、读取和恢复；业务分支测试改用显式配置并行执行。
• 不要把 Cleanup 当成并发隔离。它保证最终恢复，不保证修改期间不被其他测试观察。

这样处理后，t.Setenv 的职责很清楚：它负责让串行测试临时拥有一组环境值；t.Parallel 负责并发调度，两者不在同一条测试边界里争夺进程级状态。

常见问题

t.Setenv 会自动恢复环境变量吗？

会。它使用 Cleanup 在当前测试及其子测试完成后恢复原值，但恢复动作不等于并行隔离。

只有子测试调用 t.Parallel，也不能在父测试 Setenv 吗？

环境变更的安全做法是让整棵相关测试树保持串行。若子测试要并行，父测试不要在同一生命周期内承担环境覆盖，改为显式注入配置。

把 t.Parallel 放到 t.Setenv 前面可以绕过限制吗？

不能。t.Parallel 后调用 t.Setenv 会直接冲突；先 t.Setenv 再并行也会被测试框架禁止。

提高 go test 的 -parallel 参数能解决吗？

不能。-parallel 只调整并行测试的调度上限，不会把进程级环境变成测试级或 goroutine 级状态。