#性能与预算

默认管线是同步的：解析与准备都在调用时完成。库不内置调度器、Worker 或虚拟列表；性能策略由宿主决定。本页给出可调的预算与常用的开销控制方式。

#成本在哪里

retainSyntax: true 会保留源码语法树，显著增加内存与构建成本；只在需要源码坐标或 playground 语法树时开启。

#预算

#解析

有效预算按“单次解析选项 → 创建时 defaults → 共享默认值”合并。非法值抛 INVALID_CONFIG，超限抛 SOURCE_TOO_LONG 或 SOURCE_TOO_COMPLEX。

#准备

准备阶段的工作树与最终 HAST 使用固定预算，不能通过解析选项调整：

这些值是防护阈值，不是性能目标。触发时准备阶段直接失败；库产生的合法快照总能被 restoreWikitextRenderDocument 恢复。

#模板展开

#把解析放到 Worker

库不提供 Worker，但快照是普通数据，可以直接跨线程传递：

// worker.ts
import { parseWikitext } from "react-wikitext/parse";
import { serializeWikitextDocument } from "react-wikitext/ast";

self.onmessage = (event: MessageEvent<string>) => {
  const document = parseWikitext(event.data, { pageName: "Example" });
  self.postMessage(serializeWikitextDocument(document));
};

// main.ts
import { restoreWikitextDocument } from "react-wikitext/ast";
import { prepareWikitext } from "react-wikitext/hast";

const document = restoreWikitextDocument(payload);
const prepared = prepareWikitext(document);

• 也可以把准备放进 Worker，传回渲染快照；渲染必须在主线程。
• 传输前先确认快照版本；跨版本缓存应由恢复函数的校验结果判断是否可用。
• 同一份源码重复发送时，缓存快照比重复解析更划算。

#缓存

缓存键必须覆盖所有影响输出的输入：

快照内的 AST_SCHEMA_VERSION、SYNTAX_SCHEMA_VERSION 与 RENDER_SCHEMA_VERSION 变化意味着结构不兼容，应让缓存整体失效。缓存与恢复的安全边界见安全模型。

#避免重复工作

• 把 parseOptions 与 prepareOptions 放在组件外，或用 useMemo 固定引用；内联对象会让 Wikitext 每次渲染都重新解析。
• 解析器在模块加载时创建一次；配置变化时创建新解析器。
• 只改组件或样式时复用渲染快照，不重新准备。
• 不需要源码坐标时关闭 retainSyntax。
• 服务端准备、客户端只渲染，可以减少浏览器下载与执行；见服务端与框架。

#按入口拆分打包

只做展示时，客户端可以动态加载 /view，避免把解析器带进首屏包：

async function loadViewer() {
  const [{ WikitextView }, { restoreWikitextRenderDocument }] = await Promise.all([
    import("react-wikitext/view"),
    import("react-wikitext/hast"),
  ]);
  return { WikitextView, restoreWikitextRenderDocument };
}

#大文档

• 100 KB 级别的密集文本可能阻塞主线程；优先放到 Worker，或按页拆请求。
• 库没有虚拟列表；长页面由宿主分页、折叠或分段渲染。
• 错误边界只隔离失败块，不减少整体渲染成本。
• 目录、引用与分类是文档级结构，需要整份文档准备后才能生成。

#测量

性能数字随源码、配置、浏览器与硬件变化，不在文档中固定。需要对比时运行仓库的 pnpm bench，并记录输入、解析器版本与改动前后的差异。