企业官网建设流程全解析

• 教程
• 文档

导读

在跨平台协作或长期维护的 Git 仓库中，CRLF与LF行尾混用常导致脚本报错、diff 刷屏等诡异问题。本文基于 30 Seconds of Code 仓库中 fix-incorrect-line-endings 这一实战经验，系统讲解如何通过core.autocrlf与git add --renormalize两条命令，在不重写提交历史的前提下一次性修正全仓库的行尾，并补充core.eol、.gitattributes、core.safecrlf等配置的深度原理与验证方法。读完本文，你将能独立排查并根治 Git 仓库中的行尾问题。

一、问题现场：一行诡异的报错

在 30 Seconds of Code 的这篇 Git 实战记录中，作者同事在运行一个 Ruby 脚本时遇到了如下报错：

env: ruby\r: No such file or directory

乍看像是找不到 Ruby 解释器，但真正的原因是行尾（line endings）。该脚本文件使用了CRLF行尾，而系统期望的是LF行尾。在 Unix 系 Shell 解析 shebang（#!/usr/bin/env ruby）时，行尾的\r被当作解释器路径的一部分，于是变成了ruby\r，自然无法执行。

这类问题在不同操作系统间编辑文件时极易出现：

该文档还特别指出一个容易被忽略的事实：即使整个团队都使用 Unix 系系统，文件也可能被某个工具或历史提交带入CRLF行尾——案例中正是通过 VS Code 的状态栏确认了文件实际是CRLF编码。因此，行尾问题并不只发生在跨平台团队中，排查时不要先入为主地排除同系统协作的场景。

二、第一步：设置全局行尾策略

找到原因后，第一步是让 Git 接管行尾处理，并统一成LF：

# 为仓库中的所有文件设置 LF 行尾 git config --global core.autocrlf input

core.autocrlf的取值语义

core.autocrlf控制 Git 在**检出（checkout）与提交（commit）**时的行尾转换行为，共有三个取值：

在 Unix 系环境执行git config --global core.autocrlf input，意味着：工作区里的文件保持原始状态，但一旦进入暂存区/提交，Git 会统一将其转为LF入库。这正是"全局修复行尾"的第一步。

[!TIP]

需要特别说明的是：该命令只影响"之后"的写入行为，并不会修改已经存在于工作区或历史中的文件。这也是原文档明确指出"doesn't fix existing files"的原因——要修正存量文件，还需要第二步。

配套配置：core.eol与git config -e

与本仓库中另一篇 line-endings 记录的知识相呼应，core.eol是更细粒度的行尾配置，直接指定仓库内文件应使用哪种行尾：

# Usage: git config core.eol [lf | crlf] git config core.eol lf # 使用 UNIX 行尾 git config core.eol crlf # 使用 DOS 行尾

两者协作关系可概括为：core.autocrlf决定"何时转换"，core.eol决定"转换到什么目标"。若你的团队同时涉及 Windows 与 Unix 成员，推荐配合 配置 Git 的默认文本编辑器 后，直接使用 git config -e 编辑配置文件 手工核对这些键值：

git config --global -e # 打开全局配置文件 git config -e # 打开当前仓库的配置文件

三、第二步：不重写历史，修正存量文件

直接对所有存量文件重新提交会污染提交历史，代价过高。正确的做法是使用git add --renormalize：

# 重新检查仓库中所有文件并应用新的行尾设置 git add --renormalize .

原理：为什么它不重写历史？

git add --renormalize会忽略工作区文件是否"看起来没变"，强制对所有已跟踪文件重新执行"clean 过滤器 + 行尾规范化"流程，并把规范化后的内容重新写入索引（staging area）。关键在于：

• 它只改变索引中记录的 blob 内容，不触碰任何历史提交对象；
• 你随后的提交是一个普通的新提交，历史记录依然完整保留；
• 与git filter-branch或git rebase等重写历史的操作有本质区别——这也是原文档强调"without messing up the repository's history"的原因。

从执行细节看，该命令内部等价于git add --renormalize对所有匹配的文件执行 "core.autocrlf/core.eol规则下的重新规范化"。Git 会比对规范化前后内容，只有行尾真正变化的文件才会进入待提交状态（git status会显示这些文件为 modified）。

[!WARNING]

运行前请确保当前工作区是干净的（或至少已暂存/提交你的改动），避免把未完成的编辑一并卷入这次批量规范化。

完整修复流程

将两步串起来，就是原文档给出的完整解决方案：

# 1. 设置全局行尾策略为 LF git config --global core.autocrlf input # 2. 重新规范化所有存量文件（不改写历史） git add --renormalize . # 3. 查看将被修正的文件列表，确认无误 git status # 4. 提交本次行尾修复 git commit -m "Normalize line endings to LF"

四、进阶：用.gitattributes做团队级行尾治理

core.autocrlf是本机级配置（依赖每个成员的本地设置），在多平台团队中并不足够可靠。更规范的团队级做法是提交一个.gitattributes文件，把行尾规则固化进仓库本身：

# 所有文本文件统一使用 LF 入库 * text=auto # 指定文件类型强制 LF / CRLF *.sh text eol=lf *.bat text eol=crlf # 二进制文件禁止行尾转换 *.png binary *.jpg binary

配合.gitattributes后，git add --renormalize .会按属性文件中的规则重新规范化全部文件，效果与core.autocrlf一致，但对所有克隆该仓库的人生效，规则随仓库分发。

五、验证与防范：避免问题复发

修复完成后，可用以下手段验证行尾是否已统一：

# 查看某文件的实际行尾（$ 表示行尾，CRLF 会显示 ^M） git diff --cached # 用 cat 检查是否还有 CRLF 残留 cat -v script.rb | grep '\^M' # 用 file 命令确认 file script.rb

预防复发方面，可以开启core.safecrlf在提交时拦截"可能出错的行尾转换"：

git config --global core.safecrlf warn # 只警告 git config --global core.safecrlf true # 禁止提交（严格模式）

另外，仓库中同主题的 JavaScript 片段 normalizeLineEndings 提供了一个有趣的"非 Git"视角：在程序处理字符串层面，用一条正则即可完成行尾归一化：

const normalizeLineEndings = (str, normalized = '\n') => str.replace(/\r?\n/g, normalized);

这提醒我们：行尾问题是横跨"操作系统 → 版本控制 → 字符串处理"三个层面的系统性问题，本文的 Git 方案负责仓库层面，而上面的 JS 工具函数负责运行时数据处理层面。

六、总结

回顾整个修复过程，核心方法论可以浓缩为三点：

1. 症状识别：形如env: ruby\r: No such file or directory的报错、或 diff 中整文件变红的怪象，优先怀疑行尾问题；
2. 规则先行：git config --global core.autocrlf input确立全局行尾策略（Unix 系团队统一LF）；
3. 存量修复：git add --renormalize .在不重写历史的前提下重新规范化所有已跟踪文件，随后正常提交。

这两条命令的组合正是 fix-incorrect-line-endings 这篇文档给出的标准解法。配合.gitattributes、core.safecrlf等治理手段，你可以彻底告别跨平台行尾噩梦。

• 教程
• 文档