Go exec.Cmd.Cancel 与 WaitDelay 分别解决什么问题

exec.Cmd.Cancel 与 WaitDelay 解决的是相邻但不同的问题：Cancel 决定 Context 完成时“用什么动作通知命令停止”；WaitDelay 决定从取消发生或进程退出被观察到以后，“最多再等待多久”，到期后会强制结束仍存活的进程并关闭仍未结束的 I/O 管道。

默认的 exec.CommandContext 把 Cancel 设置为 Process.Kill，所以超时通常直接强杀。若想先发温和信号，让程序保存状态并自行退出，就要覆盖 Cancel；为了防止它忽略信号或后代进程一直占着输出管道，再设置非零 WaitDelay 作为兜底。

Go os/exec 文档：https://pkg.go.dev/os/exec#Cmd

CommandContext 文档：https://pkg.go.dev/os/exec#CommandContext

先确认 CommandContext 的默认行为

很多代码只写了 Context 超时，却没有意识到默认取消动作是 Process.Kill。这适合必须立即终止的工具，但不适合需要刷新缓冲区、写完临时文件或优雅关闭连接的工作进程。

package main

import (
    "context"
    "fmt"
    "os/exec"
    "time"
)

func main() {
    // Context 是命令总运行时间的上限，不是 WaitDelay 的替代品。
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    // CommandContext 默认在超时时调用 Process.Kill。
    cmd := exec.CommandContext(ctx, "worker", "--once")
    if err := cmd.Run(); err != nil {
        fmt.Printf("command ended: %v\n", err)
    }
}

这里的 worker 是待替换的示例命令。关键并不是命令名，而是 CommandContext 已经填好了 Cancel；如果不覆盖，Context 到期时不会先尝试温和退出。

用自定义 Cancel 发起温和停止

Cancel 的类型是 func() error。官方说明它通常给子进程发送信号，但也可以关闭标准输入或输出管道，或者通过网络连接发送应用级停机请求。Cancel 非 nil 时，命令必须由 CommandContext 创建，而且要在命令启动前完成配置。

下面是面向 Unix 类系统的信号示例。程序先发送 os.Interrupt，给子进程自行清理的机会：

package main

import (
    "context"
    "errors"
    "fmt"
    "os"
    "os/exec"
    "time"
)

func main() {
    ctx, stop := context.WithTimeout(context.Background(), 3*time.Second)
    defer stop()

    cmd := exec.CommandContext(ctx, "worker", "--serve")

    cmd.Cancel = func() error {
        // 先发送中断信号，让支持该信号的子进程自行收尾。
        err := cmd.Process.Signal(os.Interrupt)
        if errors.Is(err, os.ErrProcessDone) {
            // 进程已经结束时返回 ErrProcessDone，避免制造额外取消错误。
            return os.ErrProcessDone
        }
        return err
    }

    // 取消后最多等待两秒；仍未退出时由 os/exec 强制 Kill。
    cmd.WaitDelay = 2 * time.Second

    if err := cmd.Run(); err != nil {
        fmt.Printf("command ended: %v\n", err)
    }
}

信号行为有平台差异，Windows 服务或跨平台程序更适合使用应用自身的关闭协议。无论 Cancel 做什么，它都只是“发起取消”；函数返回并不等于进程已经结束，真正等待进程和 I/O 收尾的仍是 Wait。

Cancel 与 WaitDelay 管的是两个阶段

WaitDelay 的计时起点不是 Start。计时器在两个时刻中较早的一个启动：关联 Context 完成，或者 Wait 观察到子进程已经退出。延时到期后，如果进程仍未结束，os/exec 会调用 Process.Kill；如果通信管道仍打开，则关闭管道以解除相关复制 goroutine 的等待。

这两个字段组合后形成常见的“两阶段停止”：Context 到期，Cancel 先做温和通知；WaitDelay 留出宽限时间；宽限时间结束后仍未退出，才执行强制 Kill。只设置 Cancel 没有等待上限，子进程可能忽略信号；只设置 WaitDelay 又不能表达业务希望采用的温和停止动作。

第二个实验：进程退出了，Wait 仍可能等管道

WaitDelay 还处理一个不太直观的场景：直接子进程已经成功退出，但它启动的后代进程继承了 stdout 或 stderr 文件描述符，导致 os/exec 的复制 goroutine 一直等不到 EOF。此时没有“活着的直接子进程”可等，卡住的是管道收尾。

以下 Unix 类系统示例让 shell 在后台启动一个短期后代进程，并立即成功退出。后台进程继承输出管道，因此 Output 可能需要等到 WaitDelay 关闭管道：

package main

import (
    "errors"
    "fmt"
    "os/exec"
    "time"
)

func main() {
    // 后台 sleep 继承 stdout；shell 输出 ready 后立即成功退出。
    cmd := exec.Command("sh", "-c", "sleep 30 & printf ready")
    cmd.WaitDelay = 500 * time.Millisecond

    output, err := cmd.Output()
    fmt.Printf("output=%q\n", output)

    if errors.Is(err, exec.ErrWaitDelay) {
        // 进程成功退出，但管道未及时关闭，WaitDelay 负责结束等待。
        fmt.Println("I/O cleanup exceeded WaitDelay")
    } else if err != nil {
        fmt.Printf("command failed: %v\n", err)
    }
}

当进程本身成功退出、没有发生 Cancel 调用，却因为 WaitDelay 到期而关闭管道时，Wait、Output 或 CombinedOutput 会返回 ErrWaitDelay，而不是 nil。这个错误说明“进程退出状态成功，但 I/O 没有按时完成”，不应和非零退出码混为一谈。

运行检查时要区分三类错误

最终错误可能来自进程退出、取消动作或等待超时。实际项目中应使用 errors.Is 和 errors.As 分类，而不是比较错误字符串。

func classify(err error, ctx context.Context) string {
    // ErrWaitDelay 表示等待进程或 I/O 收尾超过配置上限。
    if errors.Is(err, exec.ErrWaitDelay) {
        return "wait-delay"
    }

    // Context 错误说明命令因超时或上游取消进入停止流程。
    if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
        return "context-canceled"
    }

    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        // ExitError 保存进程非零退出状态，可继续读取 ExitCode。
        return fmt.Sprintf("exit-%d", exitErr.ExitCode())
    }
    if err != nil {
        return "start-or-cancel-error"
    }
    return "success"
}

自定义 Cancel 还有一个容易忽略的规则：如果 Cancel 已被调用，进程随后以成功状态退出，而 Cancel 没有返回等价于 os.ErrProcessDone 的错误，那么 Wait 仍会返回非 nil 错误，可能包装 Cancel 错误或 Context 错误。因此“子进程退出码是 0”不必然意味着 Run 返回 nil。

三个常见误区

误区一：WaitDelay 等于命令总超时

不是。命令总运行时限应由 Context 控制。没有可完成的 Context，且进程一直不退出时，WaitDelay 不会从 Start 开始自行倒计时。它只在 Context 完成或 Wait 观察到进程退出后开始。

误区二：设置 WaitDelay 就一定不会卡住

也不一定。官方文档特别说明，如果提供给 Stdin 的 Reader 本身阻塞，或提供给 Stdout、Stderr 的 Writer 在 Read/Write 调用中阻塞，Wait 即使配置了 WaitDelay 也可能继续等待。需要完全控制时，使用 StdinPipe、StdoutPipe 或 StderrPipe，并由调用方负责关闭与复制 goroutine 的生命周期。

误区三：Cancel 可以在普通 exec.Command 上随便设置

不可以。Cancel 非 nil 时，命令必须由 CommandContext 创建。普通 exec.Command 可以单独使用 WaitDelay 处理进程退出后的管道拖延，但没有 Context 驱动 Cancel。

组合策略怎么选

收尾检查清单

1. 用 Context deadline 表达命令允许运行的总时间。
2. 确认默认 Kill 是否符合业务；需要优雅退出时，在启动前覆盖 Cancel。
3. 为温和退出设置有限 WaitDelay，避免忽略信号的进程无限等待。
4. 分别记录 Context 错误、ExitError 与 ErrWaitDelay。
5. 检查子进程是否会派生继承 stdout/stderr 的后代进程。
6. 不要让自定义 Reader 或 Writer 的阻塞破坏收尾上限。
7. 同一个 Cmd 在 Start、Run、Output 或 CombinedOutput 后不能复用。

最实用的记法是：Cancel 管“怎么停”，WaitDelay 管“停不下来或管道收不完时最多等多久”。Context、Cancel、WaitDelay 三者各司其职，才能把外部命令的正常运行、温和取消和强制兜底组合成可预测的生命周期。

相关问题

Cancel 为 nil 时 WaitDelay 还有效吗？

有效。Context 完成时不会立即执行取消动作，但非零 WaitDelay 仍会开始计时，到期后可 Kill 仍未退出的进程并关闭管道。

WaitDelay 为 0 表示什么？

表示不设置额外等待上限。输出管道会继续读取到 EOF，孤儿后代进程若仍持有描述符，等待可能持续到它们关闭描述符。

什么时候会返回 ErrWaitDelay？

典型情况是进程已成功退出、没有发生 Cancel，但输出管道在 WaitDelay 内没有关闭，os/exec 因而关闭管道并结束等待。

自定义 Cancel 一定要发系统信号吗？

不一定。它也可以关闭输入管道，或调用应用自己的网络停机接口，只要动作能启动取消过程并正确返回错误。