Go 1.25 容器 CPU 限额下 GOMAXPROCS 为什么会变化

如果同一个 Go 服务从宿主机迁入容器后，GOMAXPROCS 从几十变成 2、3 或 4，这通常不是程序随机改了并发配置，而是 Go 1.25 在 Linux 上开始读取容器所在 cgroup 的 CPU 吞吐限额。它会把逻辑 CPU 数、CPU 亲和性和 cgroup CPU quota 放在一起计算默认值；CPU limit 变化时，默认值还可能随运行时环境更新。

先看懂 GOMAXPROCS 和 CPU limit 不是同一个概念

GOMAXPROCS 是并行度上限：它限制同一时刻最多有多少个 goroutine 被 Go 运行时并行执行。容器 CPU limit 更接近吞吐上限，例如 2 个 CPU 的限额表示在一个调度周期内最多使用相当于 2 个 CPU 的 CPU 时间。前者限制“同时跑多少”，后者限制“一段时间内总共能跑多少”。

因此，宿主机有 32 个逻辑 CPU，并不代表容器里的 Go 程序应该一直用 32 作为并行度。Go 1.25 的默认策略正是试着让并行度接近容器的有效 CPU 能力，减少高并行度触发 cgroup throttling 后对尾延迟的影响。

Go 1.25 为什么会让这个值发生变化

在没有手动指定 GOMAXPROCS 时，Linux 下的 Go 运行时会综合三个视角：机器的逻辑 CPU 数、进程的 CPU affinity，以及 cgroup 的平均 CPU 吞吐限额。实际默认值通常取这些约束中的较小值；cgroup v2 通常从 cpu.max 读取 quota/period，cgroup v1 则对应 cpu.cfs_quota_us 和 cpu.cfs_period_us。

容器编排里的 CPU limit 通常对应 cgroup quota，而 CPU request 是调度时的保障或权重信息，并不等于硬吞吐上限，所以 Go 不会用 request 来设置默认 GOMAXPROCS。例如有效限额是 2.5 CPU 时，运行时需要得到正整数，会向上取整以避免浪费这部分限额；但它也不会在逻辑 CPU 或亲和性都至少为 2 时把默认值压到 1。

这解释了“启动时是 4，过一会儿变成 2”这类现象：如果默认模式仍然开启，Go 1.25 会定期检查逻辑 CPU、亲和性或 cgroup quota 的变化，更新默认值，频率最高大约每秒一次，空闲时可能更慢。

package main

import (
    "fmt"
    "runtime"
)

func main() {
    // 读取当前运行时采用的并行度，不会修改 GOMAXPROCS。
    current := runtime.GOMAXPROCS(0)
    // NumCPU 只表示运行时看到的逻辑 CPU 数，不等同于 cgroup CPU limit。
    logical := runtime.NumCPU()
    fmt.Printf("GOMAXPROCS=%d NumCPU=%d\n", current, logical)
}

这段代码只能帮助你区分“当前并行度”和“逻辑 CPU 视角”，不能把 NumCPU 当成容器 CPU limit 的替代读数。

手动覆盖后，自动更新为什么不再生效

如果设置了正整数的 GOMAXPROCS 环境变量，或在程序里调用 runtime.GOMAXPROCS(n)，运行时会把它视为自定义值，默认的 cgroup 感知与周期更新就不会按原方式接管。这样做适合确实需要固定并行度的场景，但也意味着容器限额后续变化不会自动反映到这个值。

Go 1.25 还提供两个明确的开关：GODEBUG=containermaxprocs=0 关闭 cgroup CPU 限额参与默认计算，GODEBUG=updatemaxprocs=0 关闭周期更新。它们解决的是不同问题，前者影响“怎么算初始默认值”，后者影响“默认值是否继续跟着环境变化”。

如果历史启动参数曾经覆盖过默认值，但现在希望恢复 Go 的默认策略，可以调用新增的 runtime.SetDefaultGOMAXPROCS()。它会按运行时默认规则重新设置，并忽略当时的 GOMAXPROCS 环境变量；这不是把值盲目设成 runtime.NumCPU()。

遇到值变化时按这张清单判断

排查时先记录 Go 版本、GOMAXPROCS 环境变量、GODEBUG，再分别记录 runtime.GOMAXPROCS(0) 和 runtime.NumCPU()。不要只看业务 goroutine 数，也不要因为数值变小就直接断定吞吐下降；CPU limit 是吞吐约束，实际效果还取决于任务是否计算密集、是否经常阻塞以及调度周期内的负载形状。

常见问题

Go 1.25 会按 CPU request 设置 GOMAXPROCS 吗？

不会。默认计算关注 Linux cgroup 的 CPU 吞吐限额，容器编排中的 CPU request 不等同于这个限额。

GOMAXPROCS 变小是不是程序出错？

不一定。若进程使用 Go 1.25 默认策略，容器 CPU limit 或 CPU 亲和性变化都可能使默认值变化。先核对环境约束和是否存在手动覆盖。

怎样恢复自动跟随容器限额？

移除固定的 GOMAXPROCS 设置，并确认没有关闭 containermaxprocs 或 updatemaxprocs；程序内有覆盖时，可按需要调用 runtime.SetDefaultGOMAXPROCS() 恢复默认规则。

官方资料：https://go.dev/doc/go1.25、https://pkg.go.dev/runtime、https://go.dev/blog/container-aware-gomaxprocs