Go testing.T Setenv 怎样隔离环境变量测试

Go 测试需要临时切换环境变量时，优先使用 t.Setenv，不要在测试里手写 os.Setenv 和恢复逻辑。它会记住变量原来的状态，并在当前测试及其子测试结束后自动恢复，适合验证配置读取、开关和降级分支。

官方资料：https://pkg.go.dev/testing

最小规则是：用 t.Setenv("KEY", "value") 设置测试值；不要让同一个进程里的并行测试同时改环境变量。如果测试必须并行，把环境变量改成函数参数或配置对象。

Setenv 解决的是哪类测试污染

环境变量属于进程级状态。一个测试直接调用 os.Setenv 后，如果没有可靠地恢复旧值，后续测试可能读到错误配置；即使手动恢复，也容易漏掉“变量原本不存在”这一种状态。

testing.T.Setenv 的职责很窄：设置一个键值，并把恢复动作注册到测试清理阶段。恢复时不仅要还原旧字符串，还要还原变量是否存在，因此比固定写回空字符串更安全。

最小示例：让配置读取只看到测试值

假设业务函数从环境变量读取运行模式。测试只需要在进入断言前设置值，函数本身不需要知道测试生命周期。

package config_test

import (
    "os"
    "testing"
)

func readMode() string {
    // 没有配置时返回默认模式，便于测试缺省分支。
    if mode := os.Getenv("APP_MODE"); mode != "" {
        return mode
    }
    return "default"
}

func TestReadMode(t *testing.T) {
    // Setenv 会在本测试结束后自动恢复 APP_MODE 的原始状态。
    t.Setenv("APP_MODE", "staging")

    if got := readMode(); got != "staging" {
        // 失败信息保留实际值，便于区分读取错误和环境污染。
        t.Fatalf("readMode() = %q, want %q", got, "staging")
    }
}

这个例子没有手动调用 os.Unsetenv，也没有保存旧值。测试结束后，APP_MODE 会回到测试开始前的状态；如果开始前变量不存在，它仍然会恢复为不存在。

支持范围：Go 1.17 起可用于 T、B 和 F

官方 testing 文档把 Setenv 提供给 *testing.T、*testing.B 和 *testing.F，对应测试、基准测试和模糊测试。本文标题中的 testing.T 是普通单元测试的常用入口。

如果项目需要兼容更早的 Go 版本，不能直接假设 T.Setenv 存在。此时可以在测试辅助函数中保存旧值、记录是否存在，并用 t.Cleanup 注册对称恢复；不要把旧值写死成空字符串。

func setEnvCompat(t *testing.T, key, value string) {
    // 先保存旧值和存在性，区分“空字符串”和“没有这个变量”。
    old, existed := os.LookupEnv(key)
    if err := os.Setenv(key, value); err != nil {
        // 环境变量设置失败时立即结束测试，避免继续断言假状态。
        t.Fatalf("set %s: %v", key, err)
    }
    t.Cleanup(func() {
        // 清理阶段按原始存在性恢复，避免把测试状态泄漏给后续测试。
        if existed {
            _ = os.Setenv(key, old)
            return
        }
        _ = os.Unsetenv(key)
    })
}

在支持 t.Setenv 的项目中，不必保留这段兼容代码；它主要帮助理解 Setenv 自动清理的边界。

子测试如何继承，以及覆盖值何时恢复

父测试调用 t.Setenv 后，子测试会看到这个值，因为它们运行在同一个测试进程中。子测试还可以再次调用 Setenv 覆盖同一个键；子测试结束时先恢复自己的旧值，父测试仍保留自己的设置，父测试结束后再恢复更外层的旧值。

func TestModes(t *testing.T) {
    // 父测试提供所有子测试共享的默认值。
    t.Setenv("APP_MODE", "test")

    t.Run("default", func(t *testing.T) {
        // 子测试继承父测试的环境变量，不要在这里调用 Parallel。
        if got := os.Getenv("APP_MODE"); got != "test" {
            t.Fatalf("APP_MODE = %q, want %q", got, "test")
        }
    })

    t.Run("override", func(t *testing.T) {
        // 子测试覆盖的值只在这个子测试及其后代范围内有效。
        t.Setenv("APP_MODE", "preview")
        if got := os.Getenv("APP_MODE"); got != "preview" {
            t.Fatalf("APP_MODE = %q, want %q", got, "preview")
        }
    })

    // 子测试结束后，父测试仍应看到自己的 test 值。
    if got := os.Getenv("APP_MODE"); got != "test" {
        t.Fatalf("APP_MODE after subtest = %q, want %q", got, "test")
    }
}

这种写法适合按模式拆分的配置测试。为了让每个子测试自包含，也可以把 Setenv 放进每个 t.Run 内部，但仍然要保持它们串行运行。

为什么 Setenv 不能和 Parallel 混用

环境变量不是当前测试对象的私有字段，而是整个进程都能读到的状态。一个测试把 APP_MODE 改成 preview 时，另一个并行测试可能同时读到这个值，因此结果会取决于调度顺序。

官方文档明确说明：Setenv 不能在并行测试中使用，也不能在拥有并行祖先的测试中使用。不要用“先设置、再马上断言”来规避，这只能缩短冲突窗口，不能消除冲突。

func TestParallelSafe(t *testing.T) {
    cases := []struct {
        name string
        mode string
    }{
        {name: "staging", mode: "staging"},
        {name: "preview", mode: "preview"},
    }

    for _, tc := range cases {
        tc := tc
        t.Run(tc.name, func(t *testing.T) {
            // 环境变量测试保持串行；不要在这里调用 t.Parallel。
            t.Setenv("APP_MODE", tc.mode)
            if got := readMode(); got != tc.mode {
                t.Fatalf("readMode() = %q, want %q", got, tc.mode)
            }
        })
    }
}

如果测试数量很多且必须并行，推荐把配置读取函数改成接收配置参数，例如 readModeFrom(cfg Config)，让每个并行子测试拥有自己的输入；环境变量只在最外层启动配置时读取一次。

一张速查表：该用 Setenv 还是依赖注入

最后检查三件事：测试是否误用了 t.Parallel，缺省变量是否真的覆盖了“未设置”分支，以及业务函数是否把环境变量读取和核心逻辑混在一起。只要并发测试需要不同配置，优先使用显式参数隔离。

常见问题

Setenv 会自动删除变量吗？

它恢复的是测试开始前的状态。开始前不存在就恢复为不存在，开始前有值就恢复原值，并不是无条件删除。

能在 TestMain 里用 t.Setenv 吗？

TestMain 没有普通测试函数的 *testing.T 参数，不能直接使用。可以在具体测试中设置，或在测试启动阶段用明确的进程配置并负责整体清理。

为什么测试单独运行通过，整包运行失败？

常见原因是直接修改环境变量后没有恢复，或者把环境变量测试标成并行。先把设置动作集中到 t.Setenv，再移除并行标记或改为显式配置输入。