#故障排查

先做三件事，通常能直接定位问题：

1. 看占位文案：labels 能区分“未求值”“已拦截”“未知结构”。
2. 看 document.diagnostics：每条诊断带有 stage、code 与源码位置。
3. 缩小到最小源码与最小选项；去掉自定义插件与组件后复现。

不确定某个占位是否正常时，先对照概览的默认输出与支持矩阵。

#内容显示

更多默认输出见支持矩阵。

#运行与构建

#错误码

错误对象带有 code；准备阶段错误还带 stage。不要根据 message 文本分支。

完整错误码与类层次见错误与诊断。

#诊断怎么读

for (const diagnostic of prepared.diagnostics) {
  console.warn(diagnostic.stage, diagnostic.code, diagnostic.message);
}

• stage 可能是 wikitext、hast、rehype、sanitize 或 finalize。
• 单条诊断不会中断整页渲染；渲染失败会由错误边界替换对应顶层块。
• 视图层失败通过 onRenderError 上报，占位文案来自 labels.renderFailed。
• meta 记录实际生效的 policy、labels、headingIdStrategy 与授权图片，适合排查“配置有没有生效”。

#还是无法定位

报告问题时附上：

• 最小 wikitext 源码与 pageName。
• 使用的入口、解析与准备选项（可脱敏）。
• 库版本、parserVersion、React 与打包器版本。
• document.diagnostics 与完整错误对象的 code、stage、cause。

更多渠道见参与与反馈。