简介：Mermaid.js v10.6.1 压缩版 JavaScript 库，面向前端开发者与文档撰写者，通过简洁文本语法即可生成流程图、时序图、类图、甘特图等专业图表，免去手动绘制与拖拽的繁琐，显著提升文档和 Web 应用中的可视化效率。压缩包体积 851KB，包含 1 个 mermaid.min.js 文件，无额外运行时依赖，可直接引入项目完成图表渲染，尤其适合内网、离线或加载速度受限的环境。目前已有 502 人学习下载，作为 v10.6.1 稳定版本，其社区生态与 Jira、GitLab、VS Code 等主流工具的兼容性也较为成熟。获取后即可获得该版本的完整压缩文件，既能快速搭建图表原型，也能直接嵌入生产项目；配合 Mermaid 文本语法，复杂图表的创建、更新与协作都更加高效，降低重复绘图与沟通成本。 上周我把内部工单系统的流程审批模块重构了一遍，核心就是用 JavaScript 加载本地化的 Mermaid 渲染环境，把原本散落在文档里的几十条审批链路全部转成了可交互的流程图。整套方案落地后最大的感受是：Mermaid 的威力不只在它能把文本变成图，而在于它的渲染流程、安全策略、版本行为都直接影响你写业务代码的方式。这篇文章就围绕 Mermaid v10.6.1.min.js 这套渲染工具，把我踩过的坑、验证过的写法、以及最终能直接抄走的配置一并整理出来，适合要在 Vue、React 或原生 JavaScript 项目里接入流程图可视化、并且希望离线部署或做定制渲染的团队参考。
1. 为什么前端项目要选 Mermaid v10.6.1 而不是别的方案
1.1 先看清三套方案的取舍
我在开始动工之前，把市面上主流的流程图可视化方案重新过了一遍，最终留在候选清单里的有三类：Mermaid、PlantUML、以及基于 SVG/D3 的手写渲染。三者不是同一个维度的东西，但正因为维度不同，选型时的判断逻辑就变得很清晰。
| 方案 | 上手门槛 | 可定制性 | 交互能力 | 适合场景 |
|---|---|---|---|---|
| Mermaid | 低，写文本即可 | 中，支持主题变量和配置 | 可通过事件绑定实现 | 文档、业务流程图、快速可视化 |
| PlantUML | 中，语法有自己的体系 | 中，偏 UML 建模 | 弱，偏静态导出 | 时序图、类图、UML 建模 |
| 手写 SVG | 高，需要自己处理布局 | 高，完全可控 | 高，任意交互 | 复杂交互图、定制引擎 |
对于内部系统这种“流程经常微调、需求变化快、开发资源有限”的场景，手写 SVG 的维护成本实在太高，PlantUML 又更偏向设计阶段而非线上运行时渲染。Mermaid 恰恰卡在中间：文本即代码，改一句描述就能改整张图，同时 JavaScript API 足够完善，能够嵌入现有业务系统，做到动态渲染和事件交互。
1.2 v10.6.1 这个版本有什么值得被记住的
需要强调的是，Mermaid 从 v10 开始做了几个较大的架构调整，这些调整直接影响业务代码的写法，也是我在实际开发中发现很多教程已经失效的原因。
- render 方法变成异步。v10 之前
mermaidAPI.render('id', text)可以同步拿到 svg 字符串，v10 之后必须await mermaid.render(...)，返回的是一个 Promise。 - ESM 化。v10 的 dist 目录里同时存在
mermaid.min.js（UMD 风格全局脚本）和mermaid.esm.min.mjs（ES Module），引入方式不同，挂载到全局的方式也不同。 - 安全策略默认收紧。v10 之后
securityLevel默认是strict，HTML 标签会被剥离，click事件默认也不再生效，必须显式配置。 - 内置 dayjs 等依赖被移除或调整，体积可控，对离线部署更友好。
我选择固定使用 v10.6.1 而非追最新版，原因很朴素：这套 API 行为在当前版本已经稳定，社区里踩坑记录足够多，出问题时能快速定位。内部系统最怕的是“今天能跑，明天升级后白屏”，所以锁定版本、把文件放到本地静态目录，是更稳妥的做法。
2. 搭建最小可用环境：下载、引入、首次渲染
2.1 把 v10.6.1.min.js 弄到本地资源目录
由于内部系统部署在内网，没法依赖公网 CDN，所以第一步是把渲染工具下载到本地。我推荐三种方式，按使用频率排序：
- 通过 npm 下载：在项目里执行
npm install mermaid@10.6.1，装完后去node_modules/mermaid/dist/目录找到mermaid.min.js或mermaid.esm.min.mjs，复制到自己的src/assets/vendor/mermaid/目录下。 - 直接用 curl 从 CDN 拉取：
curl -o mermaid.min.js https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js，然后把文件扔进项目静态目录。 - 浏览器手动另存，这种方式多在临时验证时用，不推荐作为工程化实践。
下载完成后，建议在项目里固定引用路径，例如src/assets/vendor/mermaid/v10.6.1/mermaid.min.js，这样版本一目了然，后续升级只需要替换目录即可。
2.2 script 全局引入与 ES Module 引入
如果你的项目是传统多页应用或不想引入打包工具，可以直接用script标签全局引入：
<script src="/assets/vendor/mermaid/v10.6.1/mermaid.min.js"></script> <script> // mermaid 已经挂载到全局对象上 window.mermaid.initialize({ startOnLoad: false }); </script>如果你用的是 Vite、Webpack 这类构建工具，更推荐用 ES Module 的方式：
import mermaid from './assets/vendor/mermaid/v10.6.1/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: false, theme: 'base', securityLevel: 'strict' });两种方式的核心差异在于作用域和打包体积。script全局引入会让mermaid出现在window上，调试方便，但会污染全局命名空间。ES Module 方式更干净，能被 tree-shaking 处理掉无用代码，缺点是如果你没用构建工具，浏览器原生 ESM 的老版本兼容性需要注意。
2.3 initialize 配置与 20 行内的首屏渲染
我习惯先把最基础的渲染函数写好，保证任何页面想画流程图时都能直接调用。下面这段代码是经过实际项目验证的最小可用版本：
// flowRenderer.js let mermaidInstance = null; export async function initMermaid() { if (mermaidInstance) return mermaidInstance; const mermaid = (await import('./assets/vendor/mermaid/v10.6.1/mermaid.esm.min.mjs')).default; mermaid.initialize({ startOnLoad: false, theme: 'base', securityLevel: 'strict', fontFamily: 'PingFang SC, Microsoft YaHei, sans-serif' }); mermaidInstance = mermaid; return mermaidInstance; } export async function renderFlow(text, containerId) { const mermaid = await initMermaid(); const { svg, bindFunctions } = await mermaid.render(`flow_${Date.now()}`, text); const container = document.getElementById(containerId); container.innerHTML = svg; if (bindFunctions) bindFunctions(container); return container; }这段代码里有几个关键点需要说明。startOnLoad: false是必须的，否则 Mermaid 会在 DOMContentLoaded 之后自动扫描页面里所有 class 为mermaid的节点，这在 SPA 里很容易导致重复渲染或渲染时机不可控。theme: 'base'让后续配色完全由我们自己控制，不依赖默认主题的绿、红配色。fontFamily必须显式设置成中文字体，否则在部分 Linux 服务器环境下渲染出来的中文会出现锯齿甚至乱码。渲染 id 加了时间戳是为了避免同一页面重复用同一个 id 导致 DOM 冲突。
3. 从能跑到好用：动态渲染、主题定制与交互
3.1 动态渲染：把用户输入的流程文本变成图
接入业务系统后，最常见的场景是：用户在后端定义流程节点，前端拿到描述文本后实时渲染成流程图。我在工单系统里做了一个预览面板，左侧是流程描述编辑器，右侧是实时渲染区域。
实现思路很简单：监听文本变化，做 300ms 防抖，然后调用renderFlow。这里有个一开始没注意的细节——mermaid.render()返回的svg字符串是包含完整<svg>标签的，包括xmlns和viewBox，你完全可以直接赋值给容器的innerHTML。我之前一直以为它只返回内部图形部分，结果最初接的时候把<svg>又包了一层，导致样式错位。
当容器尺寸不固定时，Mermaid 默认会根据内容自动计算宽高。实测下来，如果想让流程图宽度自适应容器、高度按比例增长，可以用viewBox做缩放，但更省事的做法是渲染完成后读取svg.getBBox()，再手动设置容器的height。因为 Mermaid 生成的 svg 自身携带了 width/height 属性，直接用 CSS 把 width 设为 100% 并不会让内部图形跟着缩放，这点很多人会忽略。
3.2 主题样式定制：让流程图融入现有设计体系
默认的 Mermaid 主题是蓝色系，但内部系统的视觉规范是橙红色强调色，直接使用会觉得跟页面格格不入。好在theme: 'base'模式下可以通过themeVariables覆盖大部分关键颜色：
mermaid.initialize({ startOnLoad: false, theme: 'base', securityLevel: 'strict', themeVariables: { primaryColor: '#fff7f2', primaryTextColor: '#333333', primaryBorderColor: '#f0623a', lineColor: '#999999', fontSize: '14px', clusterBkg: '#fafafa', clusterBorder: '#dddddd' } });这些变量控制的是流程图最基础的视觉层面。primaryColor是节点背景色，lineColor是连线颜色，clusterBkg是子图背景色。我觉得最省时的方式是先打开浏览器控制台，用 Mermaid 渲染一张示例图，然后逐个改themeVariables看实时效果，定稿后再固化到配置里。
还有一个细节：节点内文字换行。Mermaid 语法里用<br>标签换行在strict模式下会被过滤掉，所以换行应该用语法自带的\n转义，或者在节点 label 里直接使用一段带换行的文本。v10.6.1 对<br>的处理比较严格，实测下来把securityLevel调到loose才能保留，但 loosen 又会有 XSS 风险，所以更推荐在文本生成阶段就处理好换行。
3.3 点击节点触发流程，bindFunctions 是怎么用的
业务场景里经常需要“点击某个节点查看审批人详情”“点击连线查看流转记录”。Mermaid 从 v10 开始，在render的返回值里提供了bindFunctions回调，用它来绑定事件是最规范的方式。
const { svg, bindFunctions } = await mermaid.render(id, text); container.innerHTML = svg; if (bindFunctions) { bindFunctions(container); }绑定之后，节点上的click事件才会被正确代理。要注意的是，bindFunctions需要在innerHTML赋值之后立刻调用，而且每次重新渲染都要重新绑定一次，否则旧的事件绑定会被新 DOM 覆盖掉。我在这上面栽过跟头：第一次渲染后点击正常，第二次渲染后点击无反应，排查了半天发现是绑定的还是旧 DOM 的引用。
如果需要在strict模式下实现节点跳转，我推荐的做法是：给每个节点设置一个稳定的id（比如审批节点编码），然后在mermaid.initialize里配置securityLevel: 'strict'，不让 Mermaid 执行用户传入的 JS 回调，而是在bindFunctions之后用事件委托手动监听。
container.addEventListener('click', (e) => { const node = e.target.closest('.node'); if (!node) return; const nodeId = node.id; // nodeId 即 flow 中定义的节点 id handleNodeClick(nodeId); });这样既保留了strict的安全保护，又实现了点击交互，是目前实测最稳的方案。
4. 嵌入复杂业务页面时，绕不开的四个细节
4.1 小心 render 返回的 svg 带 BOM
第一次把渲染好的 svg 塞进页面时，我遇到过一个诡异问题：图片能显示，但用DOMParser解析时总是报错，说格式不合法。排查到最后发现是 Mermaid 返回的 svg 字符串开头带了一个 BOM（Byte Order Mark）字符\uFEFF，导致 XML 解析器识别异常。
解决方案也很简单，拿到 svg 后统一做一次清洗：
const cleanSvg = svg.replace(/^\uFEFF/, ''); container.innerHTML = cleanSvg;这个坑在本地文档里几乎不会提到，因为正常innerHTML赋值时浏览器会自动忽略 BOM，但一旦你把 svg 字符串传给图表库、导出工具、或者做字符串拼接，BOM 就会变成隐患。建议在封装渲染函数时统一处理掉，而不是等到出了问题再追。
4.2 渲染容器隐藏和懒加载的尺寸问题
Mermaid 在渲染时会读取容器尺寸来计算布局。如果容器处于display: none状态，或者还没有挂载到文档流里，渲染出来的 svg 的viewBox可能会异常，最常见的表现是图形错位、上下挤压、或者整体被截断。
我在工单系统的 Tab 页签里碰到过两次。第一次是默认展示第二个 Tab，但流程图容器在第一个 Tab 里，初始化时拿不到正确尺寸，切回来发现图是扁的。第二次是对话框里放流程图，对话框未打开前display: none，打开后渲染发现连线全部挤在一起。
标准解法是：确保容器可见后再调用renderFlow。如果你用的是 Element Plus 的 Tab 或 Dialog，可以监听tab-change或opened事件，在回调里再执行渲染。如果必须提前渲染，至少要把容器的宽高固定住，不要让 Mermaid 自己在 0 尺寸下计算。
4.3 安全性：strict 与 loose 该怎么选
Mermaid 文档里对这个配置讲得比较简单，但实际使用中它直接影响你的页面能不能被注入脚本。loose模式会保留 HTML 标签和click事件回调，方便是方便，如果流程文本是后端拼接或用户输入，很容易被塞进恶意脚本。
我的选择是：内部系统虽然信任环境，但依然保持strict，把交互统一走事件委托。这样即使某个节点的 label 被写入了异常内容，也只会显示为纯文本，不会执行任何脚本。团队里如果有人确实需要click回调，我会建议单独开一个白名单接口，由后端做内容审核后再进入渲染流程。
4.4 版本一致性：同一页面多个 mermaid 副本导致的“undefined”
这个问题在组件化开发时容易出现。项目里如果同时存在 package.json 安装的 Mermaid 和手动下载的 v10.6.1.min.js，并且都在初始化时被调用，很容易出现“mermaid 未定义”或“Mermaid API 初始化失败”的报错。本质是某个打包产物拿到的模块作用域和运行时挂载的全局对象不一致。
我经历过的具体场景：Vue 项目里 package.json 已经装了 mermaid@9，但我为了用 v10 特性又手动引了一个 v10 的全局脚本，结果全局window.mermaid是 v10，组件里 import 的却是 v9，两边 API 行为不一致，排查了很久才定位。最终处理方式是彻底删掉 package.json 里的旧依赖，统一用本地 vendor 文件，并在一开始就封装好initMermaid单例，避免多个副本初始化。
5. 高频报错与排查实录
5.1 新手最容易碰到的 6 个提示
下面这个表是我在支持同事接入时整理出来的高频问题，基本覆盖了大部分“百度不到答案”的报错类型：
| 错误现象 | 直接原因 | 解决建议 |
|---|---|---|
mermaid is not defined | 全局脚本未加载，或加载顺序在调用之后 | 检查 script 标签顺序，确保先加载库再执行调用 |
Cannot read properties of undefined (reading 'render') | 多个 mermaid 副本冲突，或 import 路径指错 | 确认 vendor 文件路径，统一用单例入口 |
| 页面白屏，控制台无报错 | 容器 id 重复，或render的 id 和已有 DOM 冲突 | 给 render 的 id 加时间戳或随机后缀 |
| 中文变成方块 | 服务器字体缺失或未设置 fontFamily | initialize 里显式配置中文字体，并把字体文件挂到全局 |
| 渲染的图被压缩 | 容器宽度为 0 或display: none时初始化 | 容器可见后再调用渲染，或固定容器宽高 |
Syntax error in text但语法看着没问题 | 文本中的引号、反引号被模板字符串吃掉了 | 用模板字符串时注意转义，或改用普通字符串拼接 |
5.2 三个我反复踩的坑
第一个坑是模板字符串拼接语法时，反引号和${}被提前解析。Mermaid 语法本身支持${}这种符号吗？其实流程文本里如果有变量占位，很容易和 JavaScript 模板字符串冲突。比如我想在节点 label 里写${startTime}，直接在反引号包住的模板字符串里写，就会被 JS 当成变量执行。解决方法是先把要替换的变量算好，再用占位符拼接，别让运行时再去解析。
第二个坑是render的 id 重复。Mermaid 内部会拿这个 id 查找或创建 DOM 节点，如果同一个 id 被渲染两次，第二次往往就报错。我最初用固定 id 在循环里渲染多个流程图，结果第一个正常，第二个开始全是偶发报错。改成flow_${Date.now()}_${index}之后彻底解决了。
第三个坑是v-if和v-show对渲染结果的影响。在 Vue 里，如果v-if为假就把容器销毁，那么渲染好的 svg 也会被销毁，下次切换回来又得重新渲染。用v-show则不会销毁 DOM，但要注意隐藏时如果调renderFlow，又会触发 4.2 节的尺寸问题。我的建议是：容器用v-show控制显隐，渲染时机统一放在首次显示之后，用一个hasRendered标记避免重复渲染。
最后再分享一个小技巧：如果团队里有多个项目都要用 Mermaid，可以把这个渲染函数直接封装成 npm 包或公共组件，入参只留三个——流程文本、容器 id、主题配置。这样能保证所有页面用同一套安全策略和事件绑定逻辑，后续升级 v10.6.1 到更高版本时，只需要改一个地方，业务代码完全无感。
本文还有配套的精品资源，点击获取
