一个用 Go 写的构建服务,调用外部打包命令后总是拿不到输出。日志里只有「命令执行完成」,stdout 是空的,退出码还是 0。开发把命令复制到终端里手跑,输出正常。后来把代码改成先读管道,输出立刻出来了。问题不在命令,而在顺序:代码先调用了 Wait,再去读 StdoutPipe,而 Wait 会把管道关掉。

Go 启动子进程的方式很朴素:os/exec 构造一个命令对象,Run 或 Start 执行,Wait 等它结束。它不经过 shell,不会自动展开通配符,也不会解释管道符号;在 Windows 上,很多习惯用的命令其实需要 cmd /c 才能跑。取消进程、处理信号、回收子进程,也各有各的平台差异。

这篇按「启动、收集输出、判断退出、取消、处理信号」的顺序讲。最后会给出本机 Windows 上的真实输出,包括一个很容易被忽略的现象:杀掉父进程,子进程仍然活着。

Wait 之后,管道已经关了

StdoutPipe 返回一个读取端,它连接到子进程的标准输出。标准库文档里写得很清楚:Wait 会在子进程退出后关闭这个管道。所以正确的顺序是「启动、读管道、等待」,而不是「启动、等待、读管道」。

cmd := exec.Command("cmd", "/c", "echo hello")
out, err := cmd.StdoutPipe()
fmt.Println("取管道错误:", err)
cmd.Start()
cmd.Wait()
b, err := io.ReadAll(out)
fmt.Println("Wait 之后读管道:", err)
fmt.Println("读到:", string(b))

本机 go1.27.3 的实际输出:

取管道错误: <nil>
Wait 之后读管道: read |0: file already closed
读到: 

管道读不出来,内容自然是空。更麻烦的是,如果子进程输出很多,而父进程在 Wait 之前不读,子进程可能因为管道缓冲区写满而阻塞,父进程又在等子进程退出,双方互相等待,形成死锁。这种死锁不会立刻出现,只在输出量超过缓冲区时发生,测试数据小的时候完全看不出来。

如果不需要在程序里处理输出,只是想让子进程直接继承终端的输出,可以把 cmd.Stdout 和 cmd.Stderr 设成 os.Stdout、os.Stderr。这样不涉及管道,也就不存在读取顺序问题;代价是父进程拿不到内容做解析或脱敏。很多 CLI 工具转发命令时用这种方式,日志直接进终端,行为最接近手敲。

只要用了 StdoutPipe 或 StderrPipe,就必须在 Wait 之前把管道读完。要么先起一个 goroutine 读,要么干脆用 CombinedOutput 让标准库替你收集。不要既拿管道又先 Wait。

启动:不经过 shell,参数要一个个给

exec.Command 的第一个参数是可执行文件,后面每个参数单独传。它不会把整串命令交给 shell 解析,所以 "ls -l" 会被当成一个文件名,而不是命令加参数。这个设计避免了大量注入问题:用户输入作为参数传进去,不会被解释成 ;、|、$() 之类的 shell 语法。

cmd := exec.Command("ping", "-n", "2", "127.0.0.1")
cmd.Dir = "C:\\work"
cmd.Env = append(os.Environ(), "APP_ENV=test")
cmd.Stdin = strings.NewReader("input\n")
err := cmd.Run()

Dir 设置工作目录,Env 设置环境变量,Stdin 提供输入。注意 Env 一旦设置就会替换掉继承的环境,不是追加;想保留原有变量,要像上面那样把 os.Environ() 拼进去。子进程找不到命令时,通常是 PATH 被清空或工作目录不对,不是命令不存在。

在 Windows 上,echo、dir、copy 这些是 shell 内置命令,不是独立的 exe。直接 exec.Command("echo") 会失败,必须写成 exec.Command("cmd", "/c", "echo", "hello")。反过来,如果为了省事把用户输入拼进 cmd /c 的字符串里,就等于把 shell 注入的风险又请了回来。参数该怎么分开传,仍然要分开传。

可执行文件的查找规则也因平台而异。Windows 会按 PATHEXT 尝试 .exe、.bat 等扩展名;Unix 要求文件有执行权限。部署时如果二进制没有 chmod +x,会得到 permission denied,而不是「找不到」。这些细节在开发机上通常被 IDE 或 shell 掩盖,到了容器里才暴露。

生产环境里更稳的做法是传绝对路径。PATH 可能被服务管理器裁剪、被容器镜像改掉、被不同的启动方式影响;绝对路径至少能保证「要么文件在,要么明确报错」。把工具路径做成配置项,启动时用 exec.LookPath 或 os.Stat 检查一次,比运行到一半才发现找不到要好。

Windows 的参数拼装还有一层容易踩的细节:最终传给系统的是一整条命令行字符串,含空格或引号的参数需要用双引号包住,参数内部的引号还要转义。大多数情况下 exec.Command 会替你处理好;但如果参数来自用户输入,又自己拼了一整串命令,转义规则就会变成噩梦。避免的办法只有一个:不拼字符串,保持「一个参数一个元素」。

收集输出:三种方式,各有代价

最简单的是一次性收集:cmd.CombinedOutput() 返回标准输出和标准错误的合并内容,cmd.Output() 只返回标准输出,标准错误会放进 ExitError.Stderr。它们内部会处理好读取和等待的顺序,不会死锁,适合输出量不大的命令。

代价是全部读进内存。一条 tar 或 ffmpeg 命令输出几百 MB 日志时,内存会被直接吃掉。这时要改用管道加流式处理:起一个 goroutine 持续读 StdoutPipe,主 goroutine 负责 Wait,读完再汇合。标准错误也要单独处理,否则它同样可能写满缓冲区。

out, _ := cmd.StdoutPipe()
errPipe, _ := cmd.StderrPipe()
if err := cmd.Start(); err != nil {
	return err
}
go func() { io.Copy(os.Stdout, out) }()
go func() { io.Copy(os.Stderr, errPipe) }()
return cmd.Wait()

这段代码的关键是「先 Start,再并发读,最后 Wait」。任何一步顺序反了,都可能死锁或丢数据。实际项目里还需要处理子进程被杀、管道提前关闭、读取 goroutine 还没结束就返回等情况,通常要配合 sync.WaitGroup 或 context。

用 Output() 时,标准错误会被收集到 ExitError.Stderr,但只有在命令失败时才能拿到;成功时 stderr 的内容会被丢弃。如果某个工具把重要警告写到 stderr 而退出码是 0,你就看不到它们。需要完整审计的命令,统一用 CombinedOutput,或者自己接管两个管道。

如果子进程需要交互,比如先读提示再输入密码,单靠管道会非常别扭:你得判断提示文本出现,再写输入,还要处理缓冲和回显。这种场景更适合用伪终端(pty),标准库没有内置,需要额外的包。绝大多数构建、转换、部署类命令都不需要交互,尽量不要把交互式命令放进自动化流程。

还有一种隐蔽的阻塞:子进程等待标准输入,而父进程没有设置 Stdin。默认情况下子进程继承父进程的输入,在服务里这可能是空的,也可能是某个一直不结束的管道。表现就是命令一直不返回。给不需要输入的命令显式设置 cmd.Stdin = nil,能给不必要的等待画上句号。

退出码:0 不一定是成功

cmd.Run() 返回 nil 表示进程退出码为 0;返回非 nil 时,类型通常是 *exec.ExitError,可以用 ExitCode() 拿到具体数字。本机实测:

cmd := exec.Command("cmd", "/c", "exit 3")
err := cmd.Run()
fmt.Println("err:", err)
var ee *exec.ExitError
if errors.As(err, &ee) {
	fmt.Println("退出码:", ee.ExitCode())
}
fmt.Println("exit 0 的 err:", exec.Command("cmd", "/c", "exit 0").Run())
err: exit status 3
退出码: 3
exit 0 的 err: <nil>

退出码为 0 只代表「进程认为自己成功了」,不代表业务真的成功。有些工具出错也返回 0,只在 stderr 里写警告;有些工具把「没有匹配项」当成正常结果返回 1,比如 grep。判断成功与否,要结合具体工具的约定,不能只信退出码。

在 Unix 上,进程被信号杀死时没有正常的退出码,ExitCode() 返回 -1,需要看 ProcessState 的信号信息。Windows 上没有这套信号语义,被终止的进程通常给出一个非零退出码。跨平台代码不要写「退出码 == 137 就是被 OOM 杀了」这种判断,那条规则只在特定平台和特定容器环境成立。

还有一个容易忽略的点:Run 内部会调用 Wait,所以一个 Command 只能 Run 一次,不能重复使用。需要重试时重新构造 exec.Command,不要复用同一个对象。

如果需要区分「命令不存在」和「命令执行失败」,可以用 errors.Is(err, exec.ErrNotFound)。这两类错误的处理方式不同:前者通常是部署环境缺工具,启动时就该失败;后者可能是输入数据的问题,可以重试或报给用户。把它们混成一句「执行失败」,会让排查多花很多时间。

取消:CommandContext 会杀进程,但只杀一个

exec.CommandContext 接收一个 context,context 取消时会调用 Process.Kill()。本机用一个 500 毫秒超时的 context 启动 ping -n 6,实际输出:

err: exit status 1
ctx.Err(): context deadline exceeded

注意错误不是「context canceled」,而是子进程被终止后的退出状态;context 的错误要单独从 ctx.Err() 取。在 Unix 上,被信号杀死的进程通常返回 signal: killed,这一条未在本机实测,因为当前环境是 Windows。判断超时不要依赖错误文本,先看 ctx.Err() 更可靠。

更关键的限制是:Kill 只杀直接子进程,不会自动杀它的后代。很多命令本身是个包装器,真正干活的是它启动的另一个进程。父进程被杀后,孙进程可能继续运行,占着端口、文件或 CPU。

Go 1.20 之后,exec.Cmd 增加了 Cancel 和 WaitDelay 两个字段。Cancel 可以自定义取消时执行的动作,默认是 Kill;WaitDelay 限制 Wait 在取消后等待多久,避免子进程忽略终止信号导致父进程一直挂着。这两个字段能缓解「取消后 Wait 不返回」,但仍然不解决进程树的问题。

本机实测:Go 程序启动 cmd /c ping -n 20,500 毫秒后调用 Process.Kill(),父进程被终止,但系统里仍然留下了 ping 进程。

父进程 pid: 12040
父进程已 Kill
程序退出
运行前后 ping 进程: before=[] after=[6844]
新增 ping pid: [6844]

这不是 Go 的 bug,而是 Windows 的进程模型:进程之间没有 Unix 那样的进程组和会话,终止一个进程不会级联。要在 Windows 上清理整棵树,常见做法是调用 taskkill /PID <pid> /T /F,或者用 Job Object 把子进程绑在一起(标准库不直接提供,需要调用系统 API)。在 Unix 上可以设置 SysProcAttr{Setpgid: true} 让子进程进入独立进程组,再用负的 PID 发给整个组,这一部分也未在本机实测。

不要假设「杀掉父进程就清理干净了」。部署脚本、构建工具、媒体转码这类会派生后代的命令,必须显式处理进程树,否则残留进程会在后台继续跑,下一次任务再启动一个,越积越多。

信号:Windows 只有一部分

Unix 用信号来通知进程「该退出了」「该重载配置了」,Go 用 os/signal 的 Notify 把信号转成 channel 消息。典型写法是监听 os.Interrupt 和 syscall.SIGTERM,收到后关闭资源、停止服务,再退出。

ch := make(chan os.Signal, 1)
signal.Notify(ch, os.Interrupt, syscall.SIGTERM)
defer signal.Stop(ch)
select {
case s := <-ch:
	fmt.Println("收到信号:", s)
case <-time.After(time.Second):
	fmt.Println("等待超时,正常退出")
}

本机实际输出:

已注册信号监听: os.Interrupt, SIGTERM
等待 1 秒后自行退出,不发送真实 Ctrl+C
等待超时,正常退出

这段只验证了注册和超时分支,没有真实投递 Ctrl+C,所以「Windows 上收到 Ctrl+C 后的行为」未在本机实测。可以确定的是平台差异:Windows 只真正支持 os.Interrupt(对应 Ctrl+C)和 os.Kill;os.Kill 不能被捕获,进程直接结束;Unix 才有的 SIGTERM、SIGHUP 在 Windows 上不会按 Unix 的语义送达。把只在 Unix 上验证过的信号逻辑直接搬到 Windows,通常会静默失效。

信号处理函数里不要做复杂工作。Notify 的 channel 缓冲通常只有 1,处理太慢会丢信号;在 channel 里做数据库写入、网络请求,也可能卡住退出流程。正确做法是收到信号后只做「通知」,把真正的清理放到主流程里,并给清理设置超时。

跨平台代码通常仍会把 syscall.SIGTERM 写进监听列表,因为这段代码主要部署在 Linux 上,Windows 只是开发环境。关键是不要在 Windows 上依赖它来触发退出:本机的 Ctrl+C 会产生 os.Interrupt,关闭控制台窗口则可能直接终止进程,清理逻辑来不及跑。Windows 服务通常改用 Service Control Manager 的停止事件,那是另一套 API,标准库没有直接封装。

信号和 context 经常一起用:信号触发 cancel(),HTTP 服务调用 Shutdown,后台任务检查 ctx.Done()。这套优雅退出的完整写法放在第 8 篇,这里先记住一点:信号只是触发器,真正的清理逻辑要能被超时打断,否则进程可能永远退不掉。

标准库还提供了 signal.NotifyContext,把「监听信号」直接变成一个 context:收到指定信号时 context 被取消,下游代码只要照常检查 ctx.Done() 就行,不用自己维护 channel。它适合和 http.Server.Shutdown、数据库连接关闭这类流程配合,代码比手动 select 更短,也更不容易漏掉 signal.Stop。

出问题时先看哪里

现象真实原因第一步查什么
命令执行成功,但读不到输出先 Wait 后读管道,管道已被关闭看 Wait 和 io.ReadAll 的先后顺序;改用 CombinedOutput
命令卡住不返回,CPU 很低管道缓冲区写满,父进程没读,双方互等确认读管道在 Wait 之前;大输出改用流式读取
exec: executable file not found命令是 shell 内置,或 PATH、工作目录不对Windows 加 cmd /c;打印 cmd.Path 和 cmd.Env
退出码非 0 但看不懂原因只看了 ExitCode,没看 stderr用 CombinedOutput 或单独收集 Stderr;打印完整输出
超时后子进程还在跑只杀了父进程,后代没有被清理Windows 用 taskkill /T 或 Job Object;Unix 用进程组
ctx 取消了但错误文本不是 canceled返回的是子进程退出状态,不是 context 错误先判断 ctx.Err(),再看 ExitError
Windows 上收不到 SIGTERM平台不支持该信号语义确认信号是否只在 Unix 有效;Windows 用 Ctrl+C 或控制台事件
进程退出后资源没释放没有 Wait,或清理逻辑只写在正常路径确保每条路径都 Wait;用 defer 或信号处理统一清理
参数里带空格或引号就失败把整串命令当成了一个参数检查是否每个参数单独传;不要自己拼命令行字符串

排查子进程问题,先确认三件事:进程到底有没有启动、有没有结束、输出走了哪个管道。把 cmd.Path、cmd.Args、退出码、stdout 和 stderr 一起打印出来,大多数问题当场就能定性。剩下的是平台差异,需要分别验证。

边界与代价

  • exec 不提供 shell 语义:通配符、管道、重定向、变量展开都没有。需要这些功能时显式调用 shell,但要承担注入风险。
  • 输出收集会占内存:CombinedOutput 适合小输出,大输出必须流式读取。选择哪种方式取决于最坏情况下的输出量,不是平均值。
  • 取消只覆盖直接子进程:跨平台清理进程树没有统一 API,Windows 和 Unix 的做法完全不同。需要严格隔离时,考虑容器或专门的进程管理组件。
  • 信号不是跨平台的:代码里写了 SIGTERM 不代表 Windows 会送到。部署到多个平台时,退出逻辑要以「能收到什么」为准,而不是「想收到什么」。
  • 子进程继承环境:环境变量、工作目录、文件描述符都可能影响子进程行为。设置 Env 时容易不小心清空 PATH,导致命令找不到。
  • 没有资源限制:标准库不设置 CPU、内存、文件大小限制。子进程失控时可能拖垮整台机器,需要靠外部工具或容器做隔离。

从系统角度看,进程的创建、退出、信号和回收是操作系统的基本能力。Go 只是把这些能力包了一层,平台差异仍然存在。想理解「僵尸进程」「进程组」「信号」这些概念,可以对照 操作系统:进程与线程 那一篇。

当天能自己验证的练习

  1. 用 StdoutPipe 启动 cmd /c echo hello,先 Wait 再读,确认得到「file already closed」;改成先读后 Wait,确认能读到内容。
  2. 启动一个退出码为 3 的进程,用 errors.As 取出 *exec.ExitError,打印 ExitCode();再跑一个退出码 0 的,确认返回 nil。
  3. 用 CommandContext 给 ping -n 6 设 500 毫秒超时,打印 err 和 ctx.Err(),确认两者不是同一个信息。
  4. 启动 cmd /c ping -n 20,500 毫秒后 Kill 父进程,再用任务管理器或 Get-Process ping 检查是否还有残留,最后手动清理。
  5. 注册 signal.Notify 监听 os.Interrupt,用一个 1 秒超时的 select 等待;在真实终端里按 Ctrl+C,确认收到信号,退出后不要留下后台进程。

小结

三句话收一下:用了管道就必须先读再 Wait,或者直接用 CombinedOutput,别让子进程和父进程互相等;exec 不经过 shell,参数要一个个传,Windows 的 shell 内置命令要显式走 cmd /c;取消和信号都有平台边界,Kill 只杀直接子进程,Windows 上尤其要处理进程树残留。

下一篇进入并发。今天你用 goroutine 读管道、用 channel 收信号,但还没有系统地讲清楚:两个 goroutine 同时改一个变量会发生什么、锁应该加在哪里、sync.Map 和普通 map 加锁怎么选、竞态检测器报出的那段栈到底在说什么。这些是 Go 服务里最难复现、也最容易造成数据错乱的一类问题。