CRLF 与 LF 换行符引发的全页假 Diff：原理、最小复现与 Git 配置防线

一、问题概述：跨平台协作中的全页假 Diff (False Diff) 痛点

Windows 操作系统默认使用回车换行符 CRLF（\r\n，ASCII 0x0D 0x0A），而 Linux 与 macOS 系统使用换行符 LF（\n，ASCII 0x0A）。在跨平台团队协作中，如果 IDE 自动将文件的换行符从 LF 转成了 CRLF，按行对比引擎在逐字节比较时会判定“每一行的末尾都被新增了一个 \r 字符”，从而将整个文件所有行标记为已修改。

二、最小复现：CRLF 与 LF 逐字节对比与假 Diff 复现代码

下面的对比示范了相同的可见文本在不同换行符下产生的假 Diff 差异：

/* 1. 源文件 A (Linux/macOS 格式, LF \n): */

const fileLF = "function hello() {\n  console.log('world');\n}";

/* 2. 目标文件 B (Windows 格式, CRLF \r\n): */
const fileCRLF = "function hello()\r\n  console.log('world');\r\n}";

/* 3. 逐行与字节对比断言 */
const linesA = fileLF.split("\n");
const linesB = fileCRLF.split("\n");

console.log("行数 A:", linesA.length, "行数 B:", linesB.length);
// linesB[0] 实际包含了不可见的 '\r' 字符 ("function hello()\r")
console.log("Line 0 物理长度 A:", linesA[0].length); // 18
console.log("Line 0 物理长度 B:", linesB[0].length); // 19 (多了 1 个 \r!)
console.log("字节比较匹配结果:", linesA[0] === linesB[0]); // false -> 产生全页假 Diff！

三、根因分析：回车符 \r 物理存在与 Git autocrlf 自动转换冲突

1. 回车符 `\r` (CR) 的物理实体：换行符不是不可见的“空气”，它在文件系统中有确定的字节码。\r\n 比 \n 每行多出 1 字节。Line Diff 算法将整行字符串当作对比 Token，尾部的 \r 会破坏字符串恒等性。2. `core.autocrlf` 自动转换冲突：Windows 上开启 core.autocrlf = true 时，Git 会在检出代码时自动将 LF 转为 CRLF，并在提交时转回 LF。如果某些编辑器覆盖了换行符但未触发转换，就会导致版本库内混入 CRLF。3. `.gitattributes` 缺失：没有在项目根目录强制约束换行符策略，导致不同成员的 IDE 按照各自本地 OS 默认值写入文件。

四、推荐方案：全栈行尾规范化、.gitattributes 与工具过滤

1. 根目录引入 .gitattributes：在项目根目录新建 .gitattributes 文件，配置 * text=auto eol=lf，强制 Git 提交与检出时统一转换为 LF 换行符。2. 修正已污染的版本库历史：运行 git add --renormalize . 强制重新规范化暂存区中的所有文件。3. 在线 Diff 工具忽略空白：在代码对比工具选项中勾选 Ignore Whitespace (忽略空白/换行符差异)，并在前端匹配前自动清洗 \r。

五、完整代码：自动规范化换行符与不可见 \r 字符诊断纯函数

下面的 TypeScript 代码示范如何诊断字符串中的 CRLF 换行符并进行无损行尾规范化。

interface LineEndingAnalysis {

  hasCRLF: boolean;
  hasLF: boolean;
  crlfCount: number;
  lfCount: number;
  normalizedText: string;
}

function analyzeAndNormalizeLineEndings(rawText: string): LineEndingAnalysis {
  // 1. 正则匹配 CRLF (\r\n) 与独立 LF (\n)
  const crlfMatches = rawText.match(/\r\n/g) || [];
  // 匹配非 CRLF 后面的单独 \n
  const lfMatches = rawText.match(/(?<!\r)\n/g) || [];

  // 2. 物理清洗：将所有 \r\n 统一规范化替换为标准的 \n
  const normalizedText = rawText.replace(/\r\n/g, "\n");

  return {
    hasCRLF: crlfMatches.length > 0,
    hasLF: lfMatches.length > 0,
    crlfCount: crlfMatches.length,
    lfCount: lfMatches.length,
    normalizedText
  };
}

const mixedText = "Header\r\nLine 1\r\nLine 2\nFooter";
const result = analyzeAndNormalizeLineEndings(mixedText);
console.log("CRLF 数量:", result.crlfCount, "规范化文本长度:", result.normalizedText.length);

六、常见错误方案

在 Windows 上全局配置 git config --global core.autocrlf false（导致提交含有 CRLF 的代码带崩 Linux CI/CD 构建）；手工逐行去删除 字符；忽略二进制文件（如图片或编译产物）被 .gitattributes 误当作文本文件转换导致损坏。

七、边界条件：二进制文件 (Binary Files) 的换行符保护

在配置 .gitattributes 时，切记排除二进制文件。对于图片 (*.png, *.jpg)、字体 (*.woff2) 或压缩包 (*.zip)，必须在 .gitattributes 中显式声明 *.png binary，否则 Git 会尝试转换二进制流中的 0x0D 0x0A 字节，导致文件物理损坏。

八、如何进行换行符校验与 CI/CD 自动化拦截

使用 .gitattributes 明确文本文件的 eol 策略，并在 Linter 中配置 linebreak-style；测试夹具应分别包含 LF、CRLF 与混合换行，断言规范化工具只修改允许的文件类型。

九、FAQ

问：为什么在 IDE 里看着完全一样的代码 git diff 会显示全红全绿？答：因为文件末尾换行符从 \n 变成了 \r\n，虽然视觉渲染看不到差异，但物理字节每行都多了 0x0D 回车符。

问：.gitattributes 中的 * text=auto eol=lf 是什么意思？答：text=auto 表示让 Git 自动检测文件是否为文本文件，eol=lf 表示检出到工作区和提交到版本库时统一强制使用 LF 换行符。

问：如何一次性修复整个仓库里的 CRLF 换行符？答：在设置好 .gitattributes 后，运行 git add --renormalize . 并在 commit 后 push 即可更新仓库记录。

十、总结

全页假 Diff 是跨平台协作中换行符失配的典型体现。通过根目录 .gitattributes 配置文件规范化与 Diff 工具忽略空白过滤，可彻底根治换行符引发的对比干扰。