如果你在 macOS 上跑git add或者git commit时，突然看到一行warning: CRLF will be replaced by LF，不用慌，这不是仓库坏了，而是 Git 正在对你工作区里的文本文件做一次行尾符（换行符）的标准化处理。我第一次撞见这条警告时，第一反应是去搜现成方案，搜到的答案东一句西一句，有的让你改core.autocrlf，有的让你删掉文件重新 add，照着操作完了，下次却照样冒出来。后来把换行符的机制彻底摸了一遍，才明白这个警告背后其实是一套相当清晰的设计判断。这篇文章就用具体的排查命令和修复步骤，把这条警告讲透，同时给出不同项目情况下的可落地配置，适合第一次碰到警告就懵掉的入门开发者，也适合在 Windows 和 macOS 混合团队里被换行符问题反复折腾的老手。
1. 警告的真相：行尾符差异与 Git 自动转换机制
1.1 先从一段真实的报错现场说起
假设你在 macOS 终端里敲下：
git add .结果类似这样的提示出现在眼前：
warning: CRLF will be replaced by LF in scripts/run.sh. The file will have its original line endings in your working directory关键词是CRLF、LF、will be replaced（将被替换）。此时文件本身并没有被破坏，工作区里的scripts/run.sh还是原来的样子，警告说的是：Git 把这个文件从工作区读入暂存区（index）时，正在把原来的CRLF行尾转成LF，也就是说，仓库里即将保存下来的文件用的是 LF，而你磁盘上的文件仍然是 CRLF。
有时候警告也可能是反向的：LF will be replaced by CRLF，这种情况常出现在 Windows 上，改动方向相反，但底层逻辑一模一样。很多人在这一步就开始乱改配置，其实最该做的反而是先搞清楚 Git 为什么要这么干，以及这个行为对你的项目是保护还是干扰。
1.2 为什么会有 CRLF 和 LF 两种行尾符
换行符本质上是一个“一行结束”的标记。Windows 体系下，回车换行被记作两个字符：回车符CR（\r）加换行符LF（\n），写作CRLF，也就是\r\n。而 macOS 和 Linux 家族只用换行符LF，也就是单个\n。这个差异是历史遗留：早期电传打字机里，“回车”是把打印头移回行首，“换行”是让纸卷走一行，两个动作分开控制，于是不同厂商在做成回车键时选择了不同的组合。Windows 选择了保守的\r\n，而 Unix 系选择了精简的\n。
这个问题在日常使用中不会暴露，因为现代编辑器都能同时识别两种换行符。但 Git 不是编辑器，它是一套内容追踪系统。它希望仓库里每个文件的内容是“确定且可比较的”，如果同一个文件在不同提交里一会儿是\r\n、一会儿是\n，Git 会把这当成整文件级别的改动——哪怕你只是加了一行代码，diff 也可能向你展示整个文件都变了。为了避免这种灾难，Git 引入了行尾符自动转换机制，试图让仓库内部保存一种统一的行尾风格。这个机制的控制开关就是core.autocrlf。
1.3 Git 的自动转换逻辑：core.autocrlf 到底是什么
core.autocrlf是 Git 的一个核心配置，取值有三档：true、input、false。它们的行为差异可以直接用一张表说清楚：
| 配置值 | 提交到仓库时（工作区→暂存区/仓库） | 检出到工作区时（仓库→工作区） | 典型使用环境 |
|---|---|---|---|
true | CRLF 转成 LF | LF 转回 CRLF | Windows |
input | CRLF 转成 LF | 不做转换，保持 LF | macOS / Linux |
false | 不转换 | 不转换 | 仓库本身已完全统一，或你明确不想让 Git 碰行尾 |
注意 macOS 和 Linux 的 Git 默认值通常是false或未设置。如果你在 macOS 上还能看到CRLF will be replaced by LF，大概率是两种情况：一是你之前手动设置过core.autocrlf为true或input；二是你的仓库里已经混入了 CRLF 文件，Git 在每次 add 时都会试图把它标准化成 LF，于是警告反复出现。
除此之外还有个隐藏角色叫core.safecrlf。它负责检查“转换是否可逆”，如果文件里既有 CRLF 又有 LF，Git 认为转换不可逆，于是当safecrlf为true时会直接拒绝提交，为warn时则会和你现在看到的一样，打出一条警告但仍然继续执行。所以别以为警告只是 Git 在刷存在感，它其实是在提醒你：这个文件的换行符是混用的，不是干净的 CRLF，也不是干净的 LF。真正动手处理之前，先理解这一层，后面才不会越改越乱。
2. 解决方案：三种典型场景的完整配置
2.1 场景一：纯 macOS/Linux 个人项目
如果你维护的仓库只会在 macOS 或 Linux 上使用，比如个人脚本项目、只部署到 Linux 服务器的代码，基本思路就是让仓库彻底走 LF，不让任何 CRLF 混进去。
第一步，把全局配置设为input，它的含义是：提交时把你工作区里的 CRLF 转成 LF 存进仓库，检出时保持 LF 原样，不做反向转换。命令是：
git config --global core.autocrlf input第二步是处理存量文件。光改配置并不能让已存在仓库里的 CRLF 文件消失。你需要先确认仓库里当前有没有 CRLF 文件，再决定是否做一次全量标准化。如果这是一个新仓库，直接开始写代码就好；如果仓库已经有历史，建议先跳到 2.3 的统一清理流程。
补充一个细节：如果你希望 Git 对“是否可逆转换”做更严格检查，可以把core.safecrlf调成true：
git config --global core.safecrlf true但说实话，日常开发中直接给true容易在混合行尾文件上卡死，个人项目我建议保持warn（默认值），让 Git 提示但不阻断即可。
2.2 场景二：Windows 与 macOS 混合开发团队
跨平台团队的情况要稍微复杂一些，因为 Windows 用户普遍习惯 CRLF，而 macOS 用户普遍希望 LF。如果大家各按各的习惯提交文件，仓库内部就会变得一团糟。
业界比较稳妥的组合方案是：
- 仓库内统一保存 LF：所有文本文件入库时都转换成 LF，这样仓库内容永远一致。
- Windows 开发者：设置
core.autocrlf true，检出时 Git 自动把 LF 转成 CRLF，编辑体验不改变；提交时再自动转回 LF。 - macOS/Linux 开发者：设置
core.autocrlf input，检出时保持 LF，提交时把可能出现的 CRLF 转回 LF。
命令分别为：
# Windows git config --global core.autocrlf true # macOS / Linux git config --global core.autocrlf input但仅靠core.autocrlf是不够的，因为这个配置依赖每个开发者的本地 Git 设置。如果新同事入职时没有按规范执行，仓库照样会被污染。我经历过好几次这种翻车：某位同事在 Windows 上把.gitattributes删了，或者他那台机器装的是老版本 Git，配置没生效，结果一个 commit 就让整个文件变成 CRLF。所以跨平台团队真正推荐的方案是：用仓库内的.gitattributes文件来声明换行符规则，让规则随仓库走，而不是随人走。
一个最小可用的.gitattributes文件长这样：
# 所有文本文件按 Git 自动检测处理，统一转换为 LF 入库 * text=auto # 明确要求脚本类文件使用 LF，防止在 Windows 上被检出为 CRLF *.sh text eol=lf # Windows 批处理文件保留 CRLF 更安全 *.bat text eol=crlf # 图片、二进制文件不做任何转换 *.png binary *.jpg binary *.ico binary这样配置之后，Windows 上凡是能被识别为文本的文件，检出时仍会按text=auto的规则变成本地换行符，但.sh这种明确标了eol=lf的文件会被强制保持 LF。项目到底用哪种规则，由仓库根目录这个文件统一说了算，比口头约定可靠得多。
2.3 场景三：存量仓库的历史换行符清理
如果你的仓库已经存在很久，里面既有 LF 文件又有 CRLF 文件，这时候需要的不是零敲碎打地改某个文件，而是做一次“全仓库重新标准化”。给仓库创建或更新.gitattributes之后，用下面这条命令让 Git 按新规则重新处理所有文件：
git add --renormalize .这条命令是 Git 2.16 以后才有的，作用是把索引里已有的文件全部按当前的属性和配置重新标准化一遍，效果相当于把所有文件重新走一次“提交转换”。执行后正常提交即可：
git commit -m "chore: normalize line endings to LF"这类提交一般会动到大量文件，diff 看起来声势浩大，但真正的内容变化只有换行符。建议选在项目不太繁忙的窗口操作，并且让团队成员在合并后再清理一次本地工作区，否则他们本地那些基于旧行尾的未提交修改会产生大量冲突。
3. 实操记录：从警告出现到仓库彻底干净
3.1 先动手排查当前状态
有次我接到一个某跨平台项目，仓库是从 Windows 开发环境迁移过来的，macOS 成员一 pull 就是满屏的CRLF will be replaced by LF。我当时的排查顺序很简单，先把当前状态摸清楚。
先看本机的autocrlf到底设置成了什么：
git config --global --get core.autocrlf如果什么都输出，说明没设置，等同于默认false。再看仓库内有没有.gitattributes：
ls -la .gitattributes然后用file命令检查警告里提到的那个文件的实际行尾符：
file scripts/run.sh输出里如果带with CRLF line terminators，就证实了这个文件在当前工作区里确实是 CRLF。如果想看得更细，可以直接查看文件里的不可见字符：
sed -n '1,3l' scripts/run.shl参数会把行尾的$和回车符\r都显示出来，一眼就能看出文件是不是干净的。
最后再看一眼仓库整体状态：
git config --list | grep -Ei 'crlf|safecrlf' git ls-files --eolgit ls-files --eol这个命令特别适合诊断换行符问题，它会分三列输出每个文件的换行符状态：i/表示 index（暂存区），w/表示 working tree（工作区），attr/表示属性。看到i/lf w/crlf这种组合，就说明仓库里是 LF、工作区里是 CRLF，正是警告产生的温床。
3.2 按步骤执行修复
当时的修复流程分为四步。
第一步，统一本机配置：
git config --global core.autocrlf input第二步，在仓库根目录写入.gitattributes，内容如下：
* text=auto *.sh text eol=lf *.js text eol=lf *.ts text eol=lf *.json text eol=lf *.md text eol=lf *.bat text eol=crlf *.cmd text eol=crlf第三步，执行重新标准化：
git add --renormalize .这条执行完以后，先不要急着 commit，停下来看一眼git status：
git status --short如果看到成片修改的文本文件，属于预期内。再用git diff --stat确认一下确实没有二进制文件被卷入：
git diff --cached --stat这一步特别关键，因为如果.gitattributes里把二进制文件误判成了文本，renormalize 会把这些二进制文件改得面目全非。确认没问题后再提交：
git commit -m "chore: normalize line endings to LF"第四步，也是容易被忽略的一步：同步给团队。提交推送到远端后，其他成员要先重新拉取，然后在各自本地执行一次让工作区文件与仓库同步的命令，避免旧行尾文件继续赖在本地：
git pull git add --renormalize . git checkout -- .不过这里要提醒，git checkout -- .会覆盖本地未提交的修改，执行前务必确认工作区干净，别给自己留下一地残局。
3.3 修复后的核验与效果验证
提交完成以后，不能只凭“没有警告了”就判断问题解决，还需要再做两次验证。
第一次验证，重新执行git ls-files --eol，这时的输出应该整齐得多，原本那些i/lf w/crlf的条目，如果工作区文件已同步为 LF，会变成i/lf w/lf。如果还有w/crlf，说明工作区里还有残留的 CRLF 文件，可能需要手动转换一次再提交。
第二次验证，随便改一个文件然后再 add：
echo "# test" >> README.md git add README.md如果终端没有再次弹出CRLF will be replaced by LF，说明标准化的确落到了实处。那一行列出修改差异的普通输出，才是真正让人放心的状态。
4. 常见问题与避坑清单（实战经验）
4.1 配置改了，警告却还在，怎么回事
这是后台收到最多的一类问题。很多人问我：我都把core.autocrlf改成input了，为什么git add还是警告？
原因一般有两种。第一种：仓库里那个文件本身就是混用换行符。比如一个文件 100 行，98 行是 LF，中间夹了 2 行 CRLF，Git 在 normalize 时发现无法把一个“本来就是混合行尾”的文件安全地整体转换成一种，就会触发safecrlf=warn的提示。解决办法是先让文件本身变得“干净”——用编辑器把它统一成 CRLF 或 LF，再让 Git 做转换。
第二种：你只是改了.gitattributes或者配置，但还没有让 Git 重新处理这个文件。换行符转换发生在文件被重新加入索引时，一个已在索引里的文件不会因为你改了配置就自动重来一遍。所以必须执行git add --renormalize .，让全仓库文件按新规则重新过一遍。这条命令很多人不知道，也是“改了配置但不生效”的最大元凶。
4.2 换行符混乱在团队协作中的典型翻车现场
我接手过的项目里，换行符问题最常见的爆发点是 merge。某次团队里一位 Windows 同事提交了一份代码，另一个 macOS 同事拉下来一 merge，发现一堆文件冲突，而且冲突显示为“整个文件都被修改”。点开 diff 一看，代码一个字没变，只是行尾从 LF 变成了 CRLF。这种冲突非常难手动处理，因为 Git 在比较时会因为行尾不同而认为两个版本互不相容。
还有更隐蔽的表现：某个文件在某些成员本地永远显示为“已修改”，即便他没有编辑过。跑git diff看不到任何差异，但git status就是提示文件被改动。这通常是因为本地 Git 认为文件需要做行尾转换，但转换后与索引里实际内容不一致，或者索引里本身就存了错误行尾。遇到这种诡异状态，先查看git ls-files --eol，再决定是否 renormalize，不要硬 commit。
事后复盘时我们总结了三条经验：第一，跨平台仓库必须有.gitattributes，这是硬规则，不是锦上添花；第二，团队里所有成员的core.autocrlf策略要写进项目文档；第三，换行符标准化要和功能改动分开提交。每次提交只做一件事，遇到问题时也更好定位和回滚。
4.3 不同场景的推荐配置速查表
| 项目情况 | 本机配置（macOS） | 本机配置（Windows） | 仓库文件 | 备注 |
|---|---|---|---|---|
| 单人在 macOS 维护个人仓库 | core.autocrlf input | — | 可留空 | 新仓库无需额外处理；存量仓库建议执行一次git add --renormalize . |
| Windows + macOS 混合团队 | core.autocrlf input | core.autocrlf true | 根目录添加.gitattributes，内容以text=auto为基础，再根据文件类型补充eol=lf/eol=crlf | 以.gitattributes为准，本机配置只是兜底 |
| 仓库里已有大量 CRLF 历史文件 | core.autocrlf input | 同上 | 先补.gitattributes，然后git add --renormalize .，再单独提交一次 | 提交信息建议写清楚是换行符标准化，方便 review |
| 纯 Linux 服务器部署脚本 | core.autocrlf input或false | — | 建议*.sh text eol=lf | 脚本类文件强制 LF，避免因换行符导致执行异常 |
最后再补充一个个人偏见：很多人喜欢偷懒不建.gitattributes，全凭core.autocrlf打天下。在个人项目里这样确实能撑住，但只要是团队项目，哪怕只有两个人，我都建议第一时间把.gitattributes提交进去。规则放在仓库里，机器会帮你盯住每一个成员的提交，这比在群里喊一万遍“大家注意换行符”都管用。我后来新开的每个仓库，第一笔 commit 都会顺手带上.gitattributes，从此之后基本没再被这条警告骚扰过。如果你也被这种看似不起眼、实际上特别消耗精力的换行符问题折磨过，照着上面的步骤整理一次，你的 Git 体验会舒服很多。
