Go 测试t.Parallel 与共享环境变量冲突怎么办

Go 测试里同时使用 t.Parallel 和环境变量，修复重点不是给设置操作加延时，而是明确谁在修改进程共享状态。测试需要设置不同环境值时，让环境适配测试保持串行；业务逻辑需要并行覆盖时，把配置作为参数注入，避免每个用例改写同一份进程环境。

还要区分两种失败：testing 直接拒绝 Setenv 与 Parallel 的组合，和绕过框架后出现的偶发配置串值。前者是保护机制，后者是隔离契约已经被破坏。下面的代码和命令供读者在独立示例模块中复现，未作为本文的本机执行记录。

先区分框架报错和读到了别人的配置

先保留失败的测试全名、堆栈位置以及有关的环境变量键名，不要把整个环境或密钥值输出到日志。如果调用停在 t.Setenv 或 t.Parallel 附近，应优先检查两者是否出现在同一测试或祖先链上。把 Setenv 移到 Parallel 前面并不能使这对操作合法。

如果没有框架报错，却出现“local 用例读到 remote 配置”，搜索测试辅助函数、os.Setenv、os.Unsetenv 和初始化缓存。环境变量属于整个测试进程，不是某个 goroutine 或某个 testing.T 的私有字段。标准库环境访问的内部同步不等于多个测试的业务隔离；因此没有 race 报告，也可能有配置串值。

把 Parallel 祖先和环境读写一起列出来

列出“测试祖先、环境写入者、环境读取者”三类对象。子测试自己没有 Parallel，但其父测试调用了 Parallel，仍不能在子测试调用 Setenv。辅助函数中隐藏的 Parallel 或 Setenv 也要计入，而不能只检查当前文件。

同一进程中的进程环境由所有读取者共享。os.Setenv 是环境写入者，os.Getenv 是环境读取者，测试祖先链决定测试是否落在并行上下文中。测试框架只能管理参与它的测试，不能替你隔离包级后台 goroutine、自行启动的 goroutine 或外部资源。

一个容易混淆的情况是：串行父测试先设置一个固定值，多个并行子测试只读该值。在祖先没有并行、后代不再改环境、也没有脱离测试框架的后台改写者时，这属于共享只读夹具，不等于“每个并行子测试都能设置不同的值”。本文的推荐示例直接串行测试环境入口，减少这种层级约束。

环境适配测试保持串行并交给 Setenv 恢复

把下面内容保存为独立模块中的 env_test.go。示例要求 Go 1.17 或以上以使用 t.Setenv。每个子测试不调用 Parallel，父级也不调用；用例结束时由 testing 恢复此前的环境状态。

package configdemo

import (
    "os"
    "testing"
)

// 环境入口留在适配层，业务函数不直接访问进程状态。
func modeFromEnv() string {
    return os.Getenv("ARTICLE_DEMO_MODE")
}

func TestModeFromEnv(t *testing.T) {
    // 此测试及其所有祖先都不调用 Parallel。
    cases := []struct {
        name string
        value string
    }{
        {"local", "local"},
        {"remote", "remote"},
    }
    for _, tc := range cases {
        tc := tc // 兼容旧版循环变量语义。
        t.Run(tc.name, func(t *testing.T) {
            // 子测试结束时恢复原值，包括原本不存在的状态。
            t.Setenv("ARTICLE_DEMO_MODE", tc.value)
            if got := modeFromEnv(); got != tc.value {
                t.Fatalf("mode = %q; want %q", got, tc.value)
            }
        })
    }
}

这里的检查点是两次断言分别匹配当前用例，而不是控制台打印过某个值。Setenv 注册的清理属于相应测试的生命周期；Cleanup 会在该测试及所有子测试完成后执行，多个清理按后注册先执行。它负责恢复，不创建环境副本。

不要改为“先 os.Setenv，再在父函数 defer 恢复”。并行子测试会暂停，等待父测试函数返回后才继续；父函数的 defer 可能在子测试真正读取前就已恢复环境。使用 t.Cleanup 可以修正这种清理生命周期，但仍不能允许并行用例分别改写同一个变量。也不要把 os.Setenv 当作绕开 Setenv 限制的替代方案。

需要并行时把读取配置改为显式依赖

把下面内容保存为同一示例模块的 logic_test.go。配置对象只含字符串且按值传入；每个用例拥有自己的 cfg，不依赖可变的全局配置。环境入口留给上一节的串行适配测试，业务分支则可并行覆盖。

package configdemo

import "testing"

type config struct {
    mode string
}

// 配置按值传入，不缓存到包级变量，也不读取环境。
func label(c config) string {
    if c.mode == "remote" {
        return "network"
    }
    return "disk"
}

func TestLabel(t *testing.T) {
    t.Parallel()
    cases := []struct {
        name string
        cfg config
        want string
    }{
        {"local", config{mode: "local"}, "disk"},
        {"remote", config{mode: "remote"}, "network"},
    }
    for _, tc := range cases {
        tc := tc // 每个闭包保留独立用例。
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            if got := label(tc.cfg); got != tc.want {
                t.Fatalf("label = %q; want %q", got, tc.want)
            }
        })
    }
}

配置注入组由“用例配置、业务函数、断言目标”组成，环境适配组由“环境入口、串行适配测试、恢复责任”组成。用例配置给业务函数提供参数，断言目标约束业务函数的返回值；串行适配测试覆盖环境入口，同时承担恢复责任。两个测试层的边界不同，不应为了并行而把所有状态塞进包级变量。

如果配置包含 map、切片或指针，结构体复制不代表底层存储独立。应使用只读共享数据或为用例创建独立副本，避免并行测试重新共享可变对象。环境在 init 或 sync.Once 中被缓存时，后续 Setenv 不会自动刷新缓存：优先把加载动作变成显式构造，无法改造的进程启动行为再用独立子进程和各自 Env 测试。

局部互斥锁通常不是好补丁。只有所有读者和写者都遵守同一把锁，并把完整的设置、业务读取、恢复纳入临界区时，才可能实现人为串行；给 Setenv 单独加锁不够。持锁跨越 Parallel 的暂停点还可能阻塞其他测试。因此优先选择配置注入或真正串行的适配测试。

用不同调度条件复查，而不是只看一次通过

在新的空目录初始化示例模块，再加入前面两个文件。以下命令由读者执行，不是本文发布过程中执行的测试，也不提供虚构的通过输出。

# 仅在独立的新示例目录初始化。
go mod init example.com/configdemo
# 禁用结果缓存，重复并打乱顺序，检查测试的隔离性。
go test -count=20 -shuffle=on -parallel=8 .
# 在支持竞态检测器的平台上补充检查。
go test -race -count=5 -shuffle=on -parallel=8 .

预期检查的是 TestModeFromEnv 的串行环境断言与 TestLabel 的独立配置断言都不依赖先后顺序。失败时保存 shuffle 的种子和测试全名，便于复现；先修复共享状态，再讨论耗时。一次通过、甚至多次通过，都不是不存在污染的数学证明。

• 确认当前测试及祖先的 Parallel，而不是只删除叶子上的一行。
• 确认环境修改仅发生在串行适配测试，并由 Setenv 恢复原状态。
• 确认并行业务用例没有从全局环境、可变缓存或共享容器偷读配置。
• 确认后台任务在所属测试结束前退出，不让恢复后的环境仍被旧任务读取。

把 -parallel 设置成 1 可以消除 Setenv 报错吗？

不可以把它当成修复。这个参数限制并行测试的调度数量，不会删除 Parallel 标记，也不会改变 Setenv 对并行上下文的限制。它也不限制测试自行创建的 goroutine。对外部数据库、文件等资源的冲突，还需要另做资源隔离。

只删除当前子测试的 Parallel 为什么仍然失败？

检查父测试以及更高层祖先，尤其是统一测试套件和辅助函数。只要存在并行祖先，子测试修改进程环境仍不满足 Setenv 的使用条件。

为什么 -race 没报错却读到错误配置？

竞态检测关注实际执行中未同步的内存访问，不保证业务层的“设置环境再读取”组合属于某个用例。并发安全的单次环境操作也可能组成相互干扰的测试。

相关官方说明：Setenv、Parallel、Run 和 Cleanup 的使用约定见 https://pkg.go.dev/testing；子测试的并行分组及父子生命周期见 https://go.dev/blog/subtests；框架实现细节可查 https://go.dev/src/testing/testing.go。