Go 1.25 testing/synctest 怎么从实验开关迁移：虚拟时间测试与 CI 检查

有一类 Go 并发测试，功能本身没问题，CI 却偶尔要等几百毫秒，甚至因为机器负载不同而抖动。Go 1.25 里的 testing/synctest 已经可以直接用于这类测试：它在隔离的测试环境里虚拟时间，并用 synctest.Wait 等待 goroutine 进入可观察状态。迁移的关键不是只替换包名，而是把旧实验开关、等待条件和 CI 版本矩阵一起收干净。

先看迁移范围：包已经稳定，测试语义没有变成魔法

Go 1.24 的 synctest 还是实验能力，旧项目常见的写法是给测试命令加上 GOEXPERIMENT=synctest。Go 1.25 把 testing/synctest 带到标准库可用状态，原实验 API 仍会在开关下保留一段时间，但不应继续把它当成新项目的默认入口。

这里先别急着全局删除环境变量。第一步应确认 go.mod、开发机和 CI 使用的 Go 版本是否一致；如果还有 Go 1.24 构建任务，直接删开关会把迁移变成兼容性问题。

把真实睡眠改成虚拟时间：先保留业务等待，再替换测试等待

假设被测函数收到事件后启动一个 goroutine，经过 5 秒超时仍没有结果就返回错误。普通测试会写 time.Sleep(6 * time.Second)，这种代码既慢又容易受调度影响。迁移时，业务代码里的计时器可以保留，测试代码负责把时间放进 synctest.Test 气泡里。

func TestTimeout(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        done := make(chan error, 1)
        go func() {
            timer := time.NewTimer(5 * time.Second)
            defer timer.Stop()
            

重点是顺序：先让 goroutine 进入等待，再让气泡知道当前没有可运行的工作，虚拟时钟才会向前走。若把断言写在普通的 synctest.Test 外面，或把共享 channel、网络请求放进气泡外，测试就失去了隔离条件。

旧实验代码怎么改：三处比包名更容易漏

清理测试命令里的开关

先在 Makefile、GitHub Actions、Dockerfile 和本地脚本里搜索 GOEXPERIMENT=synctest。Go 1.25 任务可以删除它；仍要支持 Go 1.24 的项目则保留兼容任务，并在迁移完成前用版本条件隔离。

把固定等待换成可观察的汇合点

synctest.Wait 解决的是“当前气泡内的 goroutine 是否都阻塞”，不是万能的“所有业务都完成”。如果 goroutine 还在等待外部 socket、真实文件或气泡外的 channel，等待条件就不成立。此时应把外部依赖改成气泡内的可控对象，或把这段留在普通集成测试中。

检查旧 API 与新 API 是否混用

迁移后最难排查的不是编译错误，而是测试在不同命令下表现不同。统一导入 testing/synctest，再用同一个 Go 版本运行普通测试和 go test -race ./...，避免“本地开了实验开关、CI 没开”的隐式差异。

CI 回归怎么验收：让版本、开关和竞态检查互相对得上

迁移提交至少要有三组检查：目标 Go 版本执行全量测试；执行竞态检测；扫描仓库里的实验开关，防止旧脚本继续把测试带入另一套语义。

go version; go test ./...; go test -race ./...; rg 'GOEXPERIMENT=synctest|GOEXPERIMENT=.*synctest' .

如果仓库还保留 Go 1.24 兼容任务，扫描结果不一定要为空，但必须能对应到明确的旧版本 job。验收记录里把 job 名、Go 版本和是否启用开关写清楚，比简单贴一个“全部通过”更有用。

常见问题

Go 1.25 里还需要设置 GOEXPERIMENT=synctest 吗？

新代码使用 testing/synctest 时不需要。只有为了兼容 Go 1.24 的旧任务，才可能暂时保留开关。

synctest.Wait 能替代所有 time.Sleep 吗？

不能。它只适合气泡内、可观察的并发等待；真实网络、文件系统和进程边界应使用对应的集成测试等待方式。

为什么测试仍然偶尔卡住？

先检查是否有 goroutine 在气泡外等待，或测试把未关闭的 channel、真实 I/O 放进了气泡。Wait 的等待对象必须属于同一个测试气泡。

迁移清单

• 确认目标构建和 CI 已使用 Go 1.25 或更高版本。
• 统一导入 testing/synctest，删除新任务上的实验开关。
• 把固定睡眠改为气泡内的状态汇合与明确断言。
• 跑普通测试、-race 测试和仓库脚本扫描。
• 对仍需 Go 1.24 的任务单独记录兼容边界，完成切换后再删除。