Go exec.WaitDelay 为什么会返回 ErrWaitDelay

exec.ErrWaitDelay 不是“外部命令运行超时”的通用错误。它最典型的含义是：命令本身已经以成功状态退出，但 os/exec 为标准输入输出创建的 I/O 管道仍没有在 WaitDelay 内关闭，Cmd.Wait 为了结束等待而关闭管道，于是返回 ErrWaitDelay。

WaitDelay 同时约束两类等待

Cmd.Wait 不只等待主进程退出。当 Stdin、Stdout 或 Stderr 不是 *os.File 时，os/exec 可能启动 goroutine 在管道与这些 Reader/Writer 之间复制数据；Wait 还需要等待这些复制结束。

非零 WaitDelay 为两类异常等待设置上限：一是关联 Context 已结束，但子进程没有及时退出；二是主进程已经退出，但相关 I/O 管道仍保持打开。计时器从 Context 完成或 Wait 观察到进程退出二者中更早的时刻开始。

ErrWaitDelay 的精确返回条件

官方定义把条件收得很窄：进程以成功状态退出，但输出管道没有在 WaitDelay 到期前关闭。到期后，exec 会关闭仍然打开的管道来解除复制 goroutine 的阻塞；如果没有发生 Cancel 调用，且命令原本应当返回 nil，Wait 才用 ErrWaitDelay 告诉调用方“命令成功，但 I/O 收尾超时”。

因此，下面几种情况要分开判断：

为什么主进程退出了，输出管道还不关闭

常见场景是外部命令又启动了后台进程。主进程退出时，后台进程仍继承着 stdout 或 stderr 的写端；对 Go 侧读取者来说，管道还存在潜在写入者，因此读不到 EOF，Wait 也无法结束复制。

另一个来源是自定义 Writer 自身阻塞。官方文档特别提醒：即使设置了 WaitDelay，Wait 仍可能卡在一次尚未返回的 Writer.Write 上。遇到可能阻塞的写入端，应改用 StdoutPipe/StderrPipe 自己控制读取和关闭，而不是指望 WaitDelay 中断任意用户代码。

最小配置：给 I/O 收尾设置明确上限

对于预期很快结束、但偶尔会留下继承管道的命令，可以在启动前设置 WaitDelay。下面使用缓冲区承接输出；因为它不是 *os.File，exec 会管理对应的复制工作。

package main

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

func runWithIODelay(name string, args ...string) error {
    cmd := exec.Command(name, args...)
    var out bytes.Buffer
    cmd.Stdout = &out
    cmd.Stderr = &out

    // 主进程退出后，最多再等待 800 毫秒让继承的输出管道关闭。
    cmd.WaitDelay = 800 * time.Millisecond
    err := cmd.Run()

    // ErrWaitDelay 表示命令成功退出，但 I/O 收尾超过了设定上限。
    if errors.Is(err, exec.ErrWaitDelay) {
        return fmt.Errorf("command output pipe did not close: %w", err)
    }
    if err != nil {
        return fmt.Errorf("command failed: %w", err)
    }
    return nil
}

WaitDelay 必须在 Start 或 Run 之前设置。它不是业务执行时限；如果还要限制命令整体运行时间，应使用 CommandContext 和带超时的 Context。

Context 超时和 WaitDelay 应该怎么配合

CommandContext 默认在 Context 完成时调用 Process.Kill，而 WaitDelay 默认仍为零。两者配合时，Context 决定“何时开始取消”，WaitDelay 决定取消后最多还给进程退出和管道关闭多少收尾时间。

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

cmd := exec.CommandContext(ctx, name, args...)
// Context 负责整体时限，WaitDelay 负责取消后的进程和 I/O 收尾上限。
cmd.WaitDelay = 500 * time.Millisecond

err := cmd.Run()
switch {
case errors.Is(err, context.DeadlineExceeded):
    return fmt.Errorf("command exceeded execution deadline: %w", err)
case errors.Is(err, exec.ErrWaitDelay):
    return fmt.Errorf("command exited but I/O remained open: %w", err)
case err != nil:
    // 保留 ExitError 或平台级进程错误，便于上层继续分类。
    return fmt.Errorf("command execution failed: %w", err)
default:
    return nil
}

实际返回可能受进程退出状态、自定义 Cancel 和平台信号语义影响，因此分类时应使用 errors.Is 与 errors.As，不要只比较错误字符串。

按根因修复，而不是单纯增大 WaitDelay

把 500 毫秒改成 30 秒只能延后报错，不能解决描述符泄漏。更可靠的处理顺序是：

1. 确认命令是否故意派生后台进程。如果是，尽量让后台进程重定向自己的 stdout/stderr，不继承 Go 管理的管道。
2. 让主命令等待自己的后代退出。脚本或包装器应在退出前回收子进程，避免留下孤儿进程持有描述符。
3. 区分执行时限和收尾时限。整体时限交给 Context，收尾上限交给 WaitDelay。
4. 检查 Writer 是否可能阻塞。网络 Writer、无消费者的 channel 适配器或锁竞争都可能让 Write 不返回；必要时改用 Pipe 并由调用方负责读取。
5. 保留错误类型。使用 %w 包装，避免把 ExitError、Context 错误和 ErrWaitDelay 合并成一条模糊日志。

相关问题

ErrWaitDelay 是否表示进程被 Kill？

不一定。它最典型的条件是进程已经成功退出，但管道仍未关闭。Context 取消后进程迟迟不退出时，WaitDelay 也会触发 Kill，不过最终错误通常由取消或进程退出状态解释。

WaitDelay 为零会怎样？

零是默认值。此时 exec 会持续读取 I/O 管道直到 EOF；如果后代进程一直持有描述符，Wait 可能一直等下去。

把 Stdout 设为 os.Stdout 还会遇到同样问题吗？

*os.File 会直接连接到子进程，不需要 exec 启动同样的复制 goroutine，因此行为不同。但命令自身和后代进程的生命周期仍需正确管理。

应该用 err == exec.ErrWaitDelay 吗？

建议使用 errors.Is(err, exec.ErrWaitDelay)，因为上层通常会用 %w 包装错误。