Go for range 里启动 goroutine 为什么会打印错值？从版本语义到兼容写法

很多 Go 初学者都会问：为什么在 for range 里启动 goroutine，打印出来的值和预期不一样？更容易混淆的是，Go 1.22 以后循环变量语义发生了变化，有些老文章里的“坑”在新模块里已经不完全一样了。本文按完整工作流来回答：先看 Go 版本和 go.mod，再看代码是否捕获循环变量，最后选择兼容写法并验证结果。

先说结论：如果模块声明为 go 1.22 或更高，for 循环变量默认按每轮独立变量处理，很多旧式捕获问题会自然消失；如果项目仍是旧语义，或者要兼容旧项目，推荐在循环体内显式复制变量，再传给 goroutine。这个写法在新旧语义下都清楚。

问题边界：到底是哪类 range 变量问题

这个问题通常出现在循环里启动 goroutine，并在 goroutine 函数体里直接使用循环变量。旧语义下，多个 goroutine 可能共享同一个循环变量，等它们真正运行时，变量已经变成了后面的值，于是输出看起来“串了”。

package main

import (
    "fmt"
    "sync"
)

func main() {
    names := []string{"api", "job", "web"}
    var wg sync.WaitGroup

    for _, name := range names {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fmt.Println(name)
        }()
    }

    wg.Wait()
}

在旧项目里，这段代码可能打印出重复值。问题不在 goroutine 本身，而在闭包里使用了循环变量。

全流程总览：range 变量和 goroutine 检查

不要只记一句“循环里要复制变量”。更稳的做法是把排查拆成五步：看 Go 版本、看 go.mod、找 range 变量、复制变量、验证输出。

这条流程的价值在于兼容现实项目。你可能正在维护一个老模块，也可能刚把工具链升到新版本但 go.mod 还没改。只有先确认模块语义，后面的判断才不会混乱。

阶段一：先看 go.mod 和 Go 版本

Go 1.22 开始，循环变量改成每轮独立变量。这个新语义按模块声明启用：当 go.mod 里写的是 go 1.22 或更高版本时，新语义生效；旧模块仍保持兼容行为。

go version
cat go.mod

检查点如下：

• 如果工具链和模块都已经进入 Go 1.22 以上语义，旧式 range 捕获问题会减少。
• 如果模块仍声明低于 1.22，就要按旧语义审查循环闭包。
• 如果团队有多个服务，不要只看本机 Go 版本，还要看每个仓库自己的 go.mod。

阶段二：识别 goroutine 是否捕获循环变量

第二阶段是找代码模式。重点不是所有 range，而是循环变量被闭包延迟使用：goroutine、回调函数、测试用例闭包、任务列表函数等都要看。

for _, item := range items {
    go func() {
        handle(item)
    }()
}

这类代码在旧语义下风险最高。即使项目已经使用新语义，显式传参也能让意图更清楚，尤其是在多人协作和跨版本维护时。

阶段三：选择兼容写法并验证输出

推荐写法有两种。第一种是在循环体内复制变量：

for _, item := range items {
    item := item
    go func() {
        handle(item)
    }()
}

第二种是把变量作为参数传入匿名函数：

for _, item := range items {
    go func(v string) {
        handle(v)
    }(item)
}

两种方式的目标一样：让 goroutine 拿到本轮自己的值。第二种写法更直观，尤其适合多个变量一起传入。

我的推荐流程：旧项目升级时怎么查

如果你正在维护旧项目，建议按下面流程处理：

1. 先扫 go.mod，确认模块声明版本。
2. 搜索 go func、range、测试用例里的闭包。
3. 对旧语义项目，优先给 goroutine 和回调里的循环变量加显式传参。
4. 补一个能稳定验证输出的单元测试，避免只靠人工观察日志。
5. 升级到 Go 1.22 以上语义前，先跑完整测试，确认行为变化符合预期。

如果只是新项目，我依然建议采用显式传参或循环体内复制。不是因为新语义不可靠，而是因为这类代码经常被复制到老仓库、脚本或示例中，写清楚能减少沟通成本。

常见误区与速查表

常见误区有三个。第一，只升级本机 Go 工具链，却没看 go.mod；第二，以为所有 range 问题都消失了，忽略旧模块兼容行为；第三，在代码评审里只看 goroutine，漏掉了测试用例闭包和回调列表。

总结一下：Go for range 里启动 goroutine 打印错值，本质是循环变量和闭包的关系。Go 1.22 以后新语义已经改善了这个问题，但真实项目仍要看模块版本。最稳的工程写法，是先确认版本边界，再把闭包里用到的循环变量显式固定下来，最后用测试验证输出。