调试与限制

大部分问题都落在四类里：Mermaid 语法错误 字体缺失 导出限制 与宿主生命周期时机

渲染失败

Mermaid 解析失败时，运行时会显示简短的错误回退

排查顺序

• 先确认 fence 语言标记确实是 mermaid
• 再确认源码符合对应图形的 Mermaid 语法
• 最后确认 Excalidraw 没有被当成自定义 DSL 的解析器使用

字体问题

字体问题大多属于宿主侧问题

• 确认样式表或 @font-face 在渲染前已经加载
• 确认配置里的字体族名与实际加载的 family 完全一致
• 确认混合脚本场景只在必要时才引入回退链

导出限制

PNG 导出会主动保护浏览器，避免极端 canvas 尺寸拖垮页面

• 最小导出倍率：2
• 最大位图边长：8192 px
• 最大像素预算：约 1600 万像素

大图仍然可以导出，只是倍率可能会被主动压低

路由相关问题

如果自定义布局把 wrapper 插入得太晚，VitePress 仍可能在默认重试窗口外错过它

第一把手通常是 waitFor: 'animation-frame'

第二把手通常是更精确的 root 作用域