Cobra RunE 返回错误后怎么统一设置命令退出码

Cobra 子命令已经改成 RunE，但执行失败后命令仍然返回 0，通常不是 Cobra 没有传递错误，而是错误停在了命令层，main 没有接住 Execute 的返回值。稳定的做法是把职责拆成三层：RunE 产生并返回错误，Execute 原样向上返回，main 负责打印一次错误并转换为非零退出码。

官方地址：https://github.com/spf13/cobra

不要在每个 RunE 里调用进程退出。让所有执行错误回到 main，在那里统一决定输出和退出状态。

RunE 为什么能把错误交给 Execute

Cobra 的 Run 没有错误返回值，适合不会失败或已经在内部处理完错误的动作。需要把失败交给上层时，应使用 RunE func(*Command, []string) error。在回调中遇到错误直接返回，成功时返回 nil。

package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var syncCmd = &cobra.Command{
    Use:   "sync",
    Short: "同步远端数据",
    RunE: func(cmd *cobra.Command, args []string) error {
        if err := syncData(); err != nil {
            // 只把原始错误交给上层，避免这里和 main 重复打印。
            return fmt.Errorf("同步数据失败: %w", err)
        }
        return nil
    },
}

func syncData() error {
    // 示例只表达失败边界，真实项目中这里放网络或文件操作。
    return fmt.Errorf("远端响应不可用")
}

关键是返回链没有被截断。RunE 返回非 nil 后，Execute 才有机会把错误交给调用它的函数。

Execute 不退出，只负责向上传递

将根命令封装在 cmd 包时，建议让导出的 Execute 返回 error。这样命令包可以在单元测试中被调用，也不会把进程级副作用带进库代码。

package cmd

import "github.com/spf13/cobra"

var rootCmd = &cobra.Command{
    Use:           "syncer",
    SilenceErrors: true,
    SilenceUsage:  true,
}

// Execute 只负责启动 Cobra 并把错误交给 main。
func Execute() error {
    return rootCmd.Execute()
}

SilenceErrors: true 阻止 Cobra 自动再打印一遍错误，SilenceUsage: true 避免每次业务失败都附带一大段用法说明。它们不改变错误是否返回，只改变默认输出行为。

在 main 统一设置退出码

进程退出码属于应用边界，不应散落在多个子命令里。main 可以把成功映射为 0，把任意未处理的 Execute 错误映射为固定非零值。

package main

import (
    "fmt"
    "os"
    "example.com/syncer/cmd"
)

func main() {
    os.Exit(run())
}

func run() int {
    if err := cmd.Execute(); err != nil {
        // 统一在进程边界输出一次，便于 shell 和 CI 同时读取状态。
        fmt.Fprintln(os.Stderr, err)
        return 1
    }
    return 0
}

这样，成功时进程退出码是 0；任意命令错误、参数校验错误或未知命令错误回到 main 后，统一返回 1；错误输出也只集中在一个位置。

参数错误也要走同一个出口

不要只在业务函数失败时处理退出码。Cobra 的参数校验、未知子命令和 RunE 返回的业务错误，最终都应由同一个 cmd.Execute() 调用接住。下面用 Args 限制参数数量，验证失败时仍然不需要在命令层调用 os.Exit。

var exportCmd = &cobra.Command{
    Use:   "export FILE",
    Short: "导出一个文件",
    Args:  cobra.ExactArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        // 参数已经由 Cobra 检查，这里只处理真正的导出动作。
        return exportFile(args[0])
    },
}

如果用户漏传文件名，Execute 仍返回错误，run 仍然打印一次并返回 1。脚本只需要判断进程状态，不必猜测错误来自哪一层。

常见写法为什么会让退出码失效

一套可复用的检查顺序

1. 确认可能失败的子命令使用 RunE，而不是无法返回错误的 Run。
2. 确认 RunE 失败时执行 return err，没有只写日志后返回 nil。
3. 确认 cmd.Execute() 的返回值一路传到了 main。
4. 确认只有 main 调用 os.Exit，错误写到标准错误。
5. 确认 SilenceErrors 与 SilenceUsage 的设置符合团队对输出的预期。

如果目标只是让脚本知道“成功还是失败”，固定使用 0 和 1 就足够。不要为了让退出逻辑更复杂，就把进程控制塞回每个 RunE。

相关问题

RunE 返回错误后 Cobra 会自动退出进程吗？

不会。它把错误返回给 Execute 的调用方，是否打印和如何退出由外层程序决定。

为什么建议把 run 单独拆出来？

把 os.Exit 留在 main 后，run 可以直接返回整数，测试时能覆盖成功和失败分支，而不必让测试进程真的退出。

只设置 SilenceUsage 就能避免重复错误吗？

不能。SilenceUsage 只控制用法说明；如果 main 自己打印错误，还应根据需要设置 SilenceErrors。