go test -timeout 仅控制整个测试进程总耗时，不作用于单个 TestXxx 或 t.Run()；限制子测试需手动用 context.WithTimeout 或 goroutine + select 实现。
go test -timeout 只控制整个测试命令的总耗时，不能给单个 TestXxx 或 t.Run() 设超时；真要限制子测试耗时，必须手动加 context 或 goroutine 控制。
go test -timeout 是什么、不是什么
go test -timeout 是进程级总闸门：从你敲下回车开始计时，到整个 go test 进程退出为止。比如 go test -timeout 10s，10 秒一到，不管当前在跑哪个 TestXxx、有没有卡在 t.Run("sub", ...) 里、goroutine 是否还在 sleep，进程直接被 KILL，报错 test killed with quit: ran too long (10s)。
它不作用于单个函数，也不穿透到 http.Client.Timeout 或 context.WithTimeout —— 三者完全独立。Go 1.22+ 支持 -timeout 5m30s，旧版本建议统一用 s 或 m，否则会报 time missing unit in duration。
- IDE（如 VS Code Go 扩展）可能缓存上一次的
-timeout参数，改了没生效？试试重启测试终端或清 IDE 缓存 - CI 平台（如 GitHub Actions）自带
timeout-minutes，若平台级 timeout 先触发，go test -timeout根本没机会起作用 - 测试里用了
time.Sleep+select+time.After却没监听ctx.Done()，这种写法不响应进程级中断，只能靠-timeout强杀
为什么单个 t.Run() 还是卡住
Go 测试框架没有原生支持 “每个 t.Run() 单独设超时” 的机制。你看到的卡住，往往是因为：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 调用了阻塞式系统调用（如未设超时的
exec.Command().Run()），子进程没继承信号，go test杀的是主进程，子进程残留 - 用了
httptest.Server但没显式调srv.Close()，端口占着，下次测试直接失败，看起来像超时 - 外层
go test -timeout 1m包含所有 setup/teardown 时间，别指望 10 个子测试各占 5s 就刚好凑满 1m —— 调度、GC、I/O 延迟都会吃掉
如何真正控制单个测试或子测试的耗时
得手动加控制。对简单场景，推荐在 t.Run() 内部用 context.WithTimeout：
func TestAPI(t *testing.T) {
t.Run("should return 200 on valid request", func(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, "GET", "http://localhost:8080/api", nil)
resp, err := client.Do(req) // client 必须尊重 ctx
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
t.Fatal("request timed out")
}
t.Fatal(err)
}
defer resp.Body.Close()
})
}
更通用的做法是封装一个辅助函数：
- 写
RunWithTimeout(t *testing.T, d time.Duration, f func(t *testing.T))，内部启动 goroutine +select等待完成或超时，超时则t.Fatal - 注意别漏清理：比如
httptest.NewUnstartedServer启动后记得srv.Start()和defer srv.Close() - 避免嵌套超时误判：外层
go test -timeout是总预算，子测试超时只是其中一环，不要让它们叠加成不可控延迟
容易被忽略的细节
最常踩的坑不是不会写超时，而是超时逻辑和资源生命周期没对齐：
-
context.WithTimeout必须传给client.Do(req)，只设client.Timeout却不传req.Context()，底层连接不会关，资源泄漏 -
defer cancel()必须写，否则 context 不释放，TCP 连接可能持续等待 - 判断超时要用
errors.Is(err, context.DeadlineExceeded)，不是err == context.DeadlineExceeded，也不是字符串匹配 - UDP 场景要用
conn.SetReadDeadline，原始 socket 要用setsockopt，HTTP 客户端那一套不适用
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
