格式化器和 AI 互相打架：保存就重排，diff 全是噪声怎么定纪律

2026-07-28

内容截至 2026-07。文中 git 命令在 Git 2.43 上验证过；blame.ignoreRevsFile 属于较晚加入的能力，较老版本可能不认，跑之前先 git --version 看一眼，并以官方文档为准。各编辑器与格式化工具的配置项名称、默认行为随版本变化，以官方最新说明为准。

**多数人把这个问题归错因了：你看到 diff 里两百行变更，第一反应是”AI 又乱改我代码”，但真正动手的往往不是 AI，而是你按下保存键那一刻触发的格式化器。**AI 只写了三行，格式化器顺手把整个文件按另一套规则重排了一遍。这两件事在 diff 里长得一模一样，但成因、验证方法和处置动作完全不同，混为一谈就会走上错误的排查路径——你去调 AI 的指令、去限制它的改动范围，结果噪声一点没少。

这篇只处理”格式与工具链导致的 diff 噪声”。如果你的问题是 AI 真的改动了本不该碰的文件和函数，那是改动范围失控，看 AI 改动范围失控怎么控；如果是 AI 补全把已有代码吃掉了半截、留下断裂的函数体，那是补全丢失，看 AI 代码补全丢失原有代码。本篇假设 AI 写的逻辑是对的、范围也是对的，麻烦纯粹出在”谁有权重排这些字符”上。

一、先分因：五种噪声长得像，成因完全不同

在动手改任何配置之前，先做一次判别。判别的核心手段只有一个：把空白变化剔掉，看剩下的实质改动有多少。

# 忽略所有空白差异后再看 diff
git diff -w

# 等价的长写法，团队沟通时更清楚
git diff --ignore-all-space

# 只看每个文件的增删行数，快速定位"整文件被标改动"的情况
git diff --stat

如果 git diff 显示两百行、git diff -w 只剩三行，噪声大概率来自缩进、对齐、空行这一类空白重排。

这里有个容易判反的地方：**行尾的 CR 也算空白，CRLF 与 LF 的整体翻转同样会被 -w 吃掉。**我在 Git 2.43 上拿一个三行文件试过，把它整体从 LF 改成 CRLF 之后，git diff --stat 报的是 3 增 3 删（等于全文件行数），而 git diff -w 输出为空。所以”-w 之后干净”这一条并不能直接推出”是缩进问题”：如果 --stat 的改动行数又接近整个文件的行数，优先查换行符，别一头扎进缩进配置里调半天。

如果 git diff 和 git diff -w 的行数差不多，那噪声就不是空白造成的，得往引号风格、尾逗号、import 排序这类非空白的排版差异上找。

下面这张表覆盖了实际工作里最常见的几类。按现象对号入座，先验证再动手：

现象	大概率成因	怎么验证	处置动作
改 3 行，diff 200 行，全是缩进/引号/空行位置变化	编辑器用的格式化规则和仓库里那份不一致	`git diff -w` 后实质改动只剩几行	统一到仓库配置文件；先做一次全量格式化并单独提交
只有 AI 新写的那一段被重排，其他地方没动	格式化只作用于改动范围，而 AI 输出的风格和项目不同	看 diff 覆盖区域是否恰好等于新增块	这是正常的，不用治；把风格约定写进仓库的规则文件让 AI 直接照着写
同一行反复横跳，保存一次变 A，再保存变回 B	两个格式化工具先后作用，规则互斥	临时停用其中一个，连续保存三次看是否稳定	全仓库只保留一个有权改写代码的格式化器，其余工具只报告不自动修
本地干净，CI 的格式检查却失败	工具版本不一致，或 CI 跑的是另一套配置	本地执行与 CI 完全相同的检查命令，再比对工具版本号	把格式化工具锁进依赖锁文件；本地和 CI 共用同一条命令
整个文件被标为改动，逐行看却没有可见差别	换行符（CRLF/LF）整体翻转	`git diff --stat` 的改动行数≈全文件行数，同时 `git diff -w` 几乎为空	用 `.gitattributes` 固定文本文件的换行符
只有第一行或最后一行被标为改动，内容看不出差别	文件开头的 BOM 头，或文件末尾少了一个换行	看 diff 的位置是不是只落在首行或末行	统一编码去掉 BOM；补齐文件末尾换行
改动溢出到本次任务无关的文件和函数	不是格式化问题，是改动范围失控	看被改文件是否与任务无关	转去处理范围控制，别在格式化上耗时间
diff 里出现半截函数、残留的冲突标记 `<<<<<<<`	补全或合并把原有代码吃掉了	直接看文件语法是否还成立	立刻回滚这次改动，按补全丢失的路子查

表的最后两行是提醒你及早跳出去：这两类不属于本篇范围，越早识别越省时间。

二、把”谁说了算”收敛成一个来源

诊断完成后，第一个动作永远是收敛权威来源。噪声的根源几乎都是同一件事：同一份代码，有两个以上的东西认为自己有权决定它长什么样。

收敛按这个顺序做，每一步做完都提交一次，别攒在一起：

**第一步，确认仓库里有且只有一份格式化配置。**很多老仓库同时躺着好几代配置：一份编辑器无关的通用配置、一份格式化工具自己的配置、还有 lint 工具里夹带的风格规则。它们各自定义了缩进宽度和引号风格，谁生效取决于加载顺序，本地和 CI 的加载顺序未必一致。把多余的删掉，只留一份，然后把这次删除单独提交，提交信息写清楚删了什么。

**第二步，让 lint 工具交出改写权。**格式化和 lint 是两件事：格式化只管排版，lint 管的是可能出错的写法。当 lint 工具也带自动修复功能、而修复规则和格式化器冲突时，就会出现保存一次变一个样的横跳。纪律很简单——只有格式化器可以改写文件，lint 工具只负责报告问题，自动修复功能在保存链路上关掉，需要时手动跑。

**第三步，锁版本。**格式化工具的小版本升级经常改变默认排版行为，一个人升级了本地依赖，他提交的所有文件就会带上一批别人看不懂的改动。把工具写进项目依赖并锁定版本，任何人执行的都是同一个二进制，而不是各自机器上全局安装的那个。全局安装的格式化工具是团队噪声的长期来源，值得专门清理一次。

**第四步，先做一次全量格式化，并把它变成一次孤立的提交。**这是最关键也最容易被跳过的一步。配置统一之后，仓库里的存量代码仍然是按旧规则排的，此后任何人碰到任何文件，都会顺手把那个文件重排一遍，噪声会持续泄漏好几个月。正确做法是选一个所有人都没有长期分支在跑的时间点，一次性格式化全仓库，单独提交，提交信息只写这一件事，绝不掺杂任何逻辑改动。

这次全量提交会污染代码溯源，所以紧接着要做第五步：

# 把纯格式化提交的哈希记进一个文件
echo "<全量格式化提交的完整哈希>" >> .git-blame-ignore-revs

# 让 git blame 默认跳过这些提交
git config blame.ignoreRevsFile .git-blame-ignore-revs

之后 git blame 追溯某一行的作者时会跳过这次重排，不会把所有代码的责任人都变成执行格式化的那个人。这里有个容易忽略的分工：**那个记哈希的文件要提交进仓库，让所有人共享；但 git config 那行写的是每个人克隆下来的本地配置，不会跟着仓库走。**所以要么在项目说明里写明这一步，要么塞进初始化脚本，否则只有配过的人看到的 blame 是干净的。至于网页端的 blame 视图，主流代码托管平台大多支持这个文件，具体行为各家不同，以你所用平台的说明为准。

三、把 AI 的改动和格式化在时间上错开

配置收敛只解决了”规则唯一”，还没解决”时机冲突”。AI 编程工具的典型工作方式是整块生成或整块替换代码，而保存时自动格式化是逐次触发的，两者叠在一起就会产生难以复盘的中间态。

我的做法是**在 AI 参与的编辑窗口里，把自动格式化从保存时机上摘出去，改挂到提交时机上。**理由是：保存是高频动作，AI 一轮对话里可能触发十几次保存，每次都重排一遍，你根本分不清哪一次改动是谁做的；提交是低频动作，且提交前的格式化只发生一次，diff 是干净的。

落地成本很低，在版本控制的提交钩子里跑格式化即可。下面这段存为 .git/hooks/pre-commit，存完记得给执行权限（chmod +x .git/hooks/pre-commit），注意 #!/bin/sh 必须是文件的第一行，前面不能垫任何注释：

#!/bin/sh
# 只格式化本次已暂存的文件，避免顺手重排无关代码
staged=$(git diff --cached --name-only --diff-filter=ACM)
[ -z "$staged" ] && exit 0

# 这里换成你项目锁定版本的格式化命令，对上面这批文件执行

# 格式化完成后重新暂存。这里改用 -z 让 git 输出以 NUL 分隔的原始文件名，
# 中文路径和带空格的路径都不会被转义成带引号的形式，交给 xargs -0 才不会错位。
git diff --cached --name-only -z --diff-filter=ACM | xargs -0 git add --

用 -z 这一笔不是洁癖。git 默认会把非 ASCII 的路径按八进制转义并加上双引号输出，直接把那种字符串喂给 git add，找不到文件、报错退出，而钩子失败通常表现为提交被拒绝，排查起来很费神。中文文件名在国内项目里并不罕见，一开始就走 -z 省事。

这个钩子只挑本次已暂存的文件来跑，不会去扫全仓库。但有一个必须知道的边界：如果某个文件是部分暂存的（一部分改动 git add 了、另一部分还留在工作区），最后那句重新暂存会把这个文件的全部改动一起收进本次提交。习惯用 git add -p 分块提交的人要么在钩子里跳过这类文件，要么接受这个行为，别等到提交完才发现多带了东西。

另外，本地钩子不会随仓库分发，新人克隆后默认没有，所以 CI 上的格式检查不能省——钩子是提效，CI 才是底线。

配套还有两条纪律：

一是每轮 AI 改动结束后立刻检查 diff，不要连着改五轮再看。AI 生成的代码越多，你越难分辨哪些行是它写的、哪些行是工具重排的。一轮一看，是几分钟的成本，攒到最后就是半小时的考古。

二是把风格约定直接写进仓库的规则文件，让 AI 一开始就按项目风格产出，而不是先随便写再靠格式化器纠正。缩进宽度、引号风格、命名习惯、import 组织方式这些写成明确的短句，比事后补救有效得多。规则文件怎么写才不啰嗦，可以参考项目规则文件怎么写才有用。

四、噪声已经进了提交，怎么把它拆出来

上面是预防，但你大概率是带着一个已经脏掉的分支来看这篇的。已经污染的改动，按这个顺序救：

**先判断还能不能重来。**如果这个分支只有你一个人在用、且没有推送过，最省事的办法就是回到分叉点重做一遍：先把配置收敛好，再把逻辑改动重新应用一次。听起来像倒退，但通常比手工挑拣快得多。

**分支已经共享了，就做拆分提交。**目标是把一个混合提交拆成”纯格式化”和”纯逻辑”两个：

# 保留改动、撤销提交，回到工作区
git reset --soft HEAD~1
# 取消暂存，逐块挑选
git reset
# 交互式挑选真正的逻辑改动，只暂存它们
git add -p
git commit -m "逻辑改动"
# 剩下的全是格式噪声，单独提交
# 用 -u 而不是 -A：只收已跟踪文件的剩余改动，不会把构建产物之类的未跟踪文件顺手带进来
git add -u
git commit -m "格式化"

git add -p 会逐块问你是否暂存，纯空白块直接跳过。这个操作会重写提交历史，共享分支上执行前务必和协作者打招呼。

**评审阶段的临时缓解。**如果拆分成本太高、又必须先让人评审，退而求其次的办法是让评审者用忽略空白的视图来看。多数代码托管平台的对比视图都提供忽略空白差异的开关，打开之后噪声会消失。这只是让人看得下去，噪声仍然在历史里，别当成解决。关于评审环节还能做哪些自动化，可以看 AI 代码评审工具怎么选。

遇到合并冲突全是格式差异时，先别硬解。两边如果只是排版不同，正确顺序是：选定一边的格式规则，把另一边整体重新格式化，再合并。手工去调和两套排版规则是纯粹的浪费。AI 参与解冲突时的边界和陷阱，另见 git 冲突让 AI 解决靠谱吗。

五、什么情况下别再折腾了

排查这类问题有明确的止损点，超过就该换路。

**信号一：你已经花了超过一小时在配置上，diff 噪声却没有量级下降。**说明你面对的不是配置问题，而是历史包袱——仓库里有多个子目录用不同风格写成，或者存在大量生成代码被纳入了版本控制。这时候正确动作不是继续调，而是缩小格式化的作用域：把生成目录、第三方引入的代码、遗留模块加进忽略列表，只保证新代码干净。老代码等到有人真正重写它时再顺手规范。

**信号二：格式化后代码行为变了。**这是硬止损线，立刻回滚。排版本身不应改变语义，一旦出现测试失败或行为变化，说明触发了工具的边界情况——比如模板字符串里的空白被处理、依赖缩进的语言里作用域被改、或者某个宏和注释指令的位置被移动。别去修格式化器，直接把这个文件或这个目录排除在自动格式化之外，并在配置里写清原因。

**信号三：全量格式化的时机撞上了正在跑的长期分支。**如果团队里有人手上有一个开了两周还没合的大分支，此时做全量格式化，他合并回来时几乎必然是一场灾难。这时候的判断是推迟：等那个分支合进去，或者把全量格式化拆成按目录分批做，每批挑一个当前无人改动的目录。工程判断上，等三天远比多花三天解冲突划算。

**信号四：你开始考虑写脚本”智能识别”哪些改动是噪声。**这是典型的越陷越深。这类脚本永远做不到可靠，因为空白和语义的边界本来就是模糊的。把精力放回收敛配置上，那才是根治。

**回滚点怎么留。**动配置之前先在干净状态打一个标记，任何一步失败都能一键回到起点：

git tag before-format-cleanup
# 需要放弃时
git reset --hard before-format-cleanup

--hard 会丢弃工作区未提交的改动，执行前确认没有值得保留的东西。

六、避坑清单：为什么会踩，以及怎么避

**坑一：把全量格式化和一次功能改动放进同一个提交。**会踩是因为当时觉得”顺手一起提了省事”，而且本地看起来一切正常。代价在评审和排障时才显现：评审者无法从两百行里找出那三行逻辑，出问题时二分定位也会被这个巨型提交卡住。避法是硬性规定——格式化提交里不允许出现任何逻辑改动，提交前用 git diff --cached -w 自查一遍。但这条自查是单向的，用的时候得清楚它的边界：输出为空，说明这次暂存的内容只有空白差异，可以放心提；输出不为空，却不等于不纯净，因为格式化器往往还会动引号风格、尾逗号、import 顺序这些非空白排版，它们本来就逃不过 -w。此时正确动作是把剩下的差异块逐个过一遍，确认每一块都只改了写法而没改行为，而不是看到有输出就推倒重来。

**坑二：只在本地配了钩子，以为团队都受约束。**会踩是因为钩子在本地生效，你的分支一直干净，直到某个同事提交了一堆重排。根因是钩子不随仓库分发。避法是把格式检查放进 CI 作为必过项，本地钩子只当提效手段，永远不作为唯一防线。

**坑三：用全局安装的格式化工具。**会踩是因为装的时候图省事，而且当时确实能用。半年后你的版本升了、同事的没升，同一个文件在两台机器上排出两种样子，谁提交谁”污染”。避法是把工具作为项目依赖锁定版本，命令统一走项目脚本，不依赖任何全局安装。

**坑四：忽略换行符和编码。**会踩通常发生在跨平台协作的团队里，Windows 与 Linux/macOS 默认换行符不同，某个人一提交就整文件飘红。避法是在仓库根目录用 .gitattributes 明确声明文本文件的换行符规则，让转换由版本控制统一处理，而不是靠每个人自己配置客户端。文件编码同理，仓库里只允许一种编码，带 BOM 头的文件在提交前清掉。

**坑五：让 AI 去”顺便把格式统一一下”。**会踩是因为这句话说起来很自然，AI 也确实会照做。问题是它是逐字符重写而非调用格式化器，结果既不完全符合任何一套规则，还可能在重写过程中丢失注释或改动逻辑。避法是分工明确——排版交给确定性工具，AI 只负责逻辑。需要统一风格时，让 AI 帮你写配置文件，而不是让它直接改代码。

**坑六：为了消除噪声而关掉所有格式化。**会踩是因为短期确实清净了。但拖上几个月之后风格会彻底分裂，那时再想统一，要动的文件、要解的冲突、要惊动的分支都比现在多得多。避法是承认”排版必须由工具统一”这个前提不可动摇，能调整的只是触发时机和作用范围。

**坑七：默认海外 AI 编程工具的默认风格就是团队标准。**会踩是因为这些工具的产出风格偏向英文社区的主流约定，和很多国内团队的既有规范并不一致。另外需要说明的是，海外 AI 工具的官方服务对中国大陆存在区域限制、不支持直接使用，市面上有第三方中转，我不背书也不推荐具体渠道，选型时把可用性风险算进去。风格上的正确做法是以仓库配置为准，让工具适应项目，而不是反过来。

收束：提交前的六条自检

格式化器和 AI 打架，本质是权责不清：两个主体都在改同一份字符，却没人规定顺序和边界。收敛配置解决”规则唯一”，错开时机解决”顺序清晰”，拆分提交解决”责任可追”。三件事做完，这类问题基本不会再复发。

提交前过一遍这六条：

git diff -w 的输出，是不是就是你真正想改的那些行？
这次提交里，纯格式改动和逻辑改动是不是已经分开了？
格式化工具的版本，是锁在项目依赖里还是装在全局？
本地跑的检查命令，和 CI 上那条是不是同一条？
有没有看不出差别却被标改动的文件？整文件飘红先查换行符，只有首行或末行飘红就查 BOM 和末尾换行。
如果 diff 里出现了任务范围之外的文件，先停手——那已经不是格式化的问题了。