Go gofmt -d 输出为空但 CI 仍失败可能是什么

遇到“gofmt -d 没有输出，但 CI 仍然失败”，我通常先不改代码。这个现象往往说明观察的不是同一个判定：-d 负责把格式差异打印出来，CI 可能还在检查另一批文件、Git 工作区，或者某个管道的退出码。先把文件集合和失败命令拆开，通常比反复执行 gofmt 更快。

官方文档：https://pkg.go.dev/cmd/gofmt

最稳妥的做法是让本地和 CI 都从 Git 已跟踪的 *.go 文件生成清单，用 gofmt -l 判断是否有未格式化文件；gofmt -d 只作为人类查看差异的辅助输出。

先分清 gofmt、gofmt -l 与 CI 的职责

gofmt -d 的语义是“如果格式不同，就把差异写到标准输出”；gofmt -l 则只列出需要格式化的文件名。两者都不等同于“整条 CI 通过”。真正让任务失败的，常见是外层脚本的 test、grep、git diff --exit-code 或构建命令。

例如，下面两条命令观察的对象就不同：第一条只看 Go 格式化结果，第二条比较整个工作区相对提交的变化。前者为空，不能推出后者一定返回 0。

# -d 只展示 gofmt 认为需要调整的内容，不负责定义 CI 失败条件
gofmt -d ./...

# --exit-code 在存在 Git 差异时返回 1；它检查的范围由路径参数决定
git diff --exit-code -- .

如果 CI 日志只保留了第一条命令的标准输出，最先要补的是每个命令的退出码和实际执行目录，而不是给源码再跑一遍格式化。

把本地和 CI 的 Go 文件集合固定下来

“本地为空、CI 失败”的第一嫌疑是文件集合不同。你在仓库根目录运行 gofmt -d .，而 CI 可能先切换到子目录；或者本地 shell 的 glob 没有匹配到文件，CI 脚本却通过 git ls-files 找到了生成目录中的 Go 文件。gofmt 对目录会递归处理其中的 Go 文件，但隐藏目录会被忽略，路径入口不同就会改变集合。

我更倾向于把“哪些文件参与检查”写成显式清单，再用 -l 作机器判定：

#!/usr/bin/env bash
set -u

bad=0
# 只从 Git 已跟踪文件取样，避免本地未提交生成文件改变检查范围
while IFS= read -r file; do
  # -l 输出文件名；有输出就记录为格式化失败
  if [ -n "$(gofmt -l "$file")" ]; then
    printf '需要 gofmt：%s\n' "$file"
    bad=1
  fi
done 

排查时把 pwd、git ls-files -- '*.go' 和 CI 的工作目录一起打印出来。不要用一个省略路径的 gofmt -d 结果去推断另一套文件集合。

检查 CRLF、LF 与 Git 的换行符边界

换行符问题容易让人误判，因为编辑器、Git checkout、格式化工具和 CI 容器可能各自做过一次处理。重点不是盯着页面上有没有明显差异，而是确认本地与 CI 看到的文件字节、.gitattributes 规则和 checkout 配置是否一致。

建议先看 Git 认为哪些文件发生变化，再看属性和原始字节；如果工作区在执行检查前被某个步骤重新生成，也要把那一步单独记录。

# 查看格式检查前，Git 工作区实际有哪些变化
git status --short
git diff --name-only -- '*.go'

# 查看某个 Go 文件在当前仓库中的换行属性
git check-attr text eol -- path/to/file.go

# 用可见标记观察行尾，避免把 CRLF/LF 差异当成普通空格
sed -n '1,12l' path/to/file.go

如果仓库要求统一 LF，就在 .gitattributes 中固定规则，并让 CI 使用干净 checkout；如果项目确实保留 CRLF，则不要只在本机编辑器里改变行尾后再比较。任何“自动修复格式”的步骤都应放在检查前或完全移除，不能让检查过程一半读旧文件、一半读新文件。

拆开管道，找出真正返回非零的命令

CI 脚本经常把多个命令串在一行，导致日志看起来像是 gofmt -d 失败。比如管道后半段的 grep 没有匹配、test -z 的条件写反，或者 shell 没有启用 pipefail。把命令拆成“列出文件、判断文件、比较工作区”三层，并在每层打印结果。

#!/usr/bin/env bash
set -u -o pipefail

# 先把格式问题变成稳定的文件名清单
formatted_files="$(git ls-files -- '*.go' | while IFS= read -r file; do
  gofmt -l "$file"
done)"

# 空清单才表示格式化检查通过，避免把 diff 文本当作布尔值
if [ -n "$formatted_files" ]; then
  printf '%s\n' "$formatted_files"
  exit 1
fi

# 只有明确要求检查工作区时才比较整个 Git diff，避免范围偷偷扩大
git diff --check -- '*.go'

这里的 git diff --check 与格式化检查也不是一回事：它主要报告空白错误和冲突标记。若它失败，日志中应明确写出“Git diff 检查失败”，不要把责任归给空输出的 gofmt -d。

一张表确定修复方向

常见追问

应该用 gofmt -d 还是 gofmt -l 做 CI 门禁？

机器门禁优先用 gofmt -l 判断文件名，失败时再调用 gofmt -d 展示差异。这样“是否失败”和“如何阅读失败”各自只有一个来源。

为什么只看 git diff --exit-code 不够？

它的范围取决于路径参数和工作区状态，可能包含非 Go 文件或其他生成步骤的改动。先确定目标文件集合，再决定是否需要 Git 差异检查。

这类问题的关键不是让某条命令输出更多，而是让输入文件、换行符处理和退出码来源保持一致。做到这三点，空输出与 CI 失败就能被拆成可定位的具体分支。