Go os/exec 包实战：如何安全地执行外部命令并处理超时与输出流

写基础设施工具的时候，我经常需要在 Go 程序里调用外部命令。比如用 ffmpeg 截帧、调 mysqldump 做备份、让 git 去拉取指定分支。这些需求看起来简单，真正放上生产环境之后，问题却往往出在不起眼的地方：命令启动后没有结束，程序像被卡住一样；或者日志文件被输出撑爆，服务内存一路走高。如果你也遇到过类似的场面，多半不是命令本身的问题，而是 os/exec 的使用方式踩到了边。

这篇文章想把这个包里最容易被忽略的两块说清楚：输出流处理和超时清理。前者决定命令会不会出人意料地阻塞，后者决定超时之后是否能干净收场。

很多阻塞问题，根源在输出流

执行外部命令时，Cmd 结构体里的 Stdout、Stderr 并不是默认收集到缓冲区供你随时读取的。可以理解成它只是往一个管道口写入数据。如果程序没有及时从另一端读取，管道满了之后，子进程的写入操作就会阻塞。即便外部命令本身很快，整个程序也会在 Wait 那里一直挂着。

一个实际场景：某个任务调度服务会调用一段 shell 脚本做数据迁移，启动脚本很快，之后脚本还会继续打印一堆进度日志。服务端只调用了 cmd.Run()，没有设置 Stdout 和 Stderr。本地测试时输出量小，看不出异常；部署到生产环境后，脚本一旦输出超过管道缓冲大小，整个任务就卡住，日志停留在最后一条进度，看起来像是数据库锁住了。

处理方式很简单：在启动命令前，给 cmd 配好输出目标。可以用 bytes.Buffer，也可以用 os.File，甚至可以自定义 Writer。很多人习惯这样写：

var stdout, stderr bytes.Buffer
cmd := exec.Command("git", "status")
cmd.Stdout = &stdout
cmd.Stderr = &stderr
if err := cmd.Run(); err != nil {
    log.Printf("run failed: %v", err)
}

这里有个容易忽略的细节：如果只设置了 Stdout 而忘了 Stderr，stderr 依然会变成一个无人读取的管道。命令一旦向 stderr 输出大量数据，同样会阻塞。所以要么两个都设置，要么直接用 CombinedOutput。不过 CombinedOutput 等于把两者混合到一个 buffer，对于需要分别记录的地方就不够灵活了。

在什么情况下可以不管这些，直接调 Output() 呢？如果命令输出量很小，比如查询版本号、执行 git rev-parse，Output 就很合适。它内部自己会创建管道并读完，使用非常方便。但如果命令可能输出几十 MB 甚至更多，Output 会把所有内容读进内存，服务就会面临内存压力。

我把输出处理的几个常用方式放在一起对比一下：

选哪种，取决于外部命令的输出特征。如果拿不准，优先选择把 stdout 和 stderr 都接到同一个文件或自定义 writer，至少能保证命令不因为缓冲区被堵死。需要一边执行一边看输出时，再考虑用 StdoutPipe 拉起一个 goroutine 持续读取。

如果外部命令输出量大，但你又不需要日志内容，可以直接把 stdout 和 stderr 都设为 io.Discard。Go 内部会启动复制 goroutine，把输出全部写入 Discard，由于 Discard 的写操作几乎不会阻塞，命令不会因为管道问题卡住。它对内存很友好，代价是放弃了全部输出。

用 Context 做完超时，为什么进程还是没杀掉

处理超时，很多人第一反应是 exec.CommandContext。这个 API 确实好用，逻辑很简单：创建一个可取消的 context，取消时 Go 会直接杀掉启动的子进程。比如：

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

cmd := exec.CommandContext(ctx, "bash", "-c", "./build.sh")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
    log.Printf("command failed: %v", err)
}

看起来没问题，但实际出问题的情况是：外部命令往往不是简单的单进程程序。bash build.sh 可能内部会启动 node、python 或者其他子进程。CommandContext 超时后检测到 ctx.Done，调用的只是 Process.Kill()，它会杀掉 bash 本身，但 bash 启动的子进程并不会自动跟着消失，而是被系统接收为孤儿进程继续运行。

这个现象在 CI 机器上尤其明显。CI 里经常会看到构建超时返回失败，但 docker build 或者一些辅助进程仍留在机器上，占用着 CPU 和端口。下次构建再用同一个端口时，就报地址被占用。排查半天，问题并不在构建脚本，是超时清理没做干净。

要避免这种情况，思路从“杀进程”切到“杀进程组”。在 Unix 系统上，我们可以让外部命令成为新进程组组长，然后对整个进程组发送信号。这样无论它内部起了多少子进程，只要不主动脱离进程组，都会被一起终止。

改一下前面的例子：

cmd := exec.Command("bash", "-c", "./build.sh")
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr

if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

done := make(chan error, 1)
go func() { done <- cmd.Wait() }()

select {
case err := <-done:
    // 命令自然结束
    if err != nil {
        log.Printf("command finished with error: %v", err)
    }
case <-ctx.Done():
    syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
    <-done // 等待 Wait 返回，回收进程
    return ctx.Err()
}

这里的关键是 Setpgid: true。它让 bash 作为新进程组组长运行，然后我们向 -cmd.Process.Pid 发送信号，就能把整个进程组里的进程都覆盖到。注意这个做法在 Windows 上没有对应效果，Windows 需要借助作业对象（Job Object），那是另一个话题。

一个容易踩的坑是：即使使用了 CommandContext，并且 ctx 超时后 Run 返回错误，进程已经在内核中被 kill，但如果你用的是 Start 和自定义 Wait 的组合，必须确保每次 Start 后都有对应的 Wait 调用。否则 Go 内部虽然杀掉了进程，进程描述符没有被回收，还是会留下僵尸进程。所以上面的代码里，case <-ctx.Done() 分支在 Kill 之后又等待了 done，就是为了保证 Wait 一定会执行。

输出流和超时是一对组合拳

刚才的示例代码已经涉及 Start、Context、Wait 的组合，这也是实际生产中更常见的形式。因为很多时候，我们希望命令输出量很大时，可以一边读一边等，不至于因为输出没读完就一直卡在 Wait 上。

这里要解释一下：如果将 cmd.Stdout 设置为自定义 writer，os/exec 会创建一个 goroutine 负责把外部命令的 stdout 不断复制到 writer 中。命令退出后，Wait 会等待这些复制 goroutine 结束。如果你的 writer 因为某些原因停滞，比如内部写文件慢了，Wait 也可能被拖住。这属于另一个层面的问题，但同样值得留意。

如果不想让输出流阻塞命令执行，可以使用 StdoutPipe，自己从管道读。但这里有个容易被忽视的细节：使用 StdoutPipe 后，必须在 Start 之后尽快开始读取，否则管道依然可能在某个瞬间被写满。相比之下，直接设置 cmd.Stdout 为自定义 writer，Go 内部会帮你起 goroutine 持续复制，不需要你操心读管道的问题，代码也更简洁。

别让 shell 成为引入安全问题的入口

再说一个和运行时安全相关的问题。os/exec 执行命令时，如果你写的是 exec.Command("sh", "-c", commandString)，等于把命令交给 shell 解析。这会带来两个问题：一个是 shell 语法和 Go 程序的交互比较隐蔽，另一个是参数拼接很容易产生注入风险。

比如你想执行 git commit，参数 message 来自用户输入。有人可能会这么写：

cmd := exec.Command("sh", "-c", fmt.Sprintf("git commit -m '%s'", userInput))

如果 userInput 里包含单引号、分号，事情就会变得不可控。使用 exec.Command 直接传参数，可以绕开 shell 转义的问题：

cmd := exec.Command("git", "commit", "-m", userInput)

这里没有 shell 参与，所以 userInput 只是作为一个普通的命令行参数传给 git，不会因为特殊字符产生额外命令。

当然，有些命令必须要用 shell 特性，比如重定向、管道、变量展开。这时候依然可以执行 bash -c，但尽量不要把外部输入直接拼进 commandString。可以把外部内容通过环境变量传入，脚本里用 $VAR 读取，会安全很多。这不是 os/exec 的功能，而是一种工程习惯。

整理几条经验

写到这里，文章里提到的观点可以整理成几条可执行的原则。下次需要在 Go 里调用外部命令时，可以先过一遍：

• 先评估输出量。小输出用 Output 或 CombinedOutput；大输出用 StdoutPipe 配合 goroutine，或者直接把输出写到文件。
• 永远同时处理 stdout 和 stderr，哪怕另一个流看起来不重要。
• 用 context.WithTimeout 控制单次执行的时长，放在整个调用链的入口。
• 如果外部命令可能拉起子进程，在 Unix 上使用 Setpgid，超时后向整个进程组发信号。
• 无论成功失败，确保 Wait 有机会被调用，避免留下僵尸进程。
• 能用 exec.Command 直接传参，就别用 sh -c 拼接字符串。

这些经验不算新鲜，但每一项背后都有生产环境的故事。输出流的问题会让程序看似“卡死”，超时清理不到位会导致系统里残留大量孤儿进程。拿捏好这两块，os/exec 的大部分坑就绕过去了。