Golang中的错误处理与命令模式 Go语言CLI工具错误输出规范

P粉602998670

发布时间：2026-02-25 17:11:21

137人浏览过

来源于php中文网

原创

用 fmt.fprintln(os.stderr, ...) 输出用户可见错误，因其输出干净无前缀；退出码优先用1，但i/o错误等应区分语义；cobra需显式处理execute()返回的error并写stderr；自定义错误若包装底层error须实现unwrap()。

golang中的错误处理与命令模式 go语言cli工具错误输出规范

Go CLI 工具该用 `fmt.Fprintln(os.Stderr, ...)` 还是 `log.Println`？

直接结论：用 fmt.Fprintln(os.Stderr, ...)，别用 log 包输出用户可见错误。

log 默认往 os.Stderr 写没错，但它会自动加时间戳、前缀（如 2024/05/12 10:30:15 ），破坏 CLI 工具的输出可预测性——尤其当用户管道接 grep 或写脚本解析时，多出来的前缀就是 bug 源头。

命令行工具的错误信息必须「干净」：只含必要内容，无额外格式
log.SetPrefix("") 和 log.SetFlags(0) 能去掉前缀，但不保险：其他包可能改全局 log 配置，导致行为漂移
如果真要复用日志逻辑（比如调试模式下加 trace），应封装自己的 errOut 函数，底层仍直写 os.Stderr

示例正确写法：

fmt.Fprintln(os.Stderr, "error: file not found:", filename)

错误退出码该返回 `1` 还是其他数字？

返回 1 是安全默认，但不是万能解。POSIX 规定非零即错，但不同退出码对自动化脚本意义重大。

立即学习“go语言免费学习笔记（深入）”；

比如 grep 用 1 表示「没匹配到」（非错误），2 才是「读文件失败」；你的工具若统一返回 1，上游脚本就无法区分「空结果」和「真出错」。

知元AI

AI智能语音聊天对讲问答 AI绘画 AI写作 AI创作助手工具

下载

常见约定：1 通用错误，2 参数解析失败（flag.Parse() 后的 flag.ErrHelp 类错误），3 I/O 错误，127 命令未找到（留给 shell 层）
避免用 0 表示错误，也别用负数（shell 只取低 8 位，-1 变成 255）
在 main() 函数末尾用 os.Exit(code) 显式退出，别依赖 return —— 否则 defer 可能干扰错误码

`cmd.Execute()` 失败后为什么错误没打出来？

因为 github.com/spf13/cobra 的 cmd.Execute() 默认只打印错误消息（调用 cmd.SilenceErrors = false 时），但不会自动写到 os.Stderr，也不带换行，更不设退出码。

典型现象：执行 mytool invalid-subcmd，终端只闪一下没输出，返回码却是 0，脚本以为成功了。

必须显式设置 cmd.SilenceErrors = false（默认就是 false，但有些模板会设成 true）
更关键的是：cmd.Execute() 返回 error，你得自己处理——不能只写 if err := cmd.Execute(); err != nil { os.Exit(1) }

正确做法：

if err := rootCmd.Execute(); err != nil {
    fmt.Fprintln(os.Stderr, "error:", err)
    os.Exit(1)
}

自定义错误类型要不要实现 `Unwrap()`？

要，只要它包装了底层错误（比如网络超时、文件权限拒绝），且你希望上层能用 errors.Is() 或 errors.As() 判断原始原因。

否则 errors.Is(err, os.ErrPermission) 会返回 false，即使你的错误内部包裹着它——这会让 CLI 工具无法针对特定系统错误做差异化提示（比如对 os.ErrPermission 提示「请检查文件权限」，对 context.DeadlineExceeded 提示「请求超时」）。