跳到正文

文件换行和字符串换行需要分别处理

把 '标题\n正文' 展开成两行模板字符串时,源码文件在 Windows 上可能以 CRLF 保存。字符串里的换行会变成 \r\n 吗?我把同一个例子分别存成 LF 和 CRLF,再用 TypeScript 和 Vite 构建后执行。两次得到的都是 '标题\n正文'。接着用 Vite 的 ?raw 导入两行文本,文件里的 CRLF 就保留在了值里。

两段文字在编辑器里长得一样。前者是一段由 JavaScript 解释的源码,后者是程序读取的数据。把这两层分开,才能知道改一个换行设置会影响什么。

LF、CRLF 和 CR 是三种字符序列

拿只有两行的 A 和 B 举例。用 UTF-8 保存,且 B 后面没有换行,文件里的字节如下。

换行 JavaScript 写法 文件字节 常见来源
LF(Line Feed) \n 41 0A 42 Unix、Linux、现代 macOS
CRLF(Carriage Return + Line Feed) \r\n 41 0D 0A 42 DOS 和 Windows 的传统约定
CR(Carriage Return) \r 41 0D 42 旧 Macintosh 应用生成的文本

CR 和 LF 的名字保留了终端动作的区别。CR 把光标移回行首,LF 让光标下移一行。在只按 LF 分行的工具里,旧 Macintosh 的 CR 文件可能被读成一整行,打印到终端时还会反复覆盖当前行。现代 macOS 沿用 Unix 的 LF,这些行为可以对照 Apple 的跨平台换行说明。

Windows 的编辑器同样可以保存 LF。微软在 2018 年也为记事本增加了 LF 和 CR 支持。

操作系统给的是惯例,具体文件仍要看内容。读取已有文件或生成约定了格式的输出时,换行由文件内容或格式约定决定。程序要生成一份遵循本机惯例的新文本时,可以用 os.EOL。它在 Windows 上返回 \r\n,在 POSIX 系统上返回 \n,详见 Node.js 的系统换行常量。

模板字符串的物理换行会得到 LF

普通模板和 String.raw 都会把源码中的物理换行解释为 LF,包括原文件里单独的 CR。这里的 raw 会保留转义的写法,键入 \r\n 时会得到四个可见字符。要让值包含真正的 CR 和 LF,可以在普通字符串或普通模板中用 \r\n 转义。取值定义见 ECMAScript 的模板字符串词法规则。

写法 值中的字节
普通模板中在 A 和 B 之间直接换行 41 0A 42
String.raw 模板中在 A 和 B 之间直接换行 41 0A 42
普通字符串 'A\r\nB' 41 0D 0A 42
在 String.raw 模板中键入 A\r\nB 41 5C 72 5C 6E 42

源码在 Git 检出时从 LF 变成 CRLF,模板得到的文本仍使用 LF。把固定正文中的 \n 展开时,还要核对正文里的空格、缩进和首尾换行,示例见使用模板字符串优化多行文字展示。

Git 决定暂存与检出时的转换

Git 的文本换行转换有两个方向。添加到暂存区时,可以把文本里的 CRLF 归一成 LF。检出时,可以按照属性和配置把暂存内容写成 LF 或 CRLF。仓库里保存的 LF 因此可能在 Windows 工作区里显示为 CRLF。单独的 CR 不在这套转换的范围内。每条路径是否启用转换,可以通过 Git 的 .gitattributes 属性指定。

跨平台项目可以把规则写进仓库根目录的 .gitattributes。例如让一般文本用 LF 检出,让批处理文件用 CRLF,把专门验证字节的样本排除在文本换行转换之外。

* text=auto eol=lf
*.bat text eol=crlf
tests/fixtures/line-endings/** -text

排查换行时,先看具体路径的属性,再看个人配置。缺少路径属性时,true 会为自动识别的文本启用归一化,检出时使用 CRLF。input 只做输入方向的转换。false 关闭这个配置项提供的自动转换,路径上显式声明的属性仍生效。三个值都属于 Git 的 core.autocrlf 配置。

git ls-files --eol -- src/example.ts
git check-attr text eol -- src/example.ts
git config --show-origin --get core.autocrlf

用上面的配置测试,批处理文件显示 i/lf w/crlf,表示索引里是 LF,工作区是 CRLF。刻意保留 CRLF 的样本显示 i/crlf w/crlf。旧式 CR 文本还可能显示 -text,需要查看实际字节才能确认换行。这两列来自 git ls-files --eol。

如果已有仓库要统一换行,可以从干净的工作区执行 git add --renormalize .,检查暂存差异,再单独提交这批格式变更。这个命令会重新处理跟踪中的文件,已有的内容修改也可能被一起暂存,详见 git add --renormalize。

编辑器、格式化工具和构建工具各处理一份输出

支持 EditorConfig 的编辑器会按 end_of_line 保存文件,值可以是 lf、crlf 或 cr。文件末尾是否补换行,由 insert_final_newline 单独决定。这两个配置都来自 EditorConfig 规范。

Prettier 的 endOfLine 默认是 lf。auto 会参考文件第一处换行来统一混用的格式。显式的 Prettier 配置可以覆盖从 EditorConfig 读取的值,因此启用了两套工具的项目,应把它们的换行约定与 Git 检出的格式对齐。可用的值和覆盖方式见 Prettier 的 endOfLine。

TypeScript 生成代码时会使用配置指定的换行。用 TypeScript 6.0.3 测试时,编译器保留下来的模板片段可以带着原有的物理换行,所以生成的同一份 JavaScript 也可能混用两种换行。控制生成代码换行的选项是 TypeScript 的 newLine。

Vite 8.3.5 构建同一组样本时,产物文件用的是 LF,模板求值仍是 LF。直接执行产物,可以看到显式写的 \r\n 保留在值里。资源文件里的 CRLF 也能在运行时读到,入口是 Vite 的原始文本导入 ?raw。

按用途决定是否归一化读到的文本

只需要逐行处理导入文本时,可以用 text.split(/\r\n|[\n\r]/u) 识别三种换行。把 CRLF 放在前面,两个字符才会作为一次分隔。如果用 split('\n') 处理 CRLF,每行末尾还会留下 \r。如果只支持现代 Unix 和 Windows 文本,/\r?\n/u 就够了。Markdown 则要考虑三种换行,具体见 CommonMark 的行与换行定义。

要把解析结果写回原文时,先确认偏移基于哪份文本。JavaScript 里,'A\r\nB'.indexOf('B') 是 3,'A\nB'.indexOf('B') 是 2。例如 Markdown 批注用归一化后的正文算出起止位置,写回时又按原始文件切片,每经过一个原始 CRLF 就会多偏一个 UTF-16 代码单元。可以全程使用同一份文本,也可以保留归一化文本到原文的偏移映射。对包含 LF、CRLF 的输入分别做写入和读回测试,可以验证两套位置有没有混用。

要核对原文件的哈希或签名,直接读取原始字节,并让 Git 和格式化工具跳过该样本的换行转换。协议报文则要按约定生成,例如起始行和字段行都使用 CRLF 的 HTTP/1.1 报文。