Biome 与 Prettier 兼容性挑战报告深度解读：96%+ 相似度的背后

Biome 与 Prettier 兼容性挑战报告深度解读：96%+ 相似度的背后

【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址: https://gitcode.com/gh_mirrors/bi/biome

导读

本文基于 Biome 仓库中的 report-challenge.md 及其两份配套兼容性报告 report-es2015.md、report-es2024+.md，系统解读 Biome 参与 Prettier 兼容性挑战（Prettier Challenge）的评测口径、测试用例取舍、选项支持范围与底层测试基础设施。读完本文，你将理解这两份报告里的兼容性百分比是如何计算出来的、哪些语法被排除在评测之外及其原因，以及 Biome 如何借助自动化测试基础设施（.prettier-snap快照对比、非严格模式标记、范围格式化占位符等）持续对齐 Prettier 的输出。

挑战背景：为什么会有这两份报告

report-challenge.md是 Biome 面向 Prettier 兼容性挑战（algora.io 上发起的 Prettier Challenge）提交的说明文档。该挑战要求参赛格式化工具尽可能在输出上与 Prettier 保持一致，Biome 为此提供了两份口径不同的兼容性报告：

两份报告的核心差异在于语法覆盖范围，而非格式化质量本身：report-es2015刻意排除了 ES2016+ 的标准语法，用于衡量「在纯 ES2015 代码库上」的兼容度；report-es2024+则面向更接近当前 JavaScript 生态的真实代码形态，纳入 ES2024 及广泛使用的实验性语法。

总体指标：兼容性如何量化

两份报告开头都给出了两个总体指标，并附带了严格的数学定义：

平均兼容性（Average compatibility）

$$average = \frac{\sum_{file}^{files}compatibility_{file}}{files}$$

即：对每个测试文件计算 Prettier Similarity（相似度百分比），再对所有文件取算术平均。

兼容行（Compatible lines）

$$average = \frac{\sum_{file}^{files}matching_lines_{file}}{max(lines_{rome}, lines_{prettier})}$$

即：所有文件中「匹配行数」之和，除以「Biome 输出行数与 Prettier 输出行数中的较大者」。这一指标以行粒度衡量输出一致性，能避免少数文件的行数差异掩盖整体水平。

两报告的实际数值：

• report-es2015.md（4530 行）：平均兼容性 96.70，兼容行 97.28；
• report-es2024+.md（5490 行）：平均兼容性 96.75，兼容行 97.32。

两份报告主体均按测试文件逐条列出Prettier Similarity百分比，对未达到 100% 的文件附上 unified diff，直观展示 Biome 输出与 Prettier 输出的差异点。

有代表性的低分用例

• js/assignment/issue-15534.js：Similarity 18.18%。差异集中在计算属性访问params["redirectTo"]这类成员表达式在赋值左侧的换行策略上，Biome 与 Prettier 对括号位置的处理不同；
• js/arrows/newline-before-arrow/newline-before-arrow.js：Similarity 0.00%（仅出现在 report-es2024+.md 中）。该文件在 ES2024+ 口径下被纳入评测，Biome 的解析阶段对async (x) => x;换行后的处理与 Prettier 出现整体性差异；
• js/arrays/numbers-with-tricky-comments.js：Similarity 54.55%，差异围绕注释/*block*/、// line后的数字字面量分组换行策略。

这些 diff 块是定位格式化差异的第一手材料，也是 Biome 后续迭代修复格式化的回归测试输入。

如何亲测：Playground 与 Nightly 版本

报告文档给出了两种直接验证方式：

1. 在线 Playground：将任意代码粘贴到 Biome 的在线 Playground 中格式化，与 Prettier 输出逐行对比；
2. 安装 nightly 版本（报告撰写时对应1.3.3-nightly.ced82da）：

npm install -D @biomejs/biome@1.3.3-nightly.ced82da

由于这些报告记录的是特定时间点的快照，若要复现当时的评测环境，应使用文档标注的 nightly 版本；当前仓库的格式化逻辑（biome_js_formatter）已经在此基础上持续演进，使用最新稳定版实测结果可能与报告数值存在差异。

测试用例说明：忽略、非严格、不稳定与刻意差异

report-challenge.md的「Test case notes」章节是理解报告口径的关键。它把 Prettier 官方测试套件中的用例分成了四类处理方式。

忽略的测试用例（两份报告共同忽略）

1. JSX 相关（13 个）：如js/binary-expressions/inline-jsx.js、js/call/first-argument-expansion/jsx.js、js/comments/jsx.js、js/trailing-comma/jsx.js、js/unicode/nbsp-jsx.js等。报告并未解释具体原因，但从源码测试入口 prettier_tests.rs 可以看到，Biome 的 Prettier 测试套件本身已将.js文件按 JSX 源码类型（JsFileSource::jsx()）处理，说明忽略这些用例并非因为无法解析 JSX，而是这些用例聚焦 JSX 格式化细节，与评测目标无关。

2. 模板字面量中的嵌入式语言格式化（13 个目录/文件）：js/multiparser-comments/、js/multiparser-css/、js/multiparser-graphql/、js/multiparser-html/、js/multiparser-markdown/、js/multiparser-text/、js/template-literals/css-prop.js、js/template-literals/styled-jsx.js等。Prettier 能在模板字面量内识别 CSS、GraphQL、HTML、Markdown 并递归格式化，而 Biome 挑战报告聚焦 JavaScript 语法本身，故排除这类跨语言场景（报告文档中该列表embed.js出现两次，系原文笔误，不影响结论）。

3. 非标准与实验性语法：包括 V8 内部函数（js/v8_intrinsic）、Babel 插件语法（js/babel-plugins/）、async do 表达式（js/async-do-expressions/）、do 表达式（js/do/）、export X from "mod"（js/export-default/export-default-from/等）、module <id> {}模块块（js/module-blocks等）、元组/记录语法#[]与#{}（js/tuple、js/record等 8 个用例）、管道运算符|>（js/comments-pipeline-own-line、js/partial-application、js/pipeline-operator）、绑定运算符::（js/arrows-bind/、js/bind-expressions/等）、私有字段解构（js/destructuring-private-fields/）、延迟导入求值（js/deferred-import-evaluation/）、source phase imports（js/source-phase-imports/）、import reflection（js/import-reflection/）。

这些语法要么尚未标准化、要么处于 Stage 早期，Biome 解析器不保证支持，因此被排除在评测之外。

ES2015 报告额外忽略的用例

report-challenge.md 特别说明，report-es2015在共同忽略列表之上，还排除了以下两类：

广泛使用的实验性语法：Decorators（js/decorators、js/decorator-auto-accessors/、js/decorators-export/等）、js/import-assertions/、js/import-attributes/、js/explicit-resource-management。这些语法在 TypeScript/React 生态中已被大量使用，但并非 ES2015 标准，故从 ES2015 口径中排除（却被纳入 ES2024+ 口径）。

标准 ES2016+ 语法（完整列表见原文，此处列举代表）：指数运算符**（js/async/exponentiation.js、js/binary-expressions/exp.js）、async/await（js/async/、js/arrows/newline-before-arrow/newline-before-arrow.js等 9 个用例）、函数调用尾逗号（js/trailing-comma/function-calls.js等）、对象展开与剩余{ ...x }（js/spread、js/destructuring/等 8 个用例）、for await（js/for-await/）、私有类字段#field（js/classes-private-fields等）、可省略 catch 绑定try {} catch {}（js/optional-catch-binding）、空值合并a ?? b（js/nullish-coalescing等）、可选链prop?.（js/optional-chaining/等 3 个用例）、BigInt（js/big-int/等）、数字分隔符1_000（js/literal-numeric-separator/等）、逻辑赋值??=/&&=（js/logical-assignment/）、私有品牌检查#field in（js/private-in）、私有方法、类实例字段、静态块static {}（js/class-static-block/）、顶层await（js/top-level-await/）、regexd/vflag（js/regex/d-flag.js、js/regex/v-flag.js）、Shebang#!/usr/bin/node（js/shebang/）。

非严格模式测试用例

以下测试用例在非严格 JavaScript 模式（sloppy mode / script mode）下处理：

• js/with/
• js/sloppy-mode/
• js/identifier/

with语句、部分标识符解析仅在 sloppy 模式下合法。这一处理在测试基础设施中有直接实现：prettier_tests.rs 中的is_non_strict_mode函数会检查文件路径前缀是否命中这三个目录，命中则调用source_type.with_module_kind(ModuleKind::Script)切换到脚本（非模块）解析模式。

不稳定测试用例：以稳定后的输出为准

报告指出，Prettier 对部分用例连续格式化两次结果不同（格式化不稳定）。Biome 的测试基础设施会捕获这类问题（CheckReformat二次格式化校验，见下文源码分析），Biome 选择匹配「稳定化后的版本」，即对输入多次运行 Prettier 后得到的最终稳定输出（文档说明实际上运行第二次即可稳定）。

受影响的用例共 9 个：

• js/sequence-expression/parenthesized.js
• js/comments/tagged-template-literal.js
• js/comments/return-statement.js
• js/last-argument-expansion/embed.js
• js/for/continue-and-break-comment-without-blocks.js
• js/class-comment/misc.js
• js/range/boundary.js
• js/range/class-declaration.js
• js/range/multiple-statements2.js

这意味着当 Biome 输出与 Prettier 的「第一次输出」不同、但与「第二次输出」一致时，该用例仍被判定为兼容。

有意的格式化差异

部分差异是刻意保留的：要么因为 Biome 解析阶段的严格性（解析出的 AST 本身不允许 Prettier 那样的输出形态），要么是 Biome 认为保持现状可读性更好。报告指向了对应的 issue 以查看这些用例的详细描述，本文不再赘述，但需明确：报告中的兼容性百分比是「实际差异」而非「目标差异」，这 9+ 个不稳定用例与刻意差异用例共同构成了兼容性 100% 之外的合理缺口。

选项支持：quoteProps 的刻意取舍

报告「Option support」章节声明：Biome 实现了 Prettier 提供的全部 JavaScript 格式化选项。唯一例外是quoteProps：

与 Prettier 不同，Biome 只为quoteProps提供as-needed和preserve两个值，不提供consistent，这是刻意选择。

这一声明在源码中得到验证：context.rs 中QuoteProperties枚举只有两个变体，且FromStr实现只接受"as-needed"与"preserve"两个字符串（context.rs），传入其他值会得到"Value not supported for QuoteProperties"错误。此外，格式化的通用选项（缩进风格、缩进宽度、行宽、行尾、尾随换行等）在 biome_formatter_test 的测试基建中均会透传给真实 workspace 配置，说明测试环境与用户实际 CLI/LSP 配置路径一致。

源码级验证：测试基础设施如何产出这些报告

理解报告的生成机制，有助于判断其可信度与复现方式。

测试入口与用例发现

prettier_tests.rs 通过tests_macros::gen_tests!宏扫描tests/specs/prettier/{js,typescript,jsx}/**/*.{js,ts,jsx,tsx}下的全部 Prettier 官方用例，每个文件生成一个测试。测试中：

• .js文件统一按 JSX 源码类型解析（Prettier 测试套件常在.js中混用 JSX）；
• 文件名含jsx的.ts文件按 TSX 解析；
• 命中非严格模式目录的文件切换为ModuleKind::Script；
• 另有is_restricted_typescript将三个特定 TypeScript 文件切换为StandardRestricted变体，对应 Prettier 对const类型参数等语法的受限解析。

快照对比与 diff 生成

核心逻辑在 test_prettier_snapshot.rs：

1. 占位符剥离：strip_prettier_placeholders会移除 Prettier 用例中的游标占位符<|>与范围占位符<<<PRETTIER_RANGE_START>>>/<<<PRETTIER_RANGE_END>>>（utils.rs），因此既有用例同时覆盖了「全文格式化」与「范围格式化」两种模式；
2. prettier-ignore 桥接：将prettier-ignore替换为biome-ignore format: prettier ignore，输出后再替换回来，实现与 Prettier 等价的局部忽略语义；
3. 二次格式化校验：对格式化结果再次运行CheckReformat，若输出不一致则测试失败——这正是报告「不稳定测试用例」章节所述能力的实现位置（test_prettier_snapshot.rs）；
4. 与 Prettier 输出对比：get_prettier_diff（utils.rs）读取同目录下由 Prettier 预先生成的.prettier-snap文件，若 Biome 输出与之一致则直接删除冗余快照（PrettierDiff::Same），否则生成 unified diff 写入.snap快照并交给DiffReport汇总——这正是报告逐文件列出Prettier Similarity与 diff 的数据来源。

从仓库结构看，crates/biome_js_formatter/tests/specs/prettier/下存放着与 Prettier 官方套件对应的输入文件及快照，报告中的每条 diff 均可回溯到具体的.prettier-snap对比结果，具备可复现性。

结论与启示

综合两份报告与源码实现，可以得出以下要点：

1. 兼容性数值：ES2015 口径平均兼容性 96.70、兼容行 97.28；ES2024+ 口径平均兼容性 96.75、兼容行 97.32。两份报告针对的是报告撰写时的特定版本快照，当前仓库代码已进一步演进；
2. 评测口径透明：报告明确列出了被忽略的测试用例分类（JSX、嵌入式语言、非标准语法、ES2016+ 语法），并解释了三类特殊处理（非严格模式、不稳定用例取稳定输出、刻意差异），读者可据此判断兼容性数据的适用范围；
3. 选项层面对齐：Biome 实现了 Prettier 全部 JavaScript 格式化选项，唯一差异是quoteProps刻意不提供consistent值，相关枚举与解析逻辑见 context.rs；
4. 基础设施保障：通过.prettier-snap对比、占位符剥离、二次格式化校验与DiffReport汇总（test_prettier_snapshot.rs、utils.rs），Biome 将「与 Prettier 输出一致」固化为可回归的自动化测试，使兼容性提升具有持续可度量性。

对希望评估或复现 Biome 兼容性水平的开发者，建议直接阅读 report-es2015.md 与 report-es2024+.md 中的 diff 段落定位差异语法点，再结合 prettier_tests.rs 与测试用例目录深入调试。

【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址: https://gitcode.com/gh_mirrors/bi/biome