说实话，这些年带跨平台项目，我见过最普遍、也最容易被低估的问题，就是Git行尾符。一个Windows同事早上提交了两个文件，macOS的同事pull下来，终端里刷出几十行同类warning：“CRLF will be replaced by LF in assets/xxx.png”。再往后，有人git diff看到一整片一整片的红色，有人明明没改文件却被git status提示modified，还有人部署到Linux服务器后脚本直接报bad interpreter。这些看着毫不相关的怪事，八成都是同一个源头：CRLF与LF的跨平台之争。
这篇文章想系统地把这件事讲清楚，包括行尾符的历史和原理、Git三个核心配置到底怎么选、为什么我强烈建议用.gitattributes把规则固化进仓库，以及一支Unity跨平台团队从告警刷屏到彻底安静的完整实操记录。适合正在被行尾符折磨的新人，也适合想给团队定规矩的负责人。
1. 行尾符到底是什么？为什么一场“回车”能引发跨平台噩梦
1.1 \r与\n：从打字机时代继承下来的两个字符
要理解CRLF和LF，先要回到一个很古老的场景：电传打字机。那时候“回车”（Carriage Return，\r，ASCII码0x0D）和“换行”（Line Feed，\n，ASCII码0x0A）是两个独立的机械动作。回车是让打印头回到行首，换行是让纸张往上走一行。现代系统沿用了这两个字符，但继承方式完全不同。
Unix和Linux从一开始就只保留了一个换行符LF，也就是0x0A。Windows走的是另一条路，它继承了MS-DOS，MS-DOS又继承了CP/M，CP/M则把打字机时代的两个动作原封不动地保留成了两个字符，也就是CRLF（0x0D 0x0A）。早期Mac系统还单独用过CR（\r）做行尾，后来macOS转向Unix内核后才改用LF。
这就造成了最直接的冲突：同一个文本文件，在Windows记事本里看，换行是两个字符；在Unix工具里看，换行是一个字符。两边的工具链对“一行结束”的定义都不一样。你可以把LF理解成“按一下发送键”，把CRLF理解成“先回车再发送”。Windows用户习惯了两个动作的合成效果，Unix用户只认那个单个动作。
1.2 Git为什么非要管这件事
Git本质上是一个字节级别的版本控制系统。它做diff、做merge、做patch都以“行”为基本单位，而行尾符直接决定了一行在什么时候结束。假如仓库里同一个文本文件有时存CRLF、有时存LF，Git看到的就不是“同一行的结尾有点差异”，而是“这文件每一行都不见了、又冒出了新的一行”。
举个例子：你在Windows上把文件保存成CRLF，提交入库；同事在macOS上pull下来，他的工具链默认按LF解析，于是每行结尾都多出一个看不见的\r字符。他用编辑器一打开，感觉整份文件都被改过了；他再保存一次，Git又认为整份文件都被改过了。最糟糕的情况发生在脚本和配置文件上：Linux的Shell遇到CRLF会把\r当成命令参数的一部分，于是报出“/bin/bash^M: bad interpreter”这种让人摸不着头脑的错误。
所以Git提出了一个折中方案：仓库里统一存放LF格式，工作区里Windows用户看到CRLF、macOS和Linux用户看到LF。换句话说，提交的时候自动把CRLF翻译成LF，检出的时候再按当前平台自动翻译回去。这就是“行尾符转换”的初衷。想法很好，但问题在于：Git给了很多开关，每个开关还受平台和安装选项影响，大家配得不一致，反而制造出更多的混乱。
2. 三个核心配置参数，先弄清它们再动手
2.1 core.autocrlf的三档取值，分别解决什么场景
Git处理行尾符的核心开关是core.autocrlf，它有三个值：true、false、input。理解它其实只需要记住两个时机：提交入库时做什么、检出到工作区时做什么。
| core.autocrlf配置 | 提交时（入库） | 检出时（工作区） | 典型适用场景 |
|---|---|---|---|
| true | CRLF转LF | LF转CRLF | Windows为主，或团队所有人都在Windows |
| false | 原样存储 | 原样检出 | 仓库只在单一平台使用，不推荐跨平台团队 |
| input | CRLF转LF | 不做转换，保持LF | macOS/Linux为主，Windows成员也能配合 |
Windows版Git安装时有一个很经典的选项：“Checkout Windows-style, commit Unix-style line endings”，选这个对应的就是autocrlf=true；“Checkout as-is, commit Unix-style line endings”对应的是autocrlf=input；“Checkout as-is, commit as-is”对应的是false。很多新人安装时一路Next，根本不知道自己选了哪档，等出了问题才回头查。
对于纯Windows团队，autocrlf=true是最省心的：大家编辑、保存、提交都用CRLF，Git在入库时统一转成LF，各自的工作区仍然是CRLF，谁也感知不到转换过程。对于macOS和Linux用户，我一般建议直接设成input或者false，让工作区保持LF就好。真正出问题的是跨平台团队：Windows成员用true，macOS成员用false，同一个文件在两边入库后的内容就不一样了，所有人开始互相看到莫名其妙的diff。
这里还有一个配套参数core.eol，它用来显式指定检出时文本文件应该用的行尾符，可选lf、crlf、native。当core.autocrlf不是false时，core.eol基本要让位给autocrlf的语义，所以日常不需要单独设置。我的经验是：先把autocrlf这一个参数理解透，再谈其他的。
2.2 core.safecrlf：宁可报错，也别让混合行尾进入仓库
除了autocrlf，另一个被低估的参数是core.safecrlf。它解决的是“行尾转换会不会产生不可逆结果”的问题。假如一个文件里既有CRLF又有LF，Git入库时统一转成LF，之后检出时想再还原成CRLF，就没法保证还原出原始状态了，因为原始文件里两种行尾的位置已经丢失。
core.safecrlf有三个取值：false是默认值，不做检查；warn表示发现这种情况时输出警告，但允许提交；true表示发现这种情况直接拒绝提交。我建议跨平台团队至少设置成warn，如果项目已经规范干净，可以进一步设成true。
但这里有个坑要注意：safecrlf=true对某些工具生成的文件会特别严格，比如Unity在个别场景下生成的YAML文件会混合多种行尾，第一次提交时会直接被Git拒绝。我踩过这个坑后，做法是：先把safecrlf设成warn跑两周，一边提交一边观察警告集中出现在哪些文件上，逐个清理干净后，再切到true。不要一上来就上最严格档位，否则新成员入职第一天提交就被拒，体验很糟。
2.3 为什么只设置本地Git开关终究不够
聊到这里，很多人会问：那我只要让团队成员统一设autocrlf=true不就行了？答案是不够。原因有三个。
第一，本地配置不进仓库。你没法要求每个新同事都记得修改自己的全局配置，更没法保证他们装的Git版本、用的GUI工具不会悄悄改掉这些设置。第二，很多GUI工具和编辑器的行为会绕过Git配置。比如有人在Windows上用VS Code把文件保存成了LF，另一个人用Visual Studio又保存成了CRLF，Git的autocrlf只处理“提交”那一下，不同的工作区文件状态仍然会带来额外的diff噪音。第三，Git仓库里已经存在的错误行尾不会因为本地配置改变而自动修复，需要一次显式的规范化。
所以，真正靠谱的做法是把规则写进仓库本身，让每个clone这个仓库的人都自动遵守。这就是.gitattributes。
3. 终极解法：用.gitattributes把行尾符规则固化进仓库
3.1 一份可以直接抄走的.gitattributes模板（通用+Unity专项）
.gitattributes是仓库根目录下的一个普通文本文件，它的每一行由两部分组成：一个文件匹配模式，以及一组属性。Git在处理文件时会读取这些属性，决定要不要做行尾转换、要不要做diff、是不是二进制文件。
最核心的属性有三个：text表示“这是文本文件，应该做LF规范化”；-text表示“不要做任何文本规范化”；binary是“-text -diff”的简写，既不做行尾转换，也不做文本diff。在此基础上可以用eol=lf或eol=crlf来强制某个匹配模式的文件在检出时使用指定行尾。
下面这份模板是我在Unity跨平台项目里使用的版本，如果你的是纯代码项目，把Unity相关扩展名删掉即可：
# 兜底规则：能被检测为文本的，一律做LF规范化 * text=auto # 脚本与配置文件：明确要求LF，避免Shell/CI环境踩坑 *.cs text eol=lf *.sh text eol=lf *.json text eol=lf *.md text eol=lf *.txt text eol=lf *.yml text eol=lf *.yaml text eol=lf *.xml text eol=lf # Unity文本资源：YAML格式，入库统一LF，diff清晰 *.unity text eol=lf *.prefab text eol=lf *.anim text eol=lf *.controller text eol=lf *.mat text eol=lf *.meta text eol=lf # 二进制资源：彻底隔离，不做任何行尾转换 *.png binary *.jpg binary *.jpeg binary *.psd binary *.tga binary *.tif binary *.wav binary *.mp3 binary *.mp4 binary *.fbx binary *.dll binary *.exe binary *.unity3d binary说明几个细节。第一，第一行的* text=auto是兜底规则：凡是Git能识别为文本的文件都按“入库LF”处理，其他没匹配到后面具体规则的文件也不会漏掉。第二，后写的具体规则会覆盖前面的兜底规则，所以*.png binary这种规则一定要放在* text=auto之后，否则会被兜底规则抢走。第三，eol=lf表示检出时强制LF，这意味着在Windows上checkout出来的这些文件也会是LF格式，对于那些希望在Windows上也用LF的团队来说非常合适。
关于.asset这类文件，我要特别提醒：Unity默认序列化文本时.asset是YAML文本，但如果你或同事在Project Settings里开启了Force Binary，.asset就会变成二进制。所以我不会在通用模板里写死*.asset的规则，而是建议你先在某个.asset文件上运行git check-attr text -- <file>，再决定要不要单独加规则。
3.2 存量仓库如何批量纠正：git add --renormalize的完整流程
如果你的仓库已经跑偏很久，里面堆满了CRLF入库的文本文件，这时候光是放下.gitattributes还不够，因为Git只会按新规则处理“接下来提交的文件”，历史入库的blob不会自动更新。你需要对Git索引做一次“重规范化”。
Git 2.16及以上版本提供了一个专门命令：git add --renormalize .。它的作用是用当前仓库的attributes规则，重新计算所有已跟踪文件的入库内容，但不会修改你工作区里的实际文件。也就是说，你本地没提交的修改会完好无损地留在工作区。
完整流程是这样：
# 1. 确认Git版本足够新 git --version # 2. 写好.gitattributes放到仓库根目录 # 3. 先提交.gitattributes本身 git add .gitattributes git commit -m "chore: add line ending rules" # 4. 用新规则重新计算所有已跟踪文件 git add --renormalize . # 5. 查看这次规范化影响了哪些文件 git status # 6. 确认无误后提交 git commit -m "chore: normalize line endings for cross-platform"执行完第4步后，git status里通常会出现两类文件：一类是本来就没遵守LF规范的文本文件，它们会显示为modified；另一类是之前被误判为文本的二进制文件，它们可能也会跟着变化。你需要对照.gitattributes逐一确认，尤其注意那些二进制文件：如果git diff后看到大片乱码，说明文件进了错误的状态，赶紧在attributes里补上对应的binary规则，重新执行renormalize。
如果Git版本太老，没有--renormalize，备选方案是git rm --cached -r .然后再git add .，但这个方案会对所有文件重新计算，而且和Git LFS等扩展配合时容易出问题，我不推荐。
3.3 文本与二进制的边界：为什么一个png会被Git当成文本
回到文章开头那个告警：“CRLF will be replaced by LF in assets/1787552212360.png”。png明明是二进制图片，为什么Git会对着它做行尾转换？答案藏在Git对text=auto的启发式检测里。
当某个文件没有显式属性时，Git会读取文件内容的前8000个字节左右，判断其中是否包含NUL字节（0x00）。如果检测到NUL，就认定这是二进制；如果没检测到，就可能把它当作文本处理。PNG、JPG这类格式的文件头和部分数据段完全可能在前8000字节里不出现NUL，尤其是体积很小的简单图片，于是就被Git误判成了文本。一旦它被当成文本，git就会尝试做CRLF/LF转换，于是那条warning就出来了。
更隐蔽的是另一种情况：文件本身是二进制，但在历史提交中已经被当成了文本并完成了行尾转换，图片数据里个别字节变成了0x0D 0x0A。这时候图片可能还能打开，但做diff时会整片乱码，某些校验严格的场景甚至会直接报“文件损坏”。这也是我在模板里给所有图片格式显式标注binary的原因：binary规则不只是为了消除warning，更是为了阻止Git用文本逻辑去“修复”二进制文件。
遇到png的CRLF告警时，第一反应不应该是去修改这个png本身，而是去仓库根目录检查.gitattributes里有没有覆盖这个扩展名。填上*.png binary，再跑一轮renormalize，告警自然会消失。
4. 实战复盘：一个Unity项目从刷屏告警到彻底安静
4.1 现场还原：assets/1787552212360.png的告警是怎么来的
有次我接手一个Unity跨平台项目，Windows开发机和macOS开发机混合使用。某天美术同事把一张新导出的图标丢进assets目录，文件名是一个13位时间戳，也就是1787552212360.png这种风格，一看就是引擎或工具批量生成的。他提交时，Git突然刷出一条warning：CRLF will be replaced by LF in assets/1787552212360.png。
当时项目里的真实情况是：仓库没有任何.gitattributes；有的成员安装Git时选了autocrlf=true，有的选了input，还有一位老兄一直是false；仓库里已经存在部分CRLF入库的文本文件，同时一些很小的png因为启发式判断没检测出NUL，被错误的当成文本纳入了行尾转换流程。其他人pull之后不是看到git diff整片乱码，就是发现git status永远显示某个文件是modified。问题的根源早就不是某个png，而是整个仓库的行尾规则完全失控。
4.2 操作实录：从改配置到提交，一步步做完
我处理这个项目时，按下面这个顺序操作，每一步的命令都可以直接参考。
第一步，先摸清现状。我建议每个仓库在动手前都跑一遍这几个命令：
# 查看当前autocrlf配置来源 git config --show-origin --get core.autocrlf # 查看特定文件的入库行尾状态，i=index，w=worktree，attr=属性 git ls-files --eol assets/1787552212360.png # 查看这个文件被attributes判定成了什么类型 git check-attr text -- assets/1787552212360.png如果git ls-files --eol输出里那个png文件显示类似i/crlf w/crlf，说明这个png在索引里都已经带了CRLF；如果git check-attr显示text: auto，说明Git把它当成了文本。这两条信息合在一起，就完全解释了告警的来源。
第二步，写好.gitattributes并提交。我直接把3.1节的模板放进去，然后执行git add .gitattributes和一次单独的commit。这一步是为了让规则先进入仓库，再让其他成员pull时能同步看到。
第三步，执行规范化：
git add --renormalize . git status这次git status里出现了几十个文件，包括之前被误判的png和被CRLF污染的*.unity、*.cs、*.meta文件。检查下来没有意外，我就直接提交了。提交后再次运行：
git ls-files --eol assets/1787552212360.png这次输出里png已经变成i/lf w/lf attr/binary（或类似状态，取决于工作区实际内容），而*.unity文件显示为i/lf w/lf attr/text eol=lf，说明索引里已经是LF，工作区也是LF，规则生效了。Windows同事pull后，他们的工作区里文本文件会根据autocrlf重新以CRLF检出，但因为仓库里已经是LF，不会再刷warning。
一个值得注意的操作细节：renormalize只更新索引，不动工作区文件，所以理论上不需要stash。但我仍然建议在跑规范化的那个下午，先把手上未提交的改动放到一边，因为后面检查git status时如果混入你自己的业务改动，会很难确认哪些是行尾规范化带来的变化。更稳妥的做法是先把未提交内容提交或stash，规范化完成后再恢复。
4.3 换行符引发的诡异Bug：脚本的“看不见的字符”
仓库安静下来之后，团队又遇到了一次典型的换行符Bug，这次跟Unity无关，但很有代表性。
项目里有个build.sh，在Windows上编辑保存后提交到了仓库。macOS同事本地跑没问题，但CI跑起来直接报错：/bin/bash^M: bad interpreter: No such file or directory。这个^M就是CR里的\r字符在终端里的显示形式。Linux的Shell把build.sh\r当成了解释器路径，自然找不到。
排查方法很简单：在Linux或macOS上执行file build.sh，输出会明确显示with CRLF line terminators。修复方法是用dos2unix build.sh，或者直接在编辑器右下角把行尾改成LF，然后重新提交。重点是把规则写进.gitattributes，也就是模板里的*.sh text eol=lf，这样以后Windows上保存的.sh文件入库时也会被强制转成LF。
同样的坑还出现在Makefile上，CRLF会让Make报出诡异的missing separator错误，看起来像是语法问题，实际只是行尾问题。Python脚本、Node.js的bin脚本、npm包里的shell脚本都是重灾区。只要规则里把这些文件统一成LF，这些Bug可以一劳永逸地避免。
4.4 跨平台开发团队的几条隐性约定
经历了那次规范化之后，我给团队定了几条简单的约定，虽然不是强制工具，但效果很好。
仓库层面，.gitattributes必须存在，并且是每次代码评审的必看项。凡是新增了一种文件类型，都要顺手确认它在attributes里属于文本还是二进制。Windows成员保持autocrlf=true，macOS/Linux成员保持autocrlf=input或false，核心是“仓库永远LF”。新成员入职后，第一件事不是配IDE，而是确认Git安装选项和core.autocrlf，再clone一遍项目。
编辑器层面，VS Code看右下角，Visual Studio用“文件 > 高级保存选项”，JetBrains系列看右下角行尾图标。团队约定：源代码文件不管在什么平台，都统一以LF保存。这样即使某个人临时绕过Git规则，也不会把CRLF带进工作区。
CI层面，如果项目足够正规，可以在流水线里加一个简单的行尾检测步骤：
grep -rl $'\r' --include='*.cs' --include='*.sh' --include='*.unity' . && exit 1 || echo "line endings OK"这条命令会检测指定类型文件中是否出现CR，一旦出现就让CI失败。它能确保规范化成果不被某次临时提交悄悄破坏。
5. 常见问题速查：这些坑基本都踩过
5.1 问题现象与解决对照表
我把这些年踩过的行尾符问题整理成了一张速查表，遇到对应现象可以直接按里面的思路处理。
| 现象 | 根本原因 | 处理方式 |
|---|---|---|
| git diff显示整个文件全红 | 文件所有行尾整体被替换 | 用git diff --ignore-space-at-eol临时验看；用.gitattributes+renormalize统一规则 |
| git status一直显示某文件modified，但内容没变化 | index与工作区行尾不一致，且attributes缺失 | git add --renormalize <file>，并补上对应的attributes规则 |
| 提交时提示“CRLF will be replaced by LF” | autocrlf=true且该文件被判定为文本 | 判断该文件类型：文本就让它转换，二进制就在attributes里加binary |
Linux报bad interpreter或bash\r错误 | 脚本文件被CRLF污染 | dos2unix修复，attributes里为*.sh加eol=lf |
| Makefile报missing separator | Makefile被CRLF污染 | 改成LF，attributes里加*.mk text eol=lf |
| 二进制文件diff显示成乱码文本 | 被text=auto误判为文本 | attributes里标记binary，并renormalize |
| 终端查看文件到处是^M | 文件是CRLF，但工具按LF显示 | 确认是否需清理；需清理时用dos2unix |
| stash apply/merge出现无关冲突 | 两个分支的行尾状态不一致 | 统一attributes后重新合并，必要时重做规范化 |
5.2 快速自查技巧：如何一眼看出是不是行尾符问题
判断一个诡异问题到底是不是行尾符引起的，我有几个最快的手段。
git ls-files --eol <file>是最直接的：它输出文件在索引（i/）、工作区（w/）和属性（attr/）三个维度上的行尾状态。例如看到i/lf w/crlf attr/text eol=lf，就知道索引已经LF化了，问题只出在工作区还没同步。看到i/crlf就知道索引里本身就不干净。
git check-attr text -- <file>用来确认attributes规则对这个文件做了什么判断，输出text: auto表示走自动检测，text: set表示显式文本，binary表示纯二进制。
在Linux/macOS上，file <file>会直接告诉你文件是否带CRLF。在Windows上则可以用VS Code打开后看右下角，或者用Notepad++的“视图 > 显示符号 > 显示行尾”。如果你想检查整个工作区有没有混入CRLF，可以用一条grep命令扫指定类型的文件，这也是我在CI里用的方法。
命令行还有一个小技巧：git diff --ignore-space-at-eol可以忽略行尾差异来做diff，如果执行后文件内容瞬间“正常”了，那基本可以断定问题就在行尾符。
我个人这两年跨平台项目的体会是：行尾符问题不存在“忍一忍就好”，它越早定规则成本越低。我建议每个仓库第一条提交就顺手带上.gitattributes；如果项目已经混乱，挑一个改动少的周五下午，按4.2节那套流程做一次规范化。最后分享一个小技巧：调试时如果怀疑某个文件被行尾符搞了，先跑git ls-files --eol <file>，三列状态顶你翻十篇文档。
