跳到主要内容
版本：Current

常见错误

构建失败​

找不到文档 ID​

现象：npm run build 报错 Document with ID "xxx" not found

原因：sidebars.ts 引用了不存在的 doc ID，或文件路径 / 大小写不匹配

解决：

  1. 确认 docs/ 下文件存在
  2. doc ID = 相对 docs/ 的路径，去掉 .md，使用 / 分隔
  3. 修正 sidebars.ts 中的 ID

Markdown / MDX 语法错误​

现象：构建报错指向某行 MDX 解析失败

原因：未转义的 {、<、组件语法冲突

解决：纯文档尽量用 .md；特殊字符用反引号包裹或转义

现象：onBrokenLinks 警告

原因：文内链接指向已删除或错误路径

解决：改为正确路径，或使用相对 doc 链接如 ./Other-Page

本地预览​

修改 sidebar 不更新​

解决：重启 npm start，或使用 npm run build && npm run serve

Mermaid 不显示或换行异常​

原因：未在 config 启用 mermaid，或节点内用了 \n

解决：确认 docusaurus.config.ts 已配置 mermaid theme；节点换行用 <br/>

部署​

wrangler deploy 认证失败​

解决：

npx wrangler login

或在 CI 中配置 CLOUDFLARE_API_TOKEN

部署后内容未更新​

原因：浏览器缓存或 CDN 缓存

解决：硬刷新；Cloudflare Dashboard 清除缓存；确认 deploy 的是最新 build

i18n​

英文页面缺失​

原因：仅翻译了 UI，未在 i18n/en/docusaurus-plugin-content-docs/current/ 添加对应 md

解决：补充镜像路径翻译文件，或暂时只保留中文 locale