企业官网建设流程全解析

Docs 项目在 Windows 下 Git 换行符被自动转换怎么解决

【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs

在 Windows 上克隆或开发 Docs 项目时，经常会遇到换行符问题：文件没有改过却被 Git 标记为已修改、终端出现 "warning: LF will be replaced by CRLF" 警告、构建或 lint 因换行符不一致而报错。原因是 Docs 项目统一使用 LF（\n）换行符，而 Windows 默认使用 CRLF（\r\n），Git 的自动转换行为会把两者搅在一起。本文按项目 troubleshooting 文档 给出的步骤，让本地 Git 停止自动转换并保留 LF。

症状：先确认你的问题属于换行符转换

troubleshoot.md 列出了三类典型现象，出现其中任意一类就可以判定为换行符问题：

• Git 显示文件已修改，但实际上没有做任何改动；
• 出现 "warning: LF will be replaced by CRLF" 之类的警告；
• 因换行符不一致导致构建失败或 lint 报错。

项目侧在仓库层面强制了 LF：根目录 .gitattributes 中配置了* text=auto eol=lf（对所有文本文件生效），CHANGELOG.md 中也有对应记录🔧(git) set LF line endings for all text files #1032。因此本地 Git 环境必须与仓库的 LF 约定保持一致。

新克隆或尚未被污染：配置当前仓库保留 LF

文档推荐的最简做法是两条仓库级配置，在仓库目录下执行：

git config core.autocrlf false git config core.eol lf

文档对这两条配置的解释是：Git 不再自动转换换行符，工作目录始终使用 LF。注意它们只作用于当前仓库，不影响机器上的其他仓库。

本地仓库已经是 CRLF：先做全局配置再重新克隆

如果本地仓库里已经混入了 CRLF 换行符，文档给出的推荐路径是：先把 Git 配置好，再删除本地副本、重新克隆。

1. 全局配置（--global写入用户级配置，会影响本机所有仓库，执行前确认你接受这一全局行为）：

git config --global core.autocrlf false git config --global core.eol lf

2. 删除本地副本并重新克隆：

# 进入仓库的父目录 cd .. # 删除当前仓库目录（先备份未提交的改动！） rm -rf docs # 重新克隆，这次换行符是 LF git clone git@github.com:suitenumerique/docs.git

执行前必须了解副作用：rm -rf docs会删除整个本地仓库目录，其中所有未提交的改动都会丢失（文档中也明确提示 "backup your changes first!"）。docs是文档示例中仓库目录名，如果你的目录名不同，替换为实际名称；git clone用的是文档中的示例地址，如果你原本是从镜像或其他地址克隆的，替换为你实际使用的地址。

如果无法重新克隆（例如本地有大量需要保留的未提交改动），文档给出了替代路径：先提交备份，再重建索引让 Git 以 LF 重新读入所有文件：

# 1. 备份当前改动 git add . git commit -m "Save changes before fixing line endings" # 2. 从 Git 索引中移除所有文件 git rm --cached -r . # 3. 仓库级换行符配置（若已完成上面的 --global 全局配置，可跳过） git config core.autocrlf false git config core.eol lf # 4. 重新添加所有文件，Git 将使用 LF 换行符 git add . # 5. 提交 git commit -m "✏️(project) Fix line endings to LF"

这套操作会在本地产生一次"所有文件按 LF 重写"的提交，属于文档原样给出的提交信息；如果你后续要向社区提交，CONTRIBUTING.md 对提交信息格式另有要求，可自行调整措辞。

结果验证

排查文档没有提供专门的验证命令，判断标准就是开头三类症状消失：

• 文件不再无故显示为已修改；
• 不再出现 "warning: LF will be replaced by CRLF" 警告；
• 构建和 lint 不再因换行符不匹配而失败。

三类现象全部不复现，即可认为本地换行符问题已解决。

边界说明

• 这一套步骤针对 Windows 用户。文档指出的问题根源是 Windows 默认的 CRLF 行为，其他平台默认行为不同，一般不需要处理。
• Windows 下前端文件监听失效（热重载不生效）是 troubleshooting 文档中的另一个独立问题，与换行符无关，需要时可在 troubleshoot.md 的 "Frontend File Watching Issues on Windows" 一节查看WATCHPACK_POLLING=true的处理方式。

【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs