os/exec Cmd.Cancel 设计超时后的退出动作

如果 Go 程序通过 exec.CommandContext 启动外部命令，并用 context.WithTimeout 设置时限，超时后默认动作不是“等待命令自己结束”，而是调用 Cmd.Cancel；默认的 Cancel 会对已经启动的进程调用 Process.Kill。这个默认值适合必须立即止损的任务，但不一定适合需要先清理临时文件、刷新输出或发送协议级退出请求的命令。

更稳妥的设计是把超时看成一个退出流程：先由 Cancel 发起可控的停止动作，再由 Wait 等待进程与 I/O 收尾，必要时用 WaitDelay 设置最后的硬边界。下面只讨论 os/exec 的这几个字段如何配合，示例中的命令是演示用的外部进程。

先看清 CommandContext 的默认取消动作

CommandContext 把 Context 保存到 Cmd，并预置一个 Cancel 函数。Context 在命令自然完成前结束时，运行时会调用这个 Cancel；默认实现调用 cmd.Process.Kill()。因此，最小可用写法如下：

package main

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

func runWithTimeout() error {
    ctx, cancel := context.WithTimeout(context.Background(), 800*time.Millisecond)
    defer cancel() // 释放定时器，避免调用方提前返回后仍保留资源

    cmd := exec.CommandContext(ctx, "sh", "-c", "sleep 5")
    err := cmd.Run() // 超时后默认 Cancel 会 Kill 已启动的进程
    if errors.Is(ctx.Err(), context.DeadlineExceeded) {
        return err // 记录为超时；err 通常还会包含进程退出信息
    }
    return err
}

这里有三个容易忽略的点。

• Cancel 非空的 Cmd 必须由 CommandContext 创建；给普通 Command 手工塞入 Cancel 会在启动时返回错误。
• 调用 Start 失败时不会触发 Cancel，因为进程根本没有成功启动。
• 取消动作和最终错误不是一回事。Context 超时、Kill 的结果、子进程退出状态以及 I/O 复制错误，可能在 Wait 阶段共同影响返回值。

把 Cmd.Cancel 改成可控的退出策略

自定义 Cancel 的目标不是把所有清理工作都塞进回调，而是快速发起一个能让子进程自行收尾的动作。Unix 场景可以发送温和信号；跨平台程序也可以关闭标准输入、写入约定好的退出命令，或调用本地 IPC。Cancel 不应调用 Wait，否则容易与主流程的等待发生竞态。

package main

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

func runGracefully() error {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel() // 释放超时上下文

    cmd := exec.CommandContext(ctx, "sh", "-c", "trap 'exit 0' TERM; sleep 5")
    cmd.Cancel = func() error {
        if cmd.Process == nil {
            return os.ErrProcessDone // 尚未启动或已经完成，不再重复操作
        }
        err := cmd.Process.Signal(syscall.SIGTERM) // 先请求子进程自行清理
        if err != nil && !errors.Is(err, os.ErrProcessDone) {
            return err // 只有真实取消失败才交给 Wait 归因
        }
        return nil
    }
    cmd.WaitDelay = 500 * time.Millisecond // 温和退出后仍然保留最后等待边界

    err := cmd.Run() // Run 内部负责 Start 与 Wait，Cancel 不要自行 Wait
    if errors.Is(ctx.Err(), context.DeadlineExceeded) {
        return err // 业务日志同时记录 deadline 与 err
    }
    return err
}

这个例子只适用于支持该信号语义的平台；如果命令本身提供“关闭输入即退出”的协议，优先使用协议动作。一个好的 Cancel 通常只做“发起退出”与“判断进程是否已经结束”，不负责等待、不重复启动，也不把正常结束包装成新的故障。

用 os.ErrProcessDone 区分已完成进程

超时回调与子进程退出可能几乎同时发生。比如子进程刚刚写完结果并退出，Context 也在同一时间结束；此时向进程发送信号可能得到“进程已结束”的结果。若这个结果等价于 os.ErrProcessDone，可以让 Wait 按命令原本的退出状态继续判断，而不是把取消回调的返回值当作新的失败原因。

func cancelOnce(cmd *exec.Cmd) error {
    if cmd.Process == nil {
        return os.ErrProcessDone // 没有可取消的进程
    }
    err := cmd.Process.Kill()
    if errors.Is(err, os.ErrProcessDone) {
        return os.ErrProcessDone // 进程已自行结束，保留原始退出结果
    }
    return err // nil 或真正的 Kill 失败交给 os/exec 继续处理
}

文档约定是：如果 Cancel 被调用后命令以成功状态退出，而 Cancel 返回的错误又不等价于 os.ErrProcessDone，Wait 仍会返回非空错误；如果命令以非零状态退出，或 Cancel 返回等价于 os.ErrProcessDone 的错误，则继续使用命令通常的退出状态。这个约定正是自定义 Cancel 时错误语义的关键。

用 WaitDelay 收住残留进程和管道

自定义 Cancel 只表示“开始取消”，不保证子进程立即退出。子进程可能忽略信号，或者已经退出但仍有继承的 stdout/stderr 管道没有关闭，导致 Wait 长时间收尾。WaitDelay 为这两类延迟提供统一上限：

func runWithBoundedWait(cmd *exec.Cmd) error {
    cmd.WaitDelay = 3 * time.Second // 给子进程和 I/O 一个明确的最后期限
    err := cmd.Run() // Run 会等待进程退出及相关 I/O 复制完成
    if errors.Is(err, exec.ErrWaitDelay) {
        return err // 单独记录 ErrWaitDelay，避免把收尾超时误归为业务退出码
    }
    return err
}

这个片段重点展示的是 WaitDelay 的判断方式。WaitDelay 计时会在 Context 结束，或 Wait 观察到子进程已退出时启动，以先发生者为准。时间到后，os/exec 会结束仍未退出的子进程和/或关闭相关管道，并可能返回 exec.ErrWaitDelay。因此，WaitDelay 是收尾边界，不是替代 Cancel 的第一步。

设计错误归因与可观测字段

生产日志至少要把“为什么停止”和“怎么停止”分开。建议保留任务 ID、命令类型、超时预算、Context 错误、Cancel 动作、进程退出状态、WaitDelay 是否触发以及 stderr 摘要；不要把完整用户输入直接拼进日志或 shell 命令。

不要只通过 err != nil 判断“是不是超时”。Context 的 Err() 说明取消原因，Wait 返回值说明命令执行和收尾结果，两者应分别记录；业务层再把它们组合成用户看得懂的状态。

最后的实现检查

1. 使用 CommandContext 创建命令，并在调用方负责取消 Context。
2. 默认 Kill 已经足够时，不要为了形式自定义 Cancel。
3. 需要温和退出时，让 Cancel 只发起动作，不在回调内 Wait。
4. 处理进程已结束的竞态，必要时返回等价于 os.ErrProcessDone 的错误。
5. 为不可靠的子进程和 I/O 设置 WaitDelay，并把 exec.ErrWaitDelay 单独归因。

常见问题

Cmd.Cancel 能不能直接给普通 Command 设置？

不能。Cancel 非空时，Cmd 必须来自 CommandContext；普通 Command 没有关联 Context，启动时会被 os/exec 拒绝。

自定义 Cancel 返回 nil 就代表命令已经结束了吗？

不是。nil 只表示取消动作本身没有报告错误，Wait 仍要等待子进程和 I/O。若命令不退出，WaitDelay 才能提供最后的时间边界。

什么时候应该继续使用默认 Kill？

任务没有可用的优雅退出协议、超时后必须立即释放资源，或子进程不可信时，默认 Kill 往往更容易解释。自定义 Cancel 应建立在明确的退出契约上。

WaitDelay 可以单独解决子进程不退出吗？

它能提供最终收尾上限，但不是业务级停止协议。先选择合适的 Cancel 动作，再用 WaitDelay 防止异常子进程或管道让等待无限延长。

总之，Cmd.Cancel 决定超时发生时如何“开始退出”，Wait 决定如何接收最终结果，WaitDelay 负责为异常收尾设上限。把三者分工写进代码和日志，外部命令的超时行为才会稳定、可解释。