Mermaid.js 渲染失败主因是加载顺序与初始化时机错误，需确保 DOM 加载完成后再调用 mermaid.initialize（传 { startOnLoad: false }），动态插入代码须手动 run()；时序图中文乱码源于字体缺失，应配置 CSS font-family；类图继承箭头需用
Mermaid.js 流程图渲染失败，mermaid.initialize 报错或图表不显示
多数情况是脚本加载顺序或初始化时机不对。Mermaid 不会自动扫描页面，必须显式调用 mermaid.initialize，且需等 DOM 加载完成后再执行。
- 确保
mermaid.min.js在底部加载，或监听DOMContentLoaded - 初始化时至少传入
{ startOnLoad: false }，否则它会尝试立即渲染所有pre code块，但此时可能还没插入内容 - 若用
innerHTML动态写入 Mermaid 代码块，必须手动调用mermaid.run()（v10+）或mermaid.render()（旧版），不能依赖自动触发 - 常见错误：
TypeError: mermaid.initialize is not a function—— 检查是否引入了压缩版但没带核心模块，或 CDN 地址返回 404（如误用了 unpkg 的未构建版本）
时序图（sequenceDiagram）里参与者文字换行或中文乱码
Mermaid 默认对 participant 名称做截断和单行渲染，中文支持依赖字体和 SVG 渲染后端，不是语法问题而是环境配置问题。
- participant 名称中不要用空格或特殊符号；如需多词，用连字符或下划线，例如：
participant User_API - 换行需用
<br>（仅在 v10.6.0+ 支持），写成participant "Frontend<br>Client"，但注意：这依赖浏览器 SVG 的 HTML 解析能力，部分旧版 Safari 不支持 - 中文乱码本质是字体缺失：Mermaid 渲染为 SVG，而 SVG 默认用系统无衬线字体；若系统无中文字体（如某些 Linux 容器或 headless 环境），就会 fallback 到方框；解决方式是在 CSS 中全局指定
font-family: "Microsoft YaHei", sans-serif，并确保该字体可用 - 避免在
activate或note中直接写长段中文，优先拆短句，或改用note right of XXX+ 简洁标注
类图（classDiagram）继承箭头不显示或关系线错位
Mermaid 类图对语法缩进和关键字大小写敏感，且不同版本对 UML 兼容性差异大（尤其是 v10 对 o、|| 等角色标记支持不一致）。
- 继承必须用
（子类指向父类），不能写反；实现接口用 <code>.>o，且箭头右侧必须是接口名，例如：Car - v10 默认启用「新布局引擎」（Elk），可能导致旧图错位；临时关闭可加配置：
mermaid.initialize({ layout: { useMaxWidth: false, elkglobals: { "elk.algorithm": "layered" } } }) - 类成员字段/方法若含括号或泛型（如
List<string></string>），需用反斜杠转义尖括号：List\<string></string>，否则解析中断 - 避免在 class 定义块内混用空行和注释；Mermaid 会把空行当作区块分隔，导致后续关系被忽略
用 pre+code 写 Mermaid 代码但渲染结果偏移或样式混乱
Mermaid 渲染后生成的是内联 SVG，其容器宽度默认由父元素决定，而 pre 的 white-space 和 padding 会干扰尺寸计算。
立即学习“前端免费学习笔记（深入）”；
- 务必给包裹 Mermaid 代码的
pre加class="mermaid"（Mermaid v10 默认只识别这个 class 触发渲染） - 不要给
pre或code设置固定width或overflow，SVG 宽度由内部内容撑开；如需限制宽度，应设在外层div并启用响应式缩放：style="max-width: 100%; overflow: auto;" - 若页面有 CSS 重置（如 normalize.css），可能清除了
pre的 margin；Mermaid 渲染后 SVG 无 margin，会导致相邻段落贴得太近，建议单独加margin-bottom: 1em给.mermaid - 主题色不生效？v10 起默认禁用内联 style，改用
mermaid.initialize({ theme: 'dark' })或通过 CSS 变量控制，如--mermaid-primary-color: #2c3e50
Mermaid 的实际落地难点不在语法，而在加载链路、字体上下文和 SVG 渲染边界——这些地方一卡，整张图就静默失败。调试时优先检查控制台报错类型，再看 network 是否加载了 JS 和字体资源，最后才动语法。
