Go signal.Notify 没收到 SIGTERM 时要检查哪些边界

Go 程序用 signal.Notify 接收不到 SIGTERM，通常不是“系统信号失效”，而是三个边界没有对齐：通知 channel 没有持续读取或缓冲太小，注册代码所在的进程已经退出，或者 systemd、容器编排器实际把信号发给了另一个 PID。先把接收模板写对，再沿着 channel、进程和托管入口逐层排查，定位会快很多。

signal.Notify 不会替你保存信号，也不会阻塞等待接收方。给单个信号使用容量为 1 的 channel，并让主流程在 channel 或 context 上等待；如果仍然没有 SIGTERM，再检查发送信号的 PID 是否就是 Go 进程。

先把 signal.Notify 注册在仍然存活的主流程里

最小可靠写法是：创建带缓冲的 channel，明确注册 syscall.SIGTERM，然后让主流程等待它。不要在一个很快返回的初始化函数里注册后就结束，也不要只启动接收 goroutine 却让 main 立即返回。

package main

import (
	"fmt"
	"os"
	"os/signal"
	"syscall"
)

func main() {
	sigCh := make(chan os.Signal, 1) // 单个 SIGTERM 用 1 个缓冲位即可
	signal.Notify(sigCh, syscall.SIGTERM) // 只注册本次要处理的信号
	defer signal.Stop(sigCh) // 退出前解除这条 channel 的通知注册

	// 这里保持主流程存活，避免 main 在信号到达前直接返回
	sig := 

这个模板只表达“收到信号后再继续”的生命周期，不代表一定要把清理逻辑全部写在 main。实际服务可以在收到信号后调用关闭函数、等待 worker 收尾，再返回。关键是注册完成后，至少有一条仍存活的路径在读取 sigCh。

channel 缓冲不足时，Notify 不会替你排队等待

os/signal 文档明确说明，通知发送不会阻塞调用方，因此接收 channel 必须有足够的缓冲空间。单个信号只关心“来过一次”时，容量 1 通常足够；如果同一 channel 注册了多个信号，或业务在收到第一个信号后还要观察更多信号，就要重新估算容量和读取速度。

排查时不要只看 signal.Notify 是否被调用，还要看下面四个事实：

如果程序只需要把终止信号转换成取消语义，也可以用 signal.NotifyContext。它适合把取消传给多个下游任务，但必须保存并调用返回的 stop 函数，否则信号注册会持续到父 context 结束。

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM) // 把 SIGTERM 转成取消信号
defer stop() // 任务收尾后恢复信号行为并释放注册关系

go runWorkers(ctx) // 下游任务统一观察 ctx.Done()

托管程序发信号的 PID 可能不是 Go 程序

代码无误时，最容易漏掉的是进程对象。手工执行 kill -TERM 时，PID 必须对应 Go 进程；在容器中，编排器通常只对容器的主进程发送信号；如果入口脚本再启动子进程，信号是否继续传递就取决于入口进程和进程组的组织方式。systemd 场景同样要确认服务单元管理的主 PID，而不是凭日志里的业务 PID 猜测。

可以把“谁发送、发给谁、谁负责接收”写成一张表再复查：

还要区分信号类型。SIGTERM 给程序一个清理机会，SIGKILL 则不能被程序捕获、阻塞或忽略；如果托管器先发送终止信号，等待超时后再强制杀死，清理代码可能只执行了一部分，这不是 Notify 丢信号。

用一张生命周期清单收敛最后的边界

当现象仍然存在时，按下面顺序复查，通常比不断改 channel 容量更有效：

1. 确认 signal.Notify 的信号参数确实包含 syscall.SIGTERM，且平台支持该信号。
2. 确认 channel 在注册前后都没有被关闭，主流程或接收循环仍在运行。
3. 确认发送命令使用的是当前 Go 进程 PID；容器和服务托管场景优先检查主进程关系。
4. 确认没有过早调用 signal.Stop，也没有在收到信号前让 main 返回。
5. 确认实际发送的是 SIGTERM 而不是无法捕获的 SIGKILL，并为清理逻辑预留足够时间。

如果要给多个组件传递退出原因，优先统一使用一个根 context；如果只是单点退出通知，容量为 1 的 channel 更直观。选择哪种方式，取决于你要传递的是“一次信号事件”，还是“整个任务树都应取消”的生命周期语义。

相关问题

signal.Notify 为什么推荐 buffered channel？

因为通知发送不会阻塞，容量为 1 可以让单个退出信号在接收方短暂忙碌时有位置保存。

调用 signal.Stop 后还能收到 SIGTERM 吗？

该 channel 不再接收由 Notify 注册的信号；需要继续接收时应保留注册，或重新用明确的 channel 注册。

NotifyContext 和 signal.Notify 怎么选？

只有一个接收点时 channel 更直接；需要让多个 worker 共享取消状态时，NotifyContext 更适合沿 context 树传播。

为什么 SIGKILL 没有进入接收分支？

SIGKILL 由系统直接终止进程，应用没有机会执行 signal.Notify 的处理逻辑。

官方 os/signal 包文档给出了 Notify、Stop 和 NotifyContext 的职责边界。遇到 SIGTERM 没有到达时，先查 channel 与生命周期，再核对托管 PID，通常就能把“代码问题”和“进程对象问题”分开。