For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/api/errors.md.
react-wikitext
  • 中文

      • 错误与诊断

      库区分两类信号：

      • 错误（Error）：当前调用无法继续，抛出异常；需要调用方捕获。
      • 诊断（WikitextDiagnostic）：单点问题或降级记录，写入快照，不中断整页渲染。

      错误类

      class WikitextError extends Error {
  readonly code: WikitextErrorCode;
  cause?: unknown;
}

class WikitextParseError extends WikitextError {}

class WikitextPrepareError extends WikitextError {
  readonly stage: string;
}

class WikitextExpandError extends WikitextError {
  readonly templateTitle?: string;
  readonly range?: WikitextRange;
}

      所有错误都带 code；cause 保留底层异常。WikitextPrepareError.stage 记录失败阶段，常见值为 prepare、wikitext、rehype 与 finalize。

      按入口导出

      入口错误导出
      /ast、/parseWikitextError、WikitextParseError、WikitextErrorCode
      /hastWikitextError、WikitextPrepareError
      /expandWikitextError、WikitextExpandError、WikitextExpandErrorCode
      根入口、/view不导出错误类；渲染异常由错误边界处理

      错误码

      错误码阶段触发条件
      SOURCE_TOO_LONG解析归一化后的源码超过长度预算
      SOURCE_TOO_COMPLEX解析语法树或语义树超过节点/深度预算
      INVALID_CONFIG解析站点配置或预算字段非法
      PARSE_FAILED解析上游解析或语义构建失败
      PARSER_UNAVAILABLE解析默认浏览器包未初始化全局解析器
      PREPARE_FAILED准备选项、插件、转换函数或预算校验失败
      ASYNC_PLUGIN_IN_SYNC_PATH准备同步入口遇到异步插件
      INVALID_DOCUMENT恢复/准备快照结构、版本、根节点或预算不合法
      INVALID_EXPAND_OPTIONS展开展开选项非法
      INCOMPATIBLE_PARSER展开注入的解析器不满足展开要求
      TEMPLATE_NOT_FOUND展开strict 模式下模板缺失
      TEMPLATE_RESOLVE_FAILED展开strict 模式下解析函数失败
      TEMPLATE_PARSE_FAILED展开strict 模式下模板源码解析失败
      TEMPLATE_LOOP展开strict 模式下检测到循环
      UNSUPPORTED_CALL展开strict 模式下遇到不支持的调用
      UNRESOLVED_DEPENDENCY展开strict 模式下依赖未解析
      EXPANSION_BUDGET_EXCEEDED展开strict 模式下预算超限
      EXPANSION_TOO_LARGE展开展开结果或保留源码超过长度上限
      FINAL_PARSE_FAILED展开strict 模式下最终解析失败
      ABORTED展开通过 AbortSignal 取消

      展开阶段在默认模式下会尽量保留调用并记录诊断；strict: true 时上述可恢复错误改为抛出。

      处理示例

      import { WikitextParseError } from "react-wikitext/parse";

try {
  const document = parser.parse(source, { pageName: "Example" });
  return document;
} catch (error) {
  if (error instanceof WikitextParseError) {
    if (error.code === "SOURCE_TOO_LONG") {
      return loadSourceInPages(source);
    }
    throw error;
  }
  throw error;
}
      import { prepareWikitextAsync, WikitextPrepareError } from "react-wikitext/hast";

try {
  return await prepareWikitextAsync(document, { rehypePlugins });
} catch (error) {
  if (error instanceof WikitextPrepareError) {
    report(error.code, error.stage, error.cause);
  }
  throw error;
}
      • 不要根据 message 文本分支；使用 code（必要时加上 stage）。
      • 解析与准备错误应在调用层捕获，并区分预算、配置与插件问题。
      • 视图渲染错误通过 onRenderError 上报；错误边界只替换失败的顶层块。
      • 恢复快照失败不应静默降级为重新解析；先确认版本与来源。

      诊断

      interface WikitextDiagnostic {
  readonly code: string;
  readonly stage: "parse" | "expand" | "wikitext" | "hast" | "rehype" | "sanitize" | "finalize";
  readonly severity: "error" | "warning" | "info";
  readonly message: string;
  readonly position?: WikitextPosition;
  readonly origin?: WikitextOrigin;
  readonly rule?: string;
}
      • position 与 origin 基于归一化后的源码；生成内容可能没有来源。
      • rule 标识产生诊断的规则或插件。
      • 渲染快照的 diagnostics 合并了解析、准备与最终整理阶段的记录。
      • 单条诊断不会中断整页渲染；是否上报、是否阻断由宿主决定。

      相关