> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 故障排查

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

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

不确定某个占位是否正常时，先对照[概览的默认输出](/zh/guide/introduction.md#默认输出)与[支持矩阵](/zh/guide/syntax-support.md)。

## 内容显示

| 症状                       | 原因                                                 | 处理                                                                       |
| ------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------ |
| 模板区域显示占位                 | 默认管线不求值模板                                          | 用 [`/expand`](/zh/guide/templates.md)；或自定义 `semanticComponents.template` |
| 解析器函数显示占位                | 同上，默认不执行                                           | 受支持的纯 wikitext 函数可用 `/expand`；其余保留占位                                     |
| 图片只有说明文字                 | 没有 `resolveImage`，或返回了 `null`                      | 返回通过校验的 `src`；相对图片需 `allowRelativeImages`                                |
| 内部链接不可点击                 | 默认输出不可导航的文本                                        | 用 `resolveLink` 返回 `href`                                                |
| 外链变成普通文本                 | 协议不在白名单                                            | 只使用 `http:`、`https:`、`mailto:`                                           |
| HTML 变成源码卡片              | 标签未知或无法配对                                          | 确认标签是否受支持；自定义语义节点需要注册 `handlers`                                         |
| 危险标签只剩提示                 | `script`、`iframe` 等被拦截                             | 预期行为；不要为了展示放宽 `stripTags`                                                |
| 整张表格变成源码卡片               | wikitext 嵌套表格                                      | 展平嵌套表，或改用 HTML `<table>` 嵌套                                              |
| 段落被合并                    | 单个换行会折叠为空格                                         | 用两个空行分段                                                                  |
| 目录没有出现                   | 标题少于 4 个、`__NOTOC__`、或 `headingIdStrategy: "none"` | 检查标题数量与行为开关；需要固定位置时用 `__TOC__`                                           |
| 引用区不在 `<references>` 的位置 | 引用区固定位于正文之后、分类之前                                   | 预期行为；位置不可通过标签控制                                                          |
| 分类不在正文中                  | 分类汇总到文末底栏                                          | 预期行为；文案由 `labels.categories` 控制                                          |
| 同一页标题锚点冲突                | 多个实例共享裸 id                                         | 用默认 `instance` 策略，或显式传 `idPrefix`                                        |

更多默认输出见[支持矩阵](/zh/guide/syntax-support.md)。

## 运行与构建

| 症状                                               | 原因                                              | 处理                                                                |
| ------------------------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------- |
| `ASYNC_PLUGIN_IN_SYNC_PATH`                      | 同步入口遇到异步插件                                      | 改用 `prepareWikitextAsync`，或在 React 外准备                            |
| 每次渲染都重新解析                                        | `parseOptions` / `prepareOptions` 是内联新对象        | 移到组件外或用 `useMemo` 固定引用                                            |
| `PARSER_UNAVAILABLE`                             | `wikiparser-node` 浏览器包没有初始化 `globalThis.Parser` | 确认打包器执行了副作用导入；避免重复副本或手工裁剪依赖                                       |
| `Cannot find module 'react-wikitext/styles.css'` | 打包器未处理包内 CSS，或产物缺少 `dist/styles.css`            | 让打包器处理包内 CSS 导入；确认解析到 `dist/styles.css`                           |
| Next.js Server Component 报 `createContext` 错误    | 在支持 RSC 边界的环境里由服务端调用了 React 入口                  | 确认产物带有 `"use client"`；服务端改用[服务端准备](/zh/guide/server-rendering.md) |
| Hydration 不一致或锚点不同                               | 服务端与客户端渲染了不同结构，或没有固定 id 前缀                      | 保持同一棵树；显式传 `idPrefix`；必要时用 `mediawiki` 策略                         |
| 类型报错：根入口没有错误类                                    | 错误类按子路径导出                                       | 从 `/parse`、`/hast`、`/expand` 导入对应错误类                              |
| CJS 环境加载失败                                       | 运行时版本过低或打包器不支持 `exports`                        | 使用 Node `>=18.18` 与支持条件导出的打包器                                     |

## 错误码

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

| 错误码                         | 阶段 | 含义                | 处理                                    |
| --------------------------- | -- | ----------------- | ------------------------------------- |
| `SOURCE_TOO_LONG`           | 解析 | 归一化后的源码超过长度预算     | 调大 `maxSourceLength`，或拆分内容            |
| `SOURCE_TOO_COMPLEX`        | 解析 | 节点数或深度超过预算        | 调大对应预算，或简化结构                          |
| `INVALID_CONFIG`            | 解析 | 站点配置或预算字段非法       | 检查传入值是否为非负安全整数                        |
| `PARSE_FAILED`              | 解析 | 上游解析或语义构建失败       | 保留源码与 `cause`，报告问题                    |
| `PARSER_UNAVAILABLE`        | 解析 | 默认浏览器包未初始化        | 检查构建与依赖解析                             |
| `PREPARE_FAILED`            | 准备 | 选项、插件或转换函数非法      | 检查 `policy`、`labels`、`handlers` 与插件签名 |
| `ASYNC_PLUGIN_IN_SYNC_PATH` | 准备 | 同步路径遇到异步插件        | 改用异步入口                                |
| `INVALID_DOCUMENT`          | 恢复 | 快照结构、版本或预算不合法     | 只恢复可信来源；版本升级后让缓存失效                    |
| `EXPANSION_TOO_LARGE`       | 展开 | 展开结果或保留源码超过长度上限   | 调大 `maxExpandedLength`，或限制模板输出        |
| `EXPANSION_BUDGET_EXCEEDED` | 展开 | `strict` 模式下预算超限  | 调大预算，或关闭 `strict` 接受保留调用              |
| `TEMPLATE_LOOP`             | 展开 | `strict` 模式下检测到循环 | 检查模板依赖                                |
| `ABORTED`                   | 展开 | 通过 `signal` 取消    | 预期行为；原始原因在 `cause`                    |

完整错误码与类层次见[错误与诊断](/zh/api/errors.md)。

## 诊断怎么读

```ts
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`。

更多渠道见[参与与反馈](/zh/project/contributing.md)。