Go 1.26 升级后 synctest 实验开关失效怎么办：从 GOEXPERIMENT 到 testing/synctest

如果一个并发测试在 Go 1.25 里依赖 GOEXPERIMENT=synctest，升级到 Go 1.26 后最常见的处理不是继续补环境变量，而是把实验 API 改成正式的 testing/synctest 包。Go 1.25 已经让这个包进入标准库，旧实验入口只是过渡路径；迁移完成后，测试应在不设置实验开关的情况下直接通过。

先确认项目依赖了哪条 synctest 路径

Go 1.25 同时留下了两种痕迹：正式的 testing/synctest 已可直接使用，旧实验接口仍能通过环境变量暂时打开。项目里只要还出现下面任意一项，就应该把它视为迁移待办，而不是稳定配置。

rg -n "GOEXPERIMENT|synctest|testing/synctest" .
go version
go env GOEXPERIMENT

重点排查CI配置、测试文件和配套脚本。不要只验证本地命令能否跑通，开发机上残留的环境变量，经常会掩盖模块代码实际上还没完成迁移的问题。

正式包和旧实验入口的差异在哪里

Go 1.25 的发布说明把 testing/synctest 作为标准库新包介绍：Test 在隔离的 bubble 中运行测试函数，Wait 等待当前 bubble 内的 goroutine 阻塞，并让时间在可推进的虚拟时钟中运行。旧实验 API 的兼容存在是为了过渡，不应成为 Go 1.26 项目的默认前提。

最小迁移示例：让虚拟时间测试回到正式 API

下面的测试让一个 goroutine 等待 10 秒后写入结果，再用 synctest.Test 建立隔离环境，用 synctest.Wait 等待它完成。正式包的导入路径就是迁移的关键。

package timer_test

import (
    "testing"
    "testing/synctest"
    "time"
)

func TestDelayedResult(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        done := make(chan string, 1)
        go func() {
            time.Sleep(10 * time.Second)
            done 

改完代码后不要为了省事把测试改成真实等待10秒。这个API的价值正是让时间推进与阻塞判断完全可控；需要真实墙上时钟的场景，单独拿出来验收就好。

迁移时最容易漏掉的三个位置

CI 环境变量

删除工作流、Makefile、容器构建参数和本地脚本里的 GOEXPERIMENT=synctest。保留它会让测试继续走旧路径，等于没有验证 Go 1.26 的正式包。

测试辅助包

自定义测试工具函数可能间接封装了旧的实验API。全局搜索只能找到直接引用的位置，还要顺着工具函数的调用链路完整跑一次测试，确认没有隐式初始化旧逻辑的情况。

版本矩阵

如果项目同时支持 Go 1.25 和 Go 1.26，直接以模块声明和CI构建矩阵为准，不要用运行时判断版本字符串的方式选择导入路径。正式包在 Go 1.25 已存在，通常可以先统一所有相关代码，再调整最低版本声明。

用三轮检查确认迁移真的完成

1. 代码检查：确认正式导入路径存在，仓库中不再有旧实验变量和旧API名称。
2. 版本检查：在目标 Go 版本下运行 go test ./...，再运行 go test -race ./...。
3. 环境检查：在没有继承开发机变量的干净 shell 中执行测试，核对 go env GOEXPERIMENT 不再提供 synctest 过渡开关。

env -u GOEXPERIMENT go test ./...
env -u GOEXPERIMENT go test -race ./...

如果只有手动设置旧环境变量时测试才通过，优先检查是否仍在使用实验API；如果race模式失败，要区分清楚是原有竞态问题，还是测试对时间的假设发生了变化，不要用重新打开实验开关来掩盖问题。

相关问题

Go 1.25 还能继续使用 GOEXPERIMENT=synctest 吗？

可以作为过渡，但不适合作为新代码的默认方案。Go 1.25 已提供正式的 testing/synctest，应尽早迁移。

迁移后为什么不能保留实验开关？

这种写法会让CI没有覆盖正式包的代码路径，而且旧实验入口计划在 Go 1.26 清理。之前的兼容脚本统一改成调用同一套正式测试命令即可。

synctest 能替代所有并发测试工具吗？

不能。它适合验证虚拟时间和协程阻塞关系；数据竞争仍应配合race检测模式验证，真实网络、文件读写和调度压力场景也需要独立做集成测试。

迁移清单

把 GOEXPERIMENT=synctest 当成删除项，把 testing/synctest 当成唯一代码入口，再用无环境变量的普通测试、race 测试和干净 shell 各跑一遍。这样升级 Go 1.26 时，失败信息才真正反映项目代码，而不是旧实验开关的残留。