Go gofmt 和 goimports 怎么接入保存前的自动检查

可以把职责拆成两层：保存文件时让 goimports -w 自动回写格式和 import，提交或 CI 时用 gofmt -l、goimports -l 只报告不符合规则的文件。这样开发者得到即时修复，流水线仍然保留一个不会偷偷改代码的质量门禁。

先分清 gofmt 和 goimports 的边界

gofmt 是 Go 工具链提供的标准格式化程序，处理缩进、对齐和注释布局；go fmt 则是面向包的调用方式。goimports 使用相同的格式化风格，还会根据源码调整 import，因此更适合接在编辑器保存动作上。

两者不要在同一阶段互相覆盖。一个实用选择是：保存时只调用 goimports，CI 时分别运行两个只读检查。goimports -l 有输出时，说明文件经过它处理后会发生变化；这正适合被流水线当成失败条件。

把 goimports 接到保存前的当前文件

先安装工具，并让编辑器找到与团队约定相同的可执行文件。官方 x/tools 文档给出的安装入口是下面这条命令；实际项目可以在开发文档中固定 Go 工具链与依赖版本。

# 安装 Go 官方工具仓库提供的 goimports 命令
go install golang.org/x/tools/cmd/goimports@latest

# 先确认编辑器使用的 PATH 能找到它
command -v goimports
goimports -h

如果编辑器支持“保存时运行外部格式化器”，将当前文件路径传给 goimports -w 即可。没有原生配置入口时，可以保存一个很薄的脚本：

#!/usr/bin/env sh
# 编辑器把当前 Go 文件作为第一个参数传入
file="$1"

# 非 Go 文件直接跳过，避免误改配置或模板
case "$file" in
  *.go) exec goimports -w "$file" ;;
  *) exit 0 ;;
esac

保存动作只应该覆盖当前文件，不要在每次按保存时扫描整个仓库。若 import 归组还需要区分本地模块，可以在团队脚本中追加 -local example.com/project，但这个值必须与 go.mod 的 module 路径一致。

把同一规则放进提交和 CI 门禁

保存时允许工具自动修复，CI 则应该只读检查。这样流水线失败后，开发者能从 diff 看出到底是排版变化还是 import 变化，而不是让 CI 悄悄改工作区。

# CI 只检查，不回写文件；有输出就让任务失败
test -z "$(gofmt -l .)"
test -z "$(goimports -l .)"

# 格式通过后再运行项目测试
go test ./...

如果仓库包含 vendor、生成代码或刻意保留的外部目录，先定义检查范围，再把相同范围用于两条命令。例如只检查模块自己的 Go 文件：

# 只对当前模块目录做格式门禁，排除 vendor 目录
gofmt -l -- *.go internal cmd 2>/dev/null
goimports -l -- *.go internal cmd 2>/dev/null

更稳妥的做法是把范围写进 Makefile 或 CI 配置，并在失败时打印文件名。不要把 goimports -w 放进 CI 的最后一步再上传修改后的工作区，那会掩盖提交者没有运行保存检查的问题。

失败时先查版本、路径和文件边界

“我本地保存没问题，CI 却失败”通常不是 Go 代码突然变了，而是工具来源不同。先在日志中打印 go version、command -v goimports，确认 CI 没有调用系统里另一份旧二进制。其次检查 goimports 是否能在模块上下文中解析 import；代理、私有模块权限或错误的 module 路径，都可能让导入整理结果不同。

生成文件也要有明确约定：如果它们由固定脚本产生，就把格式化放进生成流程并提交稳定结果；如果不属于源码审查范围，就从检查目录排除，同时把排除理由写入项目文档。不要只为让 CI 变绿而关闭检查。

常见问题

保存时只用 gofmt，不用 goimports 可以吗？

可以，但缺失或未使用的 import 仍要由其他工具处理。希望保存后代码能直接编译时，通常让 goimports 接管保存动作更省一步。

为什么 CI 要用 -l，而不是直接用 -w？

-l 只列出会发生变化的文件，失败结果对应提交内容，便于审查和复现；-w 会修改工作区，可能把真正的问题隐藏在流水线环境里。

gofmt 和 goimports 都没有输出，是否代表代码正确？

只代表格式和 import 检查通过，不代表类型检查、测试或静态分析通过。仍应继续执行项目自己的 go test ./... 和必要的分析命令。

最终可以把规则记成一句话：编辑器负责及时修复，提交钩子负责提醒，CI 负责用只读命令拦截不一致。三处调用的工具版本和文件范围保持一致，保存前自动检查才不会变成另一套隐藏规则。