Go gofmt 怎样只检查而不改写生成目录

只检查 Go 格式而不改写文件，使用 gofmt -l 查看文件名，或用 gofmt -d 查看差异，并确保没有附带 -w。如果生成目录需要排除，应在文件枚举阶段明确剪枝；生成文件头部的标记不等于 gofmt 自动忽略规则。CI 则要同时处理工具错误与格式差异，不能只看命令有没有执行完。

gofmt 官方地址：https://pkg.go.dev/cmd/gofmt

现象：检查任务改了文件，或者有差异仍通过

一个常见的配置组合是把本地自动修复命令直接放进 CI，结果生成目录也被改写；另一个组合是使用 -l 打印不规范文件，但脚本没有把非空列表转成失败。我更倾向于将“发现问题”和“修改源码”分成两个入口，这样失败任务留下的是问题清单，而不是需要猜测来源的工作区变更。

以下是可复用的原创脚本示例，没有声称在本文工作区运行过，也没有虚构 CI 日志。示例假定仓库根目录下的 generated、vendor、.git 不参与检查，实际目录名应按仓库规则调整。

分层检查：先看参数，再看文件范围

# 单文件只读检查：把路径替换为实际文件
gofmt -l ./internal/example.go
# 需要解释差异时单独使用 -d，不附带 -w
gofmt -d ./internal/example.go

不要给 gofmt 传 ./... 并期望它按 go test 的包模式展开。它接收文件或目录；要排除指定路径，自己提供筛选后的文件集合更清楚。也不要直接运行 gofmt -w .，再依靠 git diff 判断，这已经改变了文件。

证据判断：生成标记与目录排除不是一回事

Go 对生成代码有标准注释约定，典型形式为 // Code generated by examplegen. DO NOT EDIT.，应位于 package 子句之前。这个约定帮助工具识别生成来源，但不能据此假定所有工具都会跳过该文件。

对于有固定生成目录的项目，我建议优先使用路径规则：它直接表达仓库约束，且不会因为某个生成器漏写注释而改变范围。缺点是目录移动时必须同步规则。如果同一个目录混有手写和生成文件，简单跳过整个目录就不合适。

需要按注释精确识别时，可在自定义文件选择器里使用 go/ast.IsGenerated；该 API 自 Go 1.21 提供，语法树解析必须包含 parser.ParseComments。将它作为筛选策略单独实现，而不是对文件内容做宽泛的 DO NOT EDIT 字符串搜索。

修复动作：给 CI 一个只读且明确失败的入口

下面保存为 scripts/check-gofmt.sh，从仓库根目录用 Bash 执行。它先落盘文件名单，再逐个检查；空集合有单独策略，路径中的空格通过 NUL 分隔处理。这里故意使用 -l 的非空结果判断，不依赖不同工具链中 -d 的退出码细节。

#!/usr/bin/env bash
# 仅检查格式，不写回源码；find 的错误也必须使任务失败
set -euo pipefail
task_list=$(mktemp)
trap 'rm -f "$task_list"' EXIT
find . \( -path './.git' -o -path './vendor' -o -path './generated' \) -prune -o \
  -type f -name '*.go' -print0 > "$task_list"

failed=0
seen=0
while IFS= read -r -d '' file; do
  seen=$((seen + 1))
  # 先处理 gofmt 本身的错误，再检查文件名输出
  if names=$(gofmt -l "$file"); then
    if [[ -n "$names" ]]; then
      printf '需要格式化：%s\n' "$file" >&2
      failed=1
    fi
  else
    printf '格式检查出错：%s\n' "$file" >&2
    failed=1
  fi
done &2
  exit 1
fi
exit "$failed"

这个规则只排除根目录下列出的三个路径及其子树，并不排除所有层级中同名目录。若生成目录是 internal/generated，须明确加入那个路径。它扫描实际存在的普通文件，包含未跟踪文件；不是“仅检查 Git 已提交文件”的脚本。

反向确认：保留需要修复的文件清单

发现问题后，在本地对明确的手写文件运行 gofmt -w，再用相同只读入口检查。生成文件若被独立纳入格式要求，应优先调整生成器或生成流程，避免反复手工修改会被覆盖的产物。

# 修复入口与 CI 检查入口分开；路径仅为示例
gofmt -w ./internal/example.go
# 从仓库根目录再次执行同一检查脚本
bash scripts/check-gofmt.sh
# 查看工作区改动，区分原有变更与本次修复
git diff --stat

最后一条命令不是“检查任务没有写入”的充分证明：未跟踪文件和原有脏工作区都需要另外理解。只读性首先来自脚本没有 -w 和其他源码写入操作。

落地清单与相关问题

• CI 固定 Go 工具链版本，避免本地与 CI 格式规则不同。
• 明确排除的是路径还是生成标记，不混用隐含假设。
• 只读入口不附带 -w，脚本捕获工具错误与非空 -l 输出。
• 为没有检查对象设定显式策略，维护目录规则时同步修改。

生成文件有标记，为什么仍被 gofmt 列出来？

标记是识别约定，不是 gofmt 的自动忽略参数。需要跳过时由文件选择器决定。

gofmt -l 没输出就一定成功吗？

还要看命令退出状态。语法或读取错误可能写入标准错误，不能仅判断标准输出为空。

为什么脚本不直接用 gofmt -d 的退出码？

显式检查 -l 输出能把“存在格式差异”这一规则写在脚本里；工具自身错误则由另一个分支处理。这样不需要把跨工具链的退出码约定当成隐含前提。

参考：参数文档 https://pkg.go.dev/cmd/gofmt，生成代码识别 https://pkg.go.dev/go/ast#IsGenerated，生成注释约定 https://go.dev/s/generatedcode。