Biome Markdown 格式化器如何处理 CJK 文本:splitCjkText 测试与 Prettier 兼容性解析

原创2026-09-22 12:24:271,980 阅读
文章标签:开发工具Lint格式化静态分析代码质量前端

Biome Markdown 格式化器如何处理 CJK 文本:splitCjkText 测试与 Prettier 兼容性解析

Biome 在其 Markdown 格式化器中引入了与 Prettier 兼容的测试套件,其中 splitCjkText 目录专门用于覆盖中日韩(CJK)文本的换行与排版行为。本文以 space.md 为切入点,结合同目录测试用例、忽略清单与格式化快照,剖析 Biome 对 CJK 文本的实际处理策略、与 Prettier 的差异,以及底层段落格式化实现。读完本文,你将理解 Biome 为何刻意忽略 Prettier 的 "splitCjkText" 特性,以及如何通过快照机制验证 CJK 文档的格式化结果。

splitCjkText 目录:Prettier 兼容性测试中的 CJK 特例

splitCjkText 位于 Biome Markdown 格式化器的 Prettier 兼容性测试目录下,完整的相对路径是 crates/biome_markdown_formatter/tests/specs/prettier/markdown/splitCjkText。该目录共包含 7 个测试输入文件:

文件名 覆盖场景
space.md 含空格的超长中英混合段落
mixed.md 无空格的中英混排长段落
chinese-japanese.md 中文、日文(含假名、浊点)与全形空白
korean.md 韩文与英文混排、人名列表
han-kana-alnum.md 汉字、假名与字母数字交替的长文本
link.md 含参考式链接定义的长中文段落
symbolSpaceNewLine.md 中日标点、括号、引用符号与换行

这些用例的共同特征是:文本长度远超格式化器默认行宽(80 字符),且包含 CJK 字符与拉丁字符的混排。它们最初是 Prettier 自身的测试用例,Biome 将其引入仓库用于对照验证。

space.md:一个超长中英混合段落的输入

关联文档 space.md 的全部内容仅有一行(外加一个尾部换行),是一个典型的"超宽 CJK 段落":

這是一個 English 混合著中文的一段 Paragraph!這是一個 English 混合著中文的一段 Paragraph!…(反复 16 次)

这行文本在技术上有三个值得注意的特征:

  1. 中英混排且带空格:中文与英文单词之间用半角空格分隔,这是中文技术写作中的常见排版方式;
  2. 单行超宽:整体长度远超 80 字符的行宽上限,构成格式化器的换行压力测试;
  3. 重复句式:同一句式重复 16 次,确保无论在哪里断行,输出都应当保持一致、幂等。

在 Prettier 中,这类文本会被 splitCjkText 特性处理——即把 CJK 字符当作可与拉丁字符互相断行的"软换行点",从而把超长段落拆成多行。Biome 对该特性的处理策略则不同,详见下文。

同目录用例:CJK 排版的典型难题

为了让读者理解 splitCjkText 要解决的问题域,这里展开几个代表性用例:

mixed.md:无空格的中英混排

mixed.md 与 space.md 形成对照——同样是"這是一個English混合著中文的一段Paragraph"的超长重复段落,但中英文之间没有空格。这种写法在中文内容中同样常见(如"MarkdownフォーマッターPrettierはサイコー"),对依赖空格断行的英文换行算法是直接挑战。

chinese-japanese.md:全形空白与日文浊点

chinese-japanese.md 覆盖了三类 CJK 排版细节:

  • 全形空白:全  形 空白 中嵌入的全角空格(U+3000);
  • 日文浊点/半浊点:カ゚キ゚ク゚ケ゚コ゚でガギグゴ(组合用记号 U+3099/U+309A);
  • 日文历史假名:ワ゛、ヰ゛、ヱ゛、ヲ゛ 等罕见写法。

korean.md:韩英混排与字符级断行

korean.md 展示了韩文的特殊性:韩文音节(如 예문)与英文单词(如 Latin)混排时,韩文按音节单位天然可断行,且用例中包含大量人名枚举(李承晩 과 許政 과 …),用于验证 CJK 字符间是否允许断行。

symbolSpaceNewLine.md:禁则处理(kinsoku)

symbolSpaceNewLine.md 是排版难度最高的用例,涉及东亚排版中的禁则处理(kinsoku shori):

  • 行首禁则:句号(。)、逗号(、)、闭引号(」)等标点不应出现在行首;
  • 行尾禁则:开引号(「)、开括号(()不应出现在行尾;
  • 参考式链接定义 [ウィキペディア]: https://ja.wikipedia.org/ 的断行行为。

Biome 的明确选择:忽略 splitCjkText 特性

一个关键事实是:Biome 刻意忽略了 整个 splitCjkText 目录。证据在 prettier_ignored_tests 文件中,其中有一行明确注释:

# CJK text splitting (Prettier-specific feature)
markdown/splitCjkText/

该清单文件还同时忽略了一大批 Prettier 扩展特性(如 wiki-link、footnote、math、front matter、删除线、内嵌语言格式化等),并说明:"忽略的文件不产生快照,并会被排除在兼容性报告之外。"

这意味着:

  • splitCjkText 被定性为 "Prettier-specific feature"——即 Prettier 特有的、Biome 不打算复刻的行为;
  • 这些测试文件不会生成 .snap 快照,也不会进入格式兼容性差异统计。

Biome 的实际行为:不拆分 CJK 段落

虽然 splitCjkText 目录本身被忽略,但 Biome 对同类 CJK 段落的行为可以通过另一份快照直接观察:cjk.md.snap。该快照的输入 markdown/paragraph/cjk.md 与 space.md 高度同源,包含"這是一個English混合著中文的一段Paragraph"的超长段落、全形空白段落、CJK 引号、::: warning 容器、IVS(表意文字变体选择符)等。

快照揭示了 Biome 与 Prettier 的关键差异:

  1. Biome 不对超长 CJK 段落进行拆分:输入与输出中的 CJK 长段落完全一致,保持单行原样;
  2. Biome 保留全部原始间距:全形空白、半角空格均不被改动;
  3. Biome 会报告超宽行:快照末尾的 "Lines exceeding max width of 80 characters" 部分列出了第 1、3、5 行超出了 80 字符上限,其中就包括与 space.md 相同的超长中英混合段落。

快照中的 Prettier 差异(diff)段落也印证了差异范围:两处 @@ 变更均来自有序列表(1.a / 2.b / 3.中 是否合并为一行),而所有 CJK 长段落文本在输入、输出中逐字一致——Biome 在 CJK 段落上保持原样输出。

这一设计取向可以概括为:Biome 的 Markdown 格式化器不会为了行宽而强行拆分 CJK 文本,而是尊重作者原始的断行与排版,仅把超宽问题作为可报告的诊断信息。

源码视角:段落如何被格式化

Biome 的 Markdown 段落格式化入口是 paragraph.rs(FormatMdParagraph 规则)。其核心逻辑:

  • is_suppressed:当段落包含注释后代节点时跳过格式化(保留原样);
  • fmt_fields:将段落内容委托给 FormatMdFormatInlineItemListOptions,并传入两个关键参数:
    • print_mode: TextPrintMode::fill()——行内元素的填充打印模式,即"尽量放满一行,放不下再处理换行";
    • text_context: TextContext::Neutral——段落所处的文档上下文(由标题、引用等位置决定)。

TextPrintMode::fill 是理解"不拆分 CJK"的关键:Markdown 行内内容被视为一组可以顺序打印的 token,格式化器按可用宽度填充。当 CJK 文本本身不包含可断行点(如空格)时,fill 模式不会像 Prettier 的 splitCjkText 那样在每个 CJK 字符之间制造断行机会。

此外,段落规则还支持 FormatMdParagraphOptions(trim_mode 与 text_context),供标题等外层结构在格式化段落时微调首尾空白与文本语境,例如 TextPrintMode 用于控制段落起始处的裁剪行为。

如何运行这些测试

splitCjkText 目录下的用例由 Biome Markdown 格式化器测试框架驱动。测试入口在 spec_tests.rs,通过 tests_macros::gen_tests! 宏扫描 tests/specs/markdown/**/*.md 并逐个执行 crate::spec_test::run。也就是说:

  • 凡位于 tests/specs/markdown/ 下且未被 prettier_ignored_tests 排除的 .md 文件都会作为格式化输入参与测试;
  • prettier/ 前缀的目录(如 prettier/markdown/)是 Prettier 兼容性测试的镜像;
  • 由于 markdown/splitCjkText/ 在忽略清单中,该目录用例不产生快照,运行时会被跳过。

若要在本地复现 Biome 对 CJK 段落的真实输出,可以直接运行 cargo test -p biome_markdown_formatter,然后查看 tests/specs/markdown/paragraph/ 下 cjk.md 对应的快照(现有快照为 cjk.md.snap)。

小结

  • Biome 引入了 Prettier 的 splitCjkText 测试目录(含 space.md 等 7 个用例),但通过 prettier_ignored_tests 明确将其标记为 "Prettier-specific feature" 并整体忽略;
  • Biome 对超长 CJK 段落的策略是保持原样、不做字符级拆分,仅通过快照报告超宽行,这与 Prettier 主动在 CJK 字符间断行的行为形成鲜明对比;
  • 段落格式化由 paragraph.rs 中的 FormatMdParagraph 配合 TextPrintMode::fill() 实现,CJK 文本因缺少可断行点而保持单行;
  • 若你使用 Biome 格式化中文 Markdown 文档,可以预期:中英混排段落不会被自动拆行,超宽行需要通过手动断行或调整原始排版来解决。
登录后查看全文
biome