Go exec.Cmd 怎样区分退出码与启动错误

调用外部命令时，Run 返回一个非空 error，并不等于“拿到了一个退出码”。最稳妥的分法是：先用 errors.As 判断它是不是 *exec.ExitError；是的话，通常说明进程已经启动但没有以零状态结束，再从 ProcessState.ExitCode() 读取退出码。不是的话，优先按启动失败、命令查找失败或 I/O 等待错误处理。

这篇只讨论 Start/Run 的返回值、ExitError 和 ProcessState。官方文档说明，Run 等价于先启动再等待；Start 成功后必须调用 Wait 释放进程相关资源。

先把“没启动”和“启动后失败”分开

很多代码直接写成 if err != nil { return 1 }，这样会把“可重试的命令不存在”和“子进程明确返回 1”混在一起。两者的处理方式不同：前者应该记录启动阶段的原因，后者则可以把退出码交给上层策略。

从调用关系看，可以先记住这条规则：

• Start 返回错误：进程没有成功进入运行阶段，通常没有可读的子进程退出码。
• Run 返回 *exec.ExitError：命令已经启动，但没有以零退出状态结束。
• 返回其他错误：还可能是标准输入输出复制、等待上下文或其他 I/O 问题，不能强行转换成业务退出码。

用 ExitError 读取真实退出码

*exec.ExitError 里有一个 ProcessState。当进程已经结束时，可以调用 ExitCode。下面的函数把三类结果转成调用方更容易处理的结构：启动阶段错误保留原始错误，非零退出返回退出码，成功则返回 0。

package main

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

// runCommand 只把“进程已启动后的非零结束”解释为退出码。
func runCommand(name string, args ...string) (int, error) {
    // Command 只组装 Cmd；真正的启动仍由 Run 完成。
    cmd := exec.Command(name, args...)
    err := cmd.Run()
    if err == nil {
        // 零退出状态表示命令正常完成。
        return 0, nil
    }

    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        // ExitCode 读取已经结束的进程状态；信号退出时可能返回 -1。
        return exitErr.ProcessState.ExitCode(), err
    }

    // 这里保留启动、查找或 I/O 错误，不能伪造一个退出码。
    return -1, err
}

func main() {
    // 参数让示例命令以非零状态结束，用于演示分类逻辑。
    code, err := runCommand("sh", "-c", "exit 7")
    fmt.Printf("code=%d err=%v\n", code, err)
}

示例的关键不是把 -1 当成某个固定系统错误，而是告诉调用方“这里没有可靠的普通退出码”。如果需要区分具体启动原因，应继续用 errors.Is 或检查错误文本对应的包装类型，不要覆盖原始错误。

比较 Run 与 Start/Wait 的语义

Run 适合一次性执行：它内部先调用 Start，再调用 Wait。如果任务需要异步启动、写入标准输入或在等待前建立管道，就应该拆开写，但拆开后必须确保 Wait 只调用一次。

package main

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

func startAndWait() error {
    // Start 只负责发起进程，不会等待命令结束。
    cmd := exec.Command("sh", "-c", "exit 3")
    if err := cmd.Start(); err != nil {
        // 启动失败时没有可用的子进程退出码。
        return fmt.Errorf("start command: %w", err)
    }

    // Wait 必须执行，既回收资源，也把最终 ProcessState 写入 Cmd。
    err := cmd.Wait()
    if err == nil {
        return nil
    }

    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        // 这里可以按退出码映射重试、告警或业务状态。
        return fmt.Errorf("command exited with %d: %w", exitErr.ProcessState.ExitCode(), err)
    }
    return fmt.Errorf("wait command: %w", err)
}

如果只需要命令输出，可以使用 Output 或 CombinedOutput，但判断思路不变：先识别 *exec.ExitError，再读取状态。使用管道时尤其要注意读取与 Wait 的先后关系，避免把输出复制错误误判成子进程退出码。

平台和工程边界要提前写清

第一，ExitCode 是进程状态的通用接口，不应把某个 Unix 信号值硬编码成所有平台都相同的业务含义。若进程被信号终止，退出码可能是 -1，这时应结合 ProcessState 的平台信息记录原因。

第二，命令不存在、权限不足或可执行文件解析失败属于启动阶段问题。它们没有“子进程返回了多少”的事实，重试策略通常应该围绕环境、路径和权限处理。

第三，调用方可能用 fmt.Errorf("...: %w", err) 包装错误，所以不要用类型断言直接断定顶层类型。errors.As 能沿包装链查找 *exec.ExitError，更适合库代码。

可以用下面的速查表固定团队约定：

常见问题

为什么不能对所有 error 都调用 ExitCode？因为只有 *exec.ExitError 才表示命令已经启动并以失败状态结束，启动失败没有对应的子进程状态。

Start 成功后只读取 cmd.Process 可以吗？不可以。仍要调用 Wait，否则资源没有按 os/exec 的约定完成回收，也拿不到最终的等待结果。

应该返回退出码还是原始 error？工程接口通常同时保留：退出码用于策略判断，原始 error 用于日志和诊断。不要只返回一个整数而丢掉上下文。

最终判断可以压缩成一句话：先判断命令是否成功运行，再用 errors.As 识别 *exec.ExitError，只有确认进程已经启动后，才从 ProcessState.ExitCode() 读取退出码。