如何配置 Git 换行符自动转换避免跨平台冲突

推荐团队项目使用 .gitattributes 文件统一声明换行策略，个人开发可根据操作系统设置 core.autocrlf。Windows 用户设为 true，Linux/macOS 用户设为 input，注意二进制文件必须标记为 binary 避免损坏。

先说结论：跨平台协作必须通过 .gitattributes 强制统一换行符，个人单系统开发可依赖 core.autocrlf 自动转换。

适合：混合操作系统团队、含脚本与二进制文件的项目、CI/CD 流水线环境
先准备：检查当前 Git 配置 git config `--global` core.autocrlf 及编辑器换行符设置
验收：确认 git status 无虚假修改警告且 CI 构建不报换行符错误

命令速用版

根据操作系统执行对应命令，设置后无需重启终端立即生效。

Windows 系统：

git config `--global` core.autocrlf true

Linux/macOS 系统：

git config `--global` core.autocrlf input

禁用自动转换（高级场景）：

git config `--global` core.autocrlf false

为什么会这样

换行符冲突本质是操作系统历史标准不一致导致 Git 误判文件内容变更。Windows 继承 DOS 传统使用 CRLF（\r\n）作为行结束标志，而 Unix/Linux/macOS 使用 LF（\n）。Git 默认开启 core.autocrlf 但不同系统默认行为不一致，Windows 默认 true，Mac/Linux 默认 input，导致跨平台拉取代码时 Git 机械转换换行符，触发 warning: LF will be replaced by CRLF 警告或 git status 显示大量 modified 但 diff 无内容变化。

分步处理

按顺序执行以下步骤，确保配置优先级正确且历史污染被清除。

步骤 1：设置全局配置

打开 Git Bash 或终端，执行上述命令速用版中的配置。执行后务必验证：git config `--global` core.autocrlf 输出应是你设的值，而不是空或 unset。

步骤 2：创建 .gitattributes 文件（推荐团队）

在项目根目录新建文本文件，命名为 .gitattributes（注意开头为英文点号）。写入以下内容：

* text=auto eol=lf
*.sh text eol=lf
*.bat text eol=crlf
*.png binary
*.jpg binary

执行命令使新规则立即生效：git add `--renormalize` .。

步骤 3：修复已污染仓库

如果已有历史提交混入 CRLF 导致状态异常，运行 git rm `--cached` -r . 然后 git reset `--hard` 可重置工作区，注意先备份未提交改动。

怎么验证是否生效

通过以下命令和现象确认配置已起作用。

检查配置值：

git config `--get` core.autocrlf

返回当前配置值：input、true 或 false。

检查文件状态：

执行 git status，不应出现大量因换行符导致的 modified 文件。执行 git diff 不应看到整行变更仅因换行符差异。

检查 CI/CD：

观察流水线构建日志，不再提示 invalid byte sequence 或 ^M 残留错误。

常见坑

以下场景容易导致配置失效或文件损坏，操作时需謹慎。

二进制文件被当作文本处理：

图片、压缩包等二进制文件一旦被当作文本处理，\r\n 插入进去就等于损坏。必须在 .gitattributes 中明确标记 *.png binary 等规则。

.gitattributes 优先级高于全局配置：

很多人根本没配 .gitattributes，导致全局配置被覆盖。若项目根目录存在 .gitattributes 文件且写了 * text=auto eol=lf，实际以 .gitattributes 为准。

编辑器设置冲突：

刚 clone 一个历史用 input 或 false 配置的仓库，但本地编辑器（如 VS Code、Notepad++）默认保存为 CRLF，会导致 Git 发现工作区文件用了 CRLF 而准备转换。建议关闭编辑器“自动检测换行符”或设为 LF。

常见问题

为什么设置了 autocrlf 还有 LF will be replaced by CRLF 警告

这类警告本质是 Git 发现工作区文件用了 CRLF，而它准备按当前 core.autocrlf 规则转成 LF 存入暂存区。常见原因是刚 clone 仓库但本地编辑器默认保存为 CRLF，或项目根目录存在 .gitattributes 文件且规则冲突。

团队混用 Windows 和 Mac 应该怎么配

唯一可靠解法是用 .gitattributes 按文件类型精准声明换行策略，禁用 core.autocrlf 并明确标记二进制文件。推荐统一执行 git config `--global` core.autocrlf false，彻底禁用自动转换，所有换行符行为完全由 .gitattributes 决定。

已有历史提交混入 CRLF 怎么修复

运行 git rm `--cached` -r . 然后 git reset `--hard` 可重置工作区，注意先备份未提交改动。之后提交 .gitattributes 文件确保后续提交统一。

参考来源

Windows 怎么配置 Git 的换行符处理_Windows 如何设置 core.autocrlf 避免跨平台换行符冲突【避坑】
Git 怎么设置换行符自动转换_Git 如何解决跨平台 CRLF 和 LF 冲突【避坑】
Git 怎么解决换行符问题_Git 配置 autocrlf 解决 CRLF 和 LF 冲突【排查】
Git 跨平台兼容性终极指南：处理不同系统环境的最佳实践
Git 换行符 (LF/CRLF) 警告：原因与跨平台配置解决方案
跨平台开发必备：如何利用 gitattributes 解决换行符问题
别只改.prettierrc 了！从 Git 配置到 CI/CD，一劳永逸解决团队换行符冲突
如何在 Git 中设置换行符统一解决跨平台开发难题
Git 跨平台换行符解决方案-CSDN 博客
【Git】配置换行符自动转换详解---不同操作系统 (Windows 和 macOS/Linux) 的协作