在 CI 中只检查 go fix 建议而不直接改文件

我第一次把新版 go fix 放进 CI 时，最担心的不是检查失败，而是它悄悄改了检出目录里的源文件，后续测试却在一份“工作区已经变化”的代码上运行。真正适合门禁的写法是 go fix -diff ./...：它只打印原本会应用的统一差异，不修改文件；差异为空时退出成功，存在待应用差异时退出非零，CI 可以直接据此阻止合并。

这条命令已经足够完成最小检查。真正容易踩坑的是后续包装：换了旧工具链、把输出接到 tee 却没有开启 pipefail、或者把“发现差异”和“工具运行失败”都压成同一条模糊提示。

官方命令说明：https://pkg.go.dev/cmd/go#hdr-Gofix

最小配方只有一条 go fix -diff

如果流水线使用的是新版 Go，下面这一步会检查当前模块下的包。没有可应用建议时命令安静通过；有建议时标准输出出现统一差异，进程以非零状态结束，而源文件保持不变。

# 只预览 go fix 建议，不在 CI 检出目录中改写源文件
go fix -diff ./...

我喜欢这个门禁的原因是它没有额外比较动作。无需先复制仓库、运行会改文件的 go fix，再执行 git diff --exit-code；-diff 本身就同时提供补丁内容和失败状态。

后两种情况都会失败，所以日志不能只写“代码需要 go fix”。有补丁时输出通常以 ---、+++ 和差异块呈现；加载失败则是普通错误信息。保留原始输出，开发者才能知道应该本地应用修复，还是先修复构建环境。

把门禁封装成脚本，避免每个 CI 重写一遍

仓库同时接入多个 CI 平台时，我更愿意把判断放在仓库脚本里，平台配置只负责调用。这样 Go 版本、包模式和提示文案不会在不同流水线里慢慢漂移。

#!/usr/bin/env bash
set -euo pipefail

# 打印实际工具链，便于定位本地与 CI 结果不一致的问题
go version

# -diff 只输出建议；非空补丁会让脚本直接以非零状态退出
go fix -diff ./...

脚本可以命名为 scripts/check-go-fix.sh，CI 中只执行它。这里的 set -e 会让非零状态传给任务；-u 防止未定义变量悄悄变成空值；pipefail 则为后面可能加入的日志管道预留正确语义。

steps:
  - name: Check go fix suggestions
    # 平台只调用仓库脚本，检查逻辑由项目统一维护
    run: bash ./scripts/check-go-fix.sh

CI 的 Go 安装步骤应固定明确版本。Go 1.26 对 go fix 做了基于分析框架的重写；如果本地用新版本、CI 仍是旧版本，命令行为、可用 fixer 和建议集合都可能不同。这里不必追求“永远最新”，而应让本地升级计划与 CI 版本同步。

需要保存补丁时，别让 tee 吞掉退出码

后来我想把补丁留作 CI 产物，顺手写成 go fix -diff ./... | tee go-fix.patch。表面上日志和文件都有了，任务却可能显示成功，因为普通管道默认返回最后一个命令 tee 的状态。这个问题比 go fix 本身更隐蔽。

#!/usr/bin/env bash
set -euo pipefail

# pipefail 保证 go fix 发现差异时，整个管道仍返回非零状态
go fix -diff ./... | tee go-fix.patch

如果 CI 只需要在日志里展示补丁，不需要单独上传文件，就不要加 tee，最小写法更可靠。如果确实要保存补丁，确认执行 shell 支持 pipefail，并让上传步骤在前一步失败时仍能运行；上传配置属于具体 CI 平台，但核心原则不变：保留输出不能改变检查结果。

大仓库可以拆包或拆 fixer，但不要改变只读原则

全仓检查耗时太长时，第一步不是去掉 -diff，而是缩小检查集合。Go 命令接收包模式，可以按业务子树建立并行任务；也可以在查看 go tool fix help 后，只启用团队本轮准备接纳的 fixer。

# 只检查 API 服务子树，适合拆成独立 CI 任务
go fix -diff ./cmd/api/... ./internal/api/...

# 只检查声明式 inline 修复，降低一次升级的审查范围
go fix -diff -inline ./...

# 查看当前工具链实际注册的 fixer，避免凭印象写过期名称
go tool fix help

这两种拆分控制的是不同边界：包模式决定“检查哪些代码”，fixer 开关决定“检查哪类改写”。我通常先按业务目录拆包，再在工具链大版本升级时按 fixer 分批启用。这样失败日志更短，也更容易把修复提交交给对应模块维护者。

开发者本地怎么处理 CI 发现的差异

CI 只负责提出“当前代码不是 go fix 的稳定状态”，不应该替开发者提交修改。开发者在本地使用与 CI 相同的 Go 版本和包模式，先预览，再去掉 -diff 应用修复，最后运行测试和代码审查。

# 先复现 CI 的统一差异，确认工具链和包模式一致
go fix -diff ./...

# 确认建议后，让 go fix 在本地工作区应用修复
go fix ./...

# 自动改写不能替代测试，至少覆盖本次修改涉及的包
go test ./...

# 提交前审查实际差异，确认没有意外扩大修改范围
git diff --check
git diff

官方建议从干净的 Git 状态开始运行 go fix，因为一次升级可能影响很多文件。对我来说，CI 门禁最大的价值也在这里：它把自动改写留在开发者可审查的本地提交里，而不是把流水线工作区变成一个难以复现的中间状态。

常见坑与检查清单

• 工具链过旧：先打印 go version，确认 CI 与本地使用同一条升级基线。
• 包模式过大：按业务子树拆分，不要让一个任务输出数千行差异。
• 管道掩盖失败：使用 Bash 的 set -o pipefail，或直接取消 tee。
• 错误提示过度归因：区分“非空 diff”和“包加载失败”，不要都写成需要运行 go fix。
• 直接改 CI 工作区：门禁阶段始终保留 -diff，实际修复交给本地提交。
• 把生成文件当目标：go fix 会跳过生成文件；应修复生成器逻辑，再重新生成。

相关问题

go fix -diff 会不会修改 go.mod 或源文件？

不会。该模式打印原本会应用的统一差异，不把修复写回文件。它适合 CI 预览和门禁。

CI 为什么在打印补丁后返回失败？

这是设计行为。非空差异代表存在尚未应用的修复，命令返回非零状态，让 CI 阻止未现代化的代码进入主分支。

能不能把 go fix 的补丁自动提交回分支？

技术上可以，但门禁和自动写回是两种工作流。为了保留代码审查、权限边界和可复现性，常规合并检查更适合只读预览，由开发者本地应用并提交。

go fix 通过后还需要 gofmt 和 go test 吗？

需要。go fix 只处理已注册 fixer 的安全改写建议，不能替代格式检查、编译和测试。CI 应把它作为独立门禁，与其他检查并列。

我最终保留的规则很朴素：CI 永远运行 go fix -diff，本地确认后才运行不带 -diff 的命令。再加上固定 Go 版本、保留真实退出码和拆分包范围，这个检查就能长期稳定地工作，而不会在流水线里制造隐藏修改。