Parsoid 解析器发布新版本

背景

Parsoid 是 Wikimedia Foundation 自 2012 年起开发的一个 PHP 库，用于在 wikitext 和 HTML 之间进行双向转换。最初用 JavaScript 编写，旨在支持 VisualEditor。自 MediaWiki 1.35 版本起，Parsoid 被捆绑在 MediaWiki 中。在 MediaWiki 1.47 中，Parsoid 计划成为 MediaWiki 的默认解析器，取代现有的原生解析器，这一项目被称为“解析器统一”（parser unification）。

核心内容

Parsoid 是一个应用程序，可以在 MediaWiki 的 wikitext 语法和等效的 HTML/RDFa 文档模型之间进行双向转换，并增强了对自动化处理和富文本编辑的支持。它由 Wikimedia Foundation 的一个团队自 2012 年起持续开发，目前被 VisualEditor、内容翻译（Content translation）及其他应用程序广泛使用。

Parsoid 旨在提供完美无缺的正向和反向转换，即避免信息丢失并防止产生“脏差异”（dirty diffs）。在 Wikimedia 的 wiki 上，对于多个应用，Parsoid 目前通过 RESTBase 代理，RESTBase 会存储由 Parsoid 转换的 HTML。预计 RESTBase 最终将被一个与 MediaWiki 更紧密集成的缓存所取代。

Parsoid 最初被设计为 Web 服务，使用 JavaScript 编写，并基于 Node.js。2019 年 2 月的一场技术演讲（附幻灯片）和一篇博客文章描述了将其移植到 PHP 的过程。Parsoid 扩展 API 目前正在积极开发中，2020 年 8 月的一场技术演讲对此进行了说明。

使用方式

• Parsoid/Releases – 发行版列表
• Parsoid/API – Web API 文档
• MediaWiki DOM spec – 了解从 API 获取的 HTML 结构，该结构被设计为未来存储格式
• Parsoid/LanguageConverter – 关于 Parsoid 实现 LanguageConverter 的说明
• Parsoid/Known differences with Core Parser output – 与核心解析器输出的已知差异

安装说明
Parsoid 自 MediaWiki 1.35 起已包含在内，无需额外配置即可启用。Parsoid 导出一个内部 REST API，历史上被 RESTBase 使用，且无法在 WMF 内部集群之外访问。对于 VisualEditor 或核心阅读视图，该内部 API 已不再需要，且已被弃用，计划在 MW 1.43 中移除。Parsoid 名义上是 mediawiki core 的 composer 库。如果仍需要该内部 API，可通过在 LocalSettings.php 中添加 wfLoadExtension( 'Parsoid', "$IP/vendor/wikimedia/parsoid/extension.json" ); 显式加载 Parsoid 作为扩展。任何仍在使用内部 Parsoid API 的第三方用户强烈建议迁移到核心 REST HTML 页面端点，该端点提供等效功能。

开发指南
开发在 Parsoid 的 Git 仓库中进行，代码审查在 Gerrit 上完成。如果使用 MediaWiki-Vagrant 开发环境，只需添加 visualeditor 角色即可自动设置可用的 Parsoid 和 Extension:VisualEditor。以下说明适用于 MediaWiki 1.35 及更高版本（旧版本用户请参考 Parsoid/JS）。
在标准 MediaWiki 安装中，Parsoid 作为 composer 库（wikimedia/parsoid）包含在内。开发时通常希望使用 Parsoid 的 git 检出副本，而非 MediaWiki 核心捆绑的 composer 版本。可通过在 LocalSettings.php 中添加一组配置代码来实现（具体代码见原文）。这些配置对于大多数 VisualEditor 用户并非必需，但对于开发者是必要的。
如果使用 Nginx 提供 MediaWiki 服务，还需要在 server 块中添加类似 location /w/rest.php/ { ... } 的配置。如果使用 Docker 运行 MediaWiki，需要将本地 Parsoid 仓库作为额外卷映射到容器中（在 docker-compose.override.yml 中配置）。
测试配置是否正确，可访问 {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page（注意生产环境 WMF 服务器不对外暴露 Parsoid REST API）。

运行测试
运行所有解析器测试和 mocha 测试：$ composer test。解析器测试有许多选项，可通过 php bin/parserTests.php --help 查看。如果环境变量 MW_INSTALL_DIR 指向一个已配置的 MediaWiki 安装，还可以运行额外测试：$ composer phan-integrated。

转换简单 wikitext
可使用 bin/ 目录下的 parse.php 脚本从命令行转换简单 wikitext 片段，例如 echo '[[Foo]]' | php bin/parse.php。该脚本有许多选项，可通过 php bin/parse.php --help 查看。

调试 Parsoid（针对开发者）
参见 Parsoid/Debugging 页面获取调试技巧。

持续集成
Parsoid 始终作为库可用（因为它是 mediawiki core 的 composer 依赖），但有两个部分默认未启用：Parsoid ServiceWiring 和 Parsoid 的外部 REST API。测试运行器 Quibble 会在检测到 mediawiki/services/parsoid.git 已克隆为构建的一部分时启用它们。此时，它会将 Wikimedia\Parsoid 的自动加载器指向克隆的代码（替换 composer 安装的版本），并加载扩展 wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );。ServiceWiring 自 MediaWiki 1.38 起应被启用。REST API 理论上永远不会合并到 MediaWiki 中，原因包括：它从未在生产环境中公开暴露，是即将被淘汰的 RESTBase 使用的内部 API；从未经过安全审计；且与企业 MediaWiki API 功能冗余。解决方案是让 VisualEditor 通过 VisualEditor Action API 直接调用 Parsoid。

关键要点

• Parsoid 是一个 PHP 库，实现 wikitext 与 HTML 的双向无损转换，自 2012 年起开发，最初用 JavaScript 编写，后移植到 PHP。
• 自 MediaWiki 1.35 起随核心捆绑，在 1.47 版本中计划成为默认解析器，实现“解析器统一”。
• 核心目标：避免信息丢失，防止脏差异，为 VisualEditor 和内容翻译等应用提供支撑。
• 当前通过 RESTBase 代理存储 HTML，未来将替换为更紧密集成的缓存。
• 内部 REST API 已弃用，计划在 MW 1.43 移除，第三方用户应迁移到核心 REST HTML 页面端点。
• 安装作为 composer 库，无需额外配置；开发者可通过 git 检出并配置 LocalSettings.php 使用自定义版本。
• 测试、转换、调试、持续集成等开发流程均有详细文档支持。
• 长期目标：将 Parsoid 完全整合进 MediaWiki 核心，取代旧解析器，提升编辑体验和系统一致性。

意义与影响

Parsoid 的“解析器统一”项目是 MediaWiki 历史上重要的技术演进。它解决了长期以来 wikitext 解析器与 HTML 输出之间不一致的问题，使得 VisualEditor 等富文本编辑工具能够与底层解析器紧密协作，减少差异和错误。对于 Wikimedia 生态而言，Parsoid 成为默认解析器将带来更一致的页面渲染行为、更简洁的代码维护以及更高效的缓存策略。同时，它也为未来 MediaWiki 的现代化（如更丰富的编辑界面、更好的内容互操作）奠定了基础。对于第三方开发者，虽然内部 API 将逐步移除，但核心 REST