runtime / runtime/debug — 运行时调参与自诊断

runtime 和 runtime/debug 是 Go 程序"自我管理"的入口：GC 触发节奏（GOGC）、内存软上限（GOMEMLIMIT）、调度并行度（GOMAXPROCS）、资源兜底释放（Finalizer/Cleanup）、运行时观测（metrics）。这些参数在容器化部署里几乎天天碰，但语义极容易被误读——比如把 GOGC 当成"内存占用比例"、把 GOMEMLIMIT 类比 JVM 的 -Xmx。本文逐条给出官方文档/notes 原文和实测依据。

基线：go1.27.0 windows/amd64（GOROOT G:\Need\Go\golang）。文中"实测"均在本机验证；“原文"均为 release notes、包文档或 GOROOT 源码逐字摘录。

1. GOGC：堆增长百分比，不是占用比例

runtime 包文档原文（src/runtime/extern.go）：

“The GOGC variable sets the initial garbage collection target percentage. A collection is triggered when the ratio of freshly allocated data to live data remaining after the previous collection reaches this percentage. The default is GOGC=100. Setting GOGC=off disables the garbage collector entirely.”

翻译成可计算的语言：下一轮 GC 的触发点 = 上轮结束时的存活堆 × (1 + GOGC/100)。GOGC=100 表示"允许新分配的数据量达到存活数据的 100%"——即堆翻倍时回收。举例：某轮 GC 后存活 1 GB，则 GOGC=100 在堆涨到约 2 GB 时触发下一轮；GOGC=50 约 1.5 GB；GOGC=200 约 3 GB。所以：

• GOGC 越大：GC 越少、CPU 越省，但峰值内存越高（触发点被推远）。
• GOGC 越小：GC 更频繁、内存更省，但抢占应用的 CPU 更多。
• 它是"增长余量"而不是"占用比例”——说 GOGC=80 是"机器内存用到 80% 才 GC"是彻底误读，触发点跟着存活堆走，与机器物理内存无关。

GOGC=off 的文档语义就是字面意思：完全禁用 GC。堆只涨不收，适合基准测试或"想看清未回收状态"的调试，生产长跑禁用。运行时修改用 debug.SetGCPercent，其包文档补充了一个重要细节——负值禁用并不绝对：“A negative percentage effectively disables garbage collection, unless the memory limit is reached."（GOMEMLIMIT 会把 GC 重新拉起来，见第 2 节）。返回值是旧设置；初始值取启动时的 GOGC 环境变量，未设置则为 100。

package main

import (
	"fmt"
	"runtime/debug"
)

func main() {
	old := debug.SetGCPercent(80) // 返回旧值
	fmt.Println("previous GOGC:", old)
	defer debug.SetGCPercent(old)
	// ... 业务代码 ...
}

实测：默认环境下 runtime/metrics 的 /gc/gogc:percent 读数 100，与文档一致。

为什么这样设计

把触发点锚定在"存活堆的函数"上，意味着无论应用稳态占用多少内存，GC 的摊销成本大致恒定（每翻倍活一次）；如果按"物理内存占用比例"设计，大堆小堆程序的 GC 频率会完全不可预测。详细机制见官方 GC 指南 go.dev/doc/gc-guide。

2. GOMEMLIMIT：软上限，OOM 前的最后防线

runtime 包文档原文（extern.go）：

“The GOMEMLIMIT variable sets a soft memory limit for the runtime. This memory limit includes the Go heap and all other memory managed by the runtime, and excludes external memory sources such as mappings of the binary itself, memory managed in other languages, and memory held by the operating system on behalf of the Go program.”

debug.SetMemoryLimit 包文档补充了机制：“The runtime undertakes several processes to try to respect this memory limit, including adjustments to the frequency of garbage collections and returning memory to the underlying system more aggressively. This limit will be respected even if GOGC=off (or, if SetGCPercent(-1) is executed).” 也就是说 GOMEMLIMIT 与 GOGC 是分层协作：平时 GOGC 定节奏，堆逼近上限时 runtime 自动加密 GC、加快向 OS 归还内存；极端情况下设一个比运行时自身占用还低的 limit，GC 会近乎连续地跑，但应用仍可推进（包文档：“may cause the garbage collector to run nearly continuously. However, the application may still make progress."）。

它度量的是什么，包文档给了精确公式：

“the following expression accurately reflects the value the runtime attempts to maintain as the limit: runtime.MemStats.Sys - runtime.MemStats.HeapReleased，or in terms of the runtime/metrics package: /memory/classes/total:bytes - /memory/classes/heap/released:bytes”

格式与默认值：GOMEMLIMIT 是字节数加可选后缀（B/KiB/MiB/GiB/TiB，按 2 的幂）；默认 math.MaxInt64，等价于关闭（“math.MaxInt64 is the canonical value for disabling the limit”）。实测 debug.SetMemoryLimit(-1) 只读取当前值不修改，返回 9223372036854775807。

为什么不能类比 JVM 的 -Xmx

三个本质差别，都源自上面的文档措辞：

1. 管辖范围不同。-Xmx 约束 JVM 托管堆的全部；GOMEMLIMIT 只管"runtime 管辖且未归还"的内存，goroutine 栈之外它不计进程 RSS 全貌，二进制映射、cgo/syscall.Mmap 分配、OS 代持内存都被明确排除。容器按 RSS 被 OOMKill，而 RSS 可能大于 limit 度量值，也可能因未归还的 span 大于存活堆——两个数对不上是正常现象，别拿 limit 当 RSS 上限。
2. 软硬不同。-Xmx 超了抛 OutOfMemoryError；GOMEMLIMIT 只让 runtime “try to respect”——更勤快地 GC 和归还，不禁止分配、不抛错。它是"OOM 前最后手段”：让濒死进程靠压榨 GC 多活一会儿、给摘流量争取时间，而不是保险箱。
3. 和 GC 节奏的耦合方式不同。-Xmx 之下堆怎么用是你的；GOMEMLIMIT 一旦接近，会覆盖 GOGC 语义强行提频（“This setting may be effectively reduced in order to maintain a memory limit”——SetGCPercent 文档语）。

容器场景的推荐姿势：GOMEMLIMIT 设成容器 limit 的八成多、留出非 Go 内存与未归还 span 的余量（K8s 场景可配 Downward API 或环境变量注入），配合 Go 1.25+ 的自动 GOMAXPROCS（第 3 节）就是标准组合：

GOGC=off 或 100 都可以——GOMEMLIMIT 兜底照常生效
GOMEMLIMIT=870MiB   # 容器 limit 1GiB 时

3. GOMAXPROCS 与 cgroup：Go 1.25 起 Linux 自动感知 CPU limit

Go 1.25 release notes（Container-aware GOMAXPROCS 一节，原文摘录）：

“On Linux, the runtime considers the CPU bandwidth limit of the cgroup containing the process, if any. If the CPU bandwidth limit is lower than the number of logical CPUs available, GOMAXPROCS will default to the lower limit. In container runtime systems like Kubernetes, cgroup CPU bandwidth limits generally correspond to the ‘CPU limit’ option. The Go runtime does not consider the ‘CPU requests’ option.”

“On all OSes, the runtime periodically updates GOMAXPROCS if the number of logical CPUs available or the cgroup CPU bandwidth limit change.”

“Both of these behaviors are automatically disabled if GOMAXPROCS is set manually via the GOMAXPROCS environment variable or a call to runtime.GOMAXPROCS. They can also be disabled explicitly with the GODEBUG settings containermaxprocs=0 and updatemaxprocs=0, respectively.”

包文档还给出实现细节：cgroup 配额按 quota/period 的平均 CPU 吞吐折算（v2 读 cpu.max，v1 读 cpu.cfs_quota_us/cpu.cfs_period_us）；默认值取逻辑 CPU 数、CPU 亲和度、cgroup 吞吐三者最小值，除 CPU/亲和本身不足 2 外不低于 2；非整数向上取整；自动更新频率最高约每秒一次。GOMAXPROCS 被手动设定会停掉自动更新，可用 runtime.SetDefaultGOMAXPROCS() 恢复默认行为并强制立即重算。

纠错 不少旧资料写回退开关是 GODEBUG=cpu.limit=0——不存在这个键。实测 GOROOT 的 doc/godebug.md 与 src/runtime 均无 cpu.limit；正确键名是 containermaxprocs（关 cgroup 感知）与 updatemaxprocs（关周期更新），godebug.md 与 1.25 notes、go doc runtime.GOMAXPROCS 三方一致。二者对 go.mod 声明 1.24 及以下的模块默认按关闭处理（包文档：“is default for language version 1.24 and below”）。

平台标注（Windows/macOS 部署必读）：cgroup 感知仅限 Linux（包文档的默认值来源列表里 cgroup 一项明确限定 “on Linux”）。Windows 没有 cgroup 机制，GOMAXPROCS 默认仍等于逻辑 CPU 数（受亲和度影响），容器/任务管理器式的 CPU 配额不会被感知——Windows 容器部署需手动设 GOMAXPROCS。“CPU 数变化后周期性更新"这一半在所有 OS 都生效（notes 原文 “On all OSes”）。

底层原理

GOMAXPROCS 决定 P 的数量，而 P 数牵动调度吞吐、GC 标记 worker 数量与辅助标记配额。1.25 之前按宿主机核数（往往几十核）设 P、而容器只分到 0.5 核的场景，会让大量 P 抢时间片被 CFS 节流，表现为 GC 停顿和尾延迟异常放大。自动感知后这些成本被折算进"限额内该有几个 P”，无需再引入 uber/automaxprocs 之类的第三方 hack。

package main

import (
	"fmt"
	"runtime"
)

func main() {
	fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0), // 传 0 只读不改
		"NumCPU:", runtime.NumCPU())
	runtime.SetDefaultGOMAXPROCS() // 放弃手动值,回到运行时默认(含 cgroup 感知)
}

4. Green Tea GC：Go 1.26 起的默认垃圾回收器

Go 1.26 release notes 原文：

“The Green Tea garbage collector, previously available as an experiment in Go 1.25, is now enabled by default after incorporating feedback. This garbage collector’s design improves the performance of marking and scanning small objects through better locality and CPU scalability. Benchmark results vary, but we expect somewhere between a 10–40% reduction in garbage collection overhead in real-world programs that heavily use the garbage collector. Further improvements, on the order of 10% in garbage collection overhead, are expected when running on newer amd64-based CPU platforms (Intel Ice Lake or AMD Zen 4 and newer), as the garbage collector now leverages vector instructions for scanning small objects when possible.”

notes 的表述边界值得照抄不误：收益的主语是 GC 开销（对小对象标记/扫描的性能改进），而非"应用延迟"或"内存占用”——引用时不要超出这个措辞。实验路径：Go 1.25 以 GOEXPERIMENT=greenteagc 构建期启用；1.26 默认开启，可用 GOEXPERIMENT=nogreenteagc 关闭，1.26 notes 称该 opt-out “expected to be removed in Go 1.27”。实测 go1.27 的 GOROOT 中 src/internal/goexperiment/exp_greenteagc_on.go、exp_greenteagc_off.go 与 src/runtime/mgcmark_nogreenteagc.go 仍存在，说明 1.27 尚未兑现移除预告。

对使用者而言它不需要任何配置；只有两种情况会碰到这些开关：对照测试新旧 GC 的性能回归，或怀疑 GC 行为异常时按 notes 建议带 nogreenteagc 复现后提 issue。

5. Go 1.27 的运行时变化

小对象分配提速。1.27 notes “Faster memory allocation” 一节原文：

“The compiler now generates calls to size-specialized memory allocation routines, reducing the cost of some small (<80 byte) memory allocations by up to 30%. Improvements vary depending on the workload…”

配套代价与开关（同为 notes 原文）：“the binary size to increase by about 60 KB”，可 GOEXPERIMENT=nosizespecializedmalloc 关闭，且该 opt-out “expected to be removed in Go 1.28”。

asynctimerchan 移除。1.27 notes 原文：“The asynctimerchan GODEBUG setting (added in Go 1.23) has been removed permanently. Channels created by package time are now always unbuffered (synchronous), irrespective of GODEBUG settings.” 实测 doc/godebug.md 标注 “Go 1.27 removed the asynctimerchan setting”，且 GOROOT src/runtime 已 grep 不到该符号——若你的代码或运维手册还靠 GODEBUG=asynctimerchan=1 走 1.23 前的定时器 channel 行为，升级即失效，定时器语义参考 ../01-基础核心包/time.md。

traceback 带 goroutine 标签（与 pprof 标签联动）：

“Tracebacks for modules with go directives configuring Go 1.27 or later will now include runtime/pprof goroutine labels in the header line. This behavior can be disabled with tracebacklabels=0 GODEBUG setting (added in Go 1.26).”

GOMEMLIMIT：无变化。实测 grep go.dev/doc/go1.27 全文，GOMEMLIMIT 一次都未出现——1.27 没有对内存软上限的行为变更。

6. SetFinalizer 的三个陷阱与现代替代 AddCleanup

先看一个实测可运行的最小例子（go1.27.0 实测输出贴在代码后）：

package main

import (
	"fmt"
	"runtime"
	"time"
)

type dbConn struct{ id int }

var held *dbConn

func main() {
	c := &dbConn{id: 42}
	runtime.SetFinalizer(c, func(x *dbConn) { fmt.Println("finalizer ran, id=", x.id) })
	cl := &dbConn{id: 7}
	runtime.AddCleanup(cl, func(id int) { fmt.Println("cleanup ran, id=", id) }, cl.id)

	held = c // c 被全局变量引用,GC 不会认为它不可达
	runtime.GC()
	time.Sleep(50 * time.Millisecond)
	fmt.Println("after GC #1")

	cl = nil
	held = nil // 两者都不可达了
	runtime.GC()
	time.Sleep(50 * time.Millisecond)
	fmt.Println("after GC #2")
}

实测输出：

after GC #1
finalizer ran, id= 42
after GC #2

注意 cleanup ran, id= 7 始终没打出来——程序退出时排干队列，这就是本节所有陷阱的根源：“Some time after ptr is no longer reachable”（延迟任意）与 “not guaranteed to run before program exit”（退出前不保证）。finalizer 则"迟到"到第二次 GC 的睡眠期才输出；after GC #1 打印时 c 还被全局变量 held 引用着，它压根没到入队资格。

陷阱一：对象形状与签名约束

包文档：“The argument obj must be a pointer to an object allocated by calling new, by taking the address of a composite literal, or by taking the address of a local variable. The argument finalizer must be a function that takes a single argument to which obj’s type can be assigned, and can have arbitrary ignored return values. If either of these is not true, SetFinalizer may abort the program.” 即：不能是值类型、不能是非堆指针，签名错了程序可能直接中止。另有两类"不保证运行"：*obj 为 0 字节时（可能与其它零字节对象共享地址，见语言规范的大小与对齐保证）；包级变量初始化器里分配的对象（“may be linker-allocated, not heap-allocated”）。实测：对一个零字节结构体 runtime.AddCleanup(&empty{}, ...) 注册的回调直到程序退出都未见运行——与"不保证"的措辞一致。

陷阱二：入队时机是"不可达"，且对象会"复活"

包文档：“The finalizer is scheduled to run at some arbitrary time after the program can no longer reach the object.” 不可达由 GC 可达性分析决定，而不是作用域结束——最隐蔽的一点：“A function argument or receiver may become unreachable at the last point where the function mentions it.” 函数还没执行完，只要后面不再提到这个参数，它就已不可达，finalizer 可能在此刻跑掉（典型事故：文件描述符被提前 close，还在进行中的 syscall.Write 写向了另一个 fd）。防御手段是 runtime.KeepAlive(p)：包文档语义为 “marks its argument as currently reachable”，把可达性钉到调用点。

其次是复活语义：GC 发现不可达且带 finalizer 的块时，“runs finalizer(obj)… This makes obj reachable again, but now without an associated finalizer”——finalizer 执行期间对象是活的（甚至可以被重新引用），要等下一轮 GC 确认仍不可达才真正释放；如果在 finalizer 里把 obj 存回全局变量，它就永久"续命"了。另外 finalizer 的执行顺序虽按依赖排序，但整个程序只有一个 goroutine 串行跑所有 finalizer：“If a finalizer must run for a long time, it should do so by starting a new goroutine”——一个慢 finalizer 会拖垮全部。

陷阱三：不保证执行，别当生命周期钩子

包文档：“There is no guarantee that finalizers will run before a program exits”——os.Exit、正常 return、进程被杀都不等待它们。文档自带的反例：bufio.Writer 指望 finalizer 刷盘是错的，因为退出时不会刷。含 finalizer 的循环引用结构 “is not guaranteed to be garbage collected and the finalizer is not guaranteed to run”。正确定位：finalizer 只是"忘了 Close 时兜底关 fd"这类尽力而为的清理，显式 Close 永远是第一选择。

AddCleanup：Go 1.24+ 的推荐替代

SetFinalizer 包文档一锤定音：“New Go code should consider using AddCleanup instead, which is much less error-prone than SetFinalizer.” 签名（go doc runtime.AddCleanup 实测，泛型）：

func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup

与 finalizer 的关键差异（逐条出自包文档）：清理函数拿到的是直接传入的 arg（如裸 fd 数字），不用回头解引用对象本身；同一指针可以挂多个 cleanup，“much less error-prone” 的核心原因；arg == ptr 时直接 panic（防自引用导致的永不回收——“If ptr is reachable from cleanup or arg, ptr will never be collected”）；cleanups 并发执行（“unlike finalizers”），彼此无顺序，含循环引用也能各自触发；慢清理同样应自起 goroutine。不变的是"退出前不保证运行"、零字节对象与 linker 分配对象同样不保证，以及 tiny 对象批量优化可能让个别回调不跑（对象 ≤16 字节且无指针时）。

KeepAlive 的边界

runtime.KeepAlive(x) 只保证 x 在调用点之前可达，包文档强调它只应用于防 finalizer/cleanup 过早（“KeepAlive should only be used to prevent finalizers from running prematurely”）。另注意 SetFinalizer 文档的内存模型提醒：SetFinalizer(x, f) 对 f(x) 是 synchronizes-before，但 KeepAlive(x) 不保证与 f(x) 构成同步——finalizer 若读写对象的可变字段，仍需自己加锁。

7. 运行时观测：NumGoroutine、runtime/metrics 与 ReadMemStats 的代价

goroutine 数量：runtime.NumGoroutine() 文档措辞 “returns the number of goroutines that currently exist”——包含正常等待中的 goroutine，单看它判断泄漏会误报；把它做成 gauge 监控基线偏移量，再配合 goroutineleak profile（见 ./pprof.md 第 3 节）定位真泄漏。

runtime/metrics 入门：以字符串描述符暴露运行时指标，接口稳定（“This package provides a stable interface to access implementation-defined metrics exported by the Go runtime”）。用法三步：All() 拿全部 Description；构造 []Sample；Read(samples) 取值。包文档承诺浮点值永不为 NaN/Inf。实测打印若干描述符（go1.27.0，程序刚起、goroutine 50 个已返回）：

samples := []metrics.Sample{
	{Name: "/gc/heap/live:bytes"},
	{Name: "/gc/heap/allocs:bytes"},
	{Name: "/gc/gogc:percent"},
	{Name: "/gc/gomemlimit:bytes"},
	{Name: "/sched/goroutines:goroutines"},
	{Name: "/memory/classes/heap/objects:bytes"},
}
metrics.Read(samples)
// 对每个 s:按 s.Value.Kind() 分支,KindUint64 取 Uint64(),KindFloat64 取 Float64()

/gc/heap/live:bytes                uint64=0
/gc/heap/allocs:bytes              uint64=211328
/gc/gogc:percent                   uint64=100
/gc/gomemlimit:bytes               uint64=9223372036854775807
/sched/goroutines:goroutines       uint64=7
/memory/classes/heap/objects:bytes uint64=211328

各描述符的包文档语义：/gc/heap/live:bytes——“Heap memory occupied by live objects that were marked by the previous GC"（注意示例里为 0：还没跑过 GC 时该估计为空，别当成"没有存活对象”）；/sched/goroutines:goroutines——“Count of live goroutines”；/memory/classes/heap/objects:bytes——“Memory occupied by live objects and dead objects that have not yet been marked free by the garbage collector”（解释了 RSS 与存活堆的差）。/gc/pauses:seconds 已标注 Deprecated——“Prefer the identical /sched/pauses/total/gc:seconds"。除标量外还有一类分布型值（如延迟直方图），Kind 不是 Uint64/Float64，需按序列迭代读取。

ReadMemStats 的代价：包文档说它取回的统计是实时的（与 heap profile 的"上次 GC 快照"相对，原文 “This is in contrast with a heap profile, which is a snapshot as of the most recently completed garbage collection cycle”），但代价是停顿整个程序——实测 src/runtime/mstats.go 的 ReadMemStats 实现第一步即调用 stopTheWorld。监控循环里秒级轮询它会直接抬高 P99，改用 runtime/metrics（不 STW）。

8. runtime/debug 工具箱

注意 FreeOSMemory 的真实语义按包文档是"attempt to return as much memory as possible”——尽力而为，不是"立即降 RSS"的开关；后台任务本来就在逐步归还，手动调用只是加速这一次回收并付出 STW 与清理 CPU 的成本。

其余入口——PrintStack/Stack（panic 之外自行取栈）、SetTraceback（控制 panic traceback 详细程度）、SetPanicOnFault、ReadGCStats、WriteHeapDump、SetCrashOutput——从名字即可定位，具体取值语义以 go doc runtime/debug.<函数名> 为准。

9. 指针：执行 trace 与 GOEXPERIMENT

执行 trace 的采集端点、常规 trace.Start 与 FlightRecorder 的取舍、go tool trace 分析，全部在 ./pprof.md 第 4、6 节。GOEXPERIMENT 是构建期实验开关的通用机制（本文提到 greenteagc、nosizespecializedmalloc，pprof 文档提到 goroutineleakprofile），各版本增删频繁，以当年 release notes 为准，不要长期依赖某个实验开关。

10. 陷阱汇总

实战建议

• 容器化 Go 服务的标准三件套（Go 1.25+，Linux）：GOMEMLIMIT 设为容器 limit 的九成左右留出非 Go 内存余量，GOMAXPROCS 不手动设（让运行时感知 cgroup 并自动更新），GOGC 保持默认 100 除非有实测依据。
• 观测走 runtime/metrics（描述符清单用 All() 拿，别硬编码全集），ReadMemStats 只在诊断时刻偶尔按一下；goroutine 水位用 NumGoroutine + 泄漏剖析双保险。
• 新代码的资源兜底一律 runtime.AddCleanup，别再写 SetFinalizer；两者都只是最后防线，Close 必须显式。
• 升级 Go 大版本时读 release notes 的 Runtime 与 GODEBUG 两节：1.27 的 asynctimerchan 永久移除、traceback 默认带 goroutine 标签、小对象分配提速约 30% 都属"不读就会踩"的行为变更。
• 性能剖析、trace 与 FlightRecorder 的实操在 ./pprof.md；GC 调优的系统论述见官方 go.dev/doc/gc-guide。