Mermaid图表在Markdown预览中不显示？

Question

在使用 Markdown 编写文档时，Mermaid 图表（如流程图、时序图）在预览中不显示是常见问题。通常出现在 VS Code、Typora 等编辑器的实时预览中。主要原因包括：未启用 Mermaid 支持、缺少必要的渲染插件或配置错误。例如，VS Code 需安装支持 Mermaid 的扩展（如“Markdown Preview Enhanced”），并确保 `markdown.preview.mermaid.enabled` 设置为 true。此外，部分静态站点生成器（如 Jekyll、Hugo）需手动集成 Mermaid.js 库才能正确渲染。检查控制台是否报错“mermaid is not defined”可帮助诊断问题。确保网络可访问 Mermaid CDN 或本地正确引入脚本也至关重要。

Answer 1

解决 Markdown 中 Mermaid 图表预览不显示的全链路分析

1. 问题背景与常见表现

在使用 Markdown 编写技术文档时，Mermaid 因其简洁语法支持流程图、时序图、甘特图等可视化图表，已成为现代文档工程的重要组成部分。然而，许多开发者在 VS Code、Typora 等主流编辑器中实时预览时，发现 Mermaid 图表无法正常渲染，仅显示原始代码块或空白区域。

典型现象包括：

• 预览窗口中 Mermaid 代码块未被解析
• 浏览器控制台报错：ReferenceError: mermaid is not defined
• 图表区域出现红色边框或“Parse error”提示
• 静态站点部署后图表仍不显示

2. 根本原因分层剖析

Mermaid 渲染失败的根本原因可划分为三层：编辑器层、运行环境层、构建部署层。

层级	可能原因	影响范围
编辑器层	未启用 Mermaid 支持或插件缺失	VS Code、Typora 实时预览
运行环境层	未正确引入 mermaid.js 脚本	本地 HTML 预览、Web 页面
构建部署层	静态站点生成器未集成 Mermaid	Jekyll、Hugo、Docusaurus 等

3. 编辑器级解决方案（以 VS Code 为例）

VS Code 原生 Markdown 预览默认不启用 Mermaid 支持，需通过扩展增强功能。

1. 安装扩展：Markdown Preview Enhanced 或 Markdown+Math
2. 打开设置（Ctrl+,），搜索 mermaid
3. 确保配置项 "markdown.preview.mermaid.enabled": true
4. 若使用第三方扩展，检查其是否自动注入 mermaid.js
5. 重启预览窗口，验证图表是否渲染

4. Web 运行环境脚本注入

当导出为 HTML 或嵌入网页时，必须手动加载 Mermaid JS 库。

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({ startOnLoad: true });
</script>
    

注意：确保网络可访问 CDN，生产环境建议使用本地化资源或版本锁定。

5. 静态站点生成器集成方案

不同静态站点工具需定制化集成 Mermaid。

工具	集成方式	关键配置
Hugo	在模板 layout 中引入 mermaid.js	添加 script 到 baseof.html
Jekyll	使用插件 jekyll-mermaid 或自定义 include	_includes/mermaid.html
Docusaurus	通过 plugins 添加 @docusaurus/theme-mermaid	docusaurus.config.js 配置

6. Mermaid 流程图示例验证

以下是一个标准 Mermaid 流程图语法，用于测试渲染能力：

mermaid
    graph TD
        A[开始] --> B{条件判断}
        B -->|是| C[执行操作]
        B -->|否| D[结束]
        C --> E[保存结果]
        E --> D
    

7. 调试技巧与诊断流程

当图表仍不显示时，应遵循以下诊断路径：

graph LR
            A[图表未显示] --> B{是否在编辑器中?}
            B -->|是| C[检查插件与设置]
            B -->|否| D[检查HTML是否引入mermaid.js]
            C --> E[确认mermaid.enabled=true]
            D --> F[查看控制台错误]
            F --> G[是否有'is not defined'?]
            G -->|是| H[脚本未加载]
            G -->|否| I[检查语法错误]
            H --> J[修复CDN或本地引用]

8. 高级配置与性能优化

对于企业级文档系统，建议进行如下优化：

• 使用 Mermaid CLI 预渲染为 SVG，减少客户端负担
• 配置 securityLevel: 'loose' 以支持交互式图表（需评估 XSS 风险）
• 通过 themeConfig 自定义图表样式，保持品牌一致性
• 在 CI/CD 流程中加入 Mermaid 语法校验步骤