Go go test 使用 t.Parallel 时环境变量互相覆盖怎么办

我第一次把 Go 测试改成并行时，最容易误判的一点是：每个 *testing.T 看起来像独立对象，但进程环境并不会因此变成多份。两个子测试如果同时读写同一个环境变量，问题不是“恢复时机慢了一点”，而是它们从一开始就共享了同一份状态。

结论很明确：不要在调用了 t.Parallel() 的测试里使用 t.Setenv，也不要在有并行祖先的测试中使用它。t.Setenv 会改动整个测试进程的环境；需要并行时，把配置改成显式参数或注入依赖。只有确实要覆盖进程环境的测试，才保留串行边界。

官方文档：https://pkg.go.dev/testing@go1.27.3#T.Setenv

先看清：环境变量不是子测试私有数据

t.Setenv 的便利之处在于它会调用 os.Setenv，并在测试清理阶段恢复原值。但这个清理发生在测试结束之后，不能把中间时刻的并发读写隔离开。

例如下面的写法把两个不同值放进并行子测试：

func TestMode(t *testing.T) {
	// 两个子测试会同时进入并行队列，但环境变量只有一份。
	for _, tc := range []struct {
		name string
		mode string
	}{
		{name: "fast", mode: "fast"},
		{name: "safe", mode: "safe"},
	} {
		t.Run(tc.name, func(t *testing.T) {
			// 这里的写入作用于整个测试进程，不能按子测试隔离。
			t.Setenv("APP_MODE", tc.mode)
			t.Parallel()
			if got := os.Getenv("APP_MODE"); got != tc.mode {
				// 读到另一个子测试的值时，失败表现会随调度变化。
				t.Fatalf("APP_MODE = %q, want %q", got, tc.mode)
			}
		})
	}
}

这段代码的正确处理不是调整 Cleanup，而是先撤掉“并行测试修改进程环境”的组合。并行测试需要共享只读输入可以，但不能把 os.Getenv 当成每个子测试的私有字段。

为什么加了 t.Setenv 仍然会互相覆盖

Go 官方对 t.Setenv 的限制是硬规则：它影响整个进程，所以不能用于并行测试，也不能用于有并行祖先的测试。t.Parallel 则表示当前测试会与其他并行测试一起运行，并等待非并行测试完成。

这两个 API 的职责并不矛盾：一个负责临时改进程状态，一个负责放宽测试调度；真正冲突的是它们操作的状态范围不同。下面这张结构图把“子测试对象”和“进程环境”分成两层，重点是环境变量的箭头仍然指向同一个共享节点。

并行测试的首选改法：把环境差异变成参数

如果被测函数只是根据一个配置值选择行为，最好不要在测试里改环境。把读取动作放在边界处，核心逻辑接收显式配置，测试就可以安全并行：

type Config struct {
	Mode string
}

func render(c Config) string {
	// 核心逻辑只依赖传入配置，不读取进程级环境。
	if c.Mode == "safe" {
		return "safe-output"
	}
	return "fast-output"
}

func TestRender(t *testing.T) {
	for _, tc := range []struct {
		name string
		cfg  Config
		want string
	}{
		{name: "fast", cfg: Config{Mode: "fast"}, want: "fast-output"},
		{name: "safe", cfg: Config{Mode: "safe"}, want: "safe-output"},
	} {
		t.Run(tc.name, func(t *testing.T) {
			// 每个并行用例只读自己的值，不触碰 os.Environ。
			t.Parallel()
			if got := render(tc.cfg); got != tc.want {
				t.Fatalf("render() = %q, want %q", got, tc.want)
			}
		})
	}
}

这种改法的收益不只是避免覆盖：失败用例会直接暴露输入，函数也更容易被复用。若真实程序必须从环境启动，再在较外层读取一次环境，转换为 Config 后传入内部逻辑即可。

确实要改环境时，串行边界要写得很清楚

有些测试就是要覆盖环境读取路径，例如验证启动配置是否正确解析。这类测试可以继续使用 t.Setenv，但不要调用 t.Parallel，也不要让父测试先调用 t.Parallel。把它们单独放在串行测试函数中，边界会更容易审查：

func TestLoadFromEnv(t *testing.T) {
	// 本测试故意保持串行，因为它修改当前进程的环境。
	t.Setenv("APP_MODE", "safe")

	got := loadConfigFromEnv()
	if got.Mode != "safe" {
		// 失败时同时打印期望值和实际值，方便定位读取路径。
		t.Fatalf("mode = %q, want %q", got.Mode, "safe")
	}
}

审查时可以按下面的表快速判断：

如果运行时看到关于 t.Setenv 和 t.Parallel 的冲突提示，优先检查测试树的父级，而不是继续给环境变量加锁。锁只能约束你自己的读写，不能改变测试框架对进程级环境的作用范围。

常见问题

只在 t.Parallel 之后调用 t.Setenv，能避开冲突吗？

不能。调用顺序不是隔离机制，Go 会拒绝当前测试或并行祖先使用进程级环境修改。

t.Setenv 会不会因为 Cleanup 自动恢复，所以并行也安全？

不会。Cleanup 只负责测试结束后的恢复，中间的读取仍可能看到其他测试写入的值。

所有读取环境变量的测试都必须串行吗？

只有需要修改环境或依赖可变环境值的测试需要串行。把环境读取转换为不可变配置后，核心逻辑测试可以并行。

这类问题的判断标准其实很简单：测试要并行，就让输入显式化；测试要改进程环境，就让它保持串行。两种目标都合理，但不要把它们放在同一个测试边界里。