简介Mermaid.js 10.6.1 压缩版是一款借助简洁文本标记即可渲染流程图、序列图、甘特图、类图等多种图表的 JavaScript 库旨在帮助前端开发者、技术写作者和数据分析人员在网页、文档或报告中快速创建专业图表省去手工绘图和调整样式的繁琐过程。压缩包采用 ZIP 格式内含单个 mermaid.min.js 文件合计约 851KB为经过优化的稳定版本由于是压缩后的独立脚本无需安装额外依赖或访问外部 CDN在离线、内网或弱网环境下同样能正常完成图表渲染。目前已有 502 人学习/下载该版本被众多项目采用社区关注度较高。获取后可直接引用到前端项目通过文本描述即时生成多种图表极大简化可视化流程同时 Mermaid 具备可扩展架构可与 VS Code、Jira、GitLab 等工具链结合在原型设计、功能展示、数据分析等场景中显著提高开发与协作效率。 我最近在做一个内部流程引擎的管理后台需求是把节点状态用图展示出来。领导丢给我一句话“搞个流程图可视化要能自动更新。”我刚听到的时候还挺开心结果一查方案就有点懵手写 SVG 太费劲ECharts 画流程图要自己摆坐标Graphviz 又绕。最后绕了一圈还是回到 Mermaid——具体版本是 v10.6.1.min.js。这篇内容就是我做这个功能时攒下来的实操记录从选型、语法、渲染链路、动态刷新到主题定制基本把 Mermaid v10.6.1 这套整明白了。不管你是要做运维流程图、审批流可视化还是想在文档站里嵌入图表这篇都能当一份可以直接抄作业的参考。1. 为什么折腾一圈我还是选了 v10.6.1 这个版本做流程图1.1 先把话说明白Mermaid 到底解决什么问题Mermaid 是一个纯前端看图工具它把一段类似文本的图表描述语言渲染成 SVG 图形。简单说你给它一行A -- B它给你画出一个带箭头的流程图。写图表的人只需要关注内容结构不需要关心坐标、连线算法和图形布局。我见过很多人第一次接触 Mermaid 时问同一个问题“它和 Draw.io 有什么区别”Draw.io 是拖拽式Mermaid 是写代码式。拖拽式的好处是所见即所得坏处是“图表状态难以和程序数据联动”。Mermaid 的优势恰恰在于图表本身就是一段文本你可以从接口拿数据再拼接成这段文本页面刷新就完成重绘。这对管理后台、监控面板这类场景简直是命中要害——节点状态变了前端代码一变图就跟着变。1.2 v10 是一次重构分水岭如果你翻过 Mermaid 的历史版本会发现 v9 和 v10 之间变化非常大。v10 把整个渲染器用 ESM 方式重构了一遍核心能力被抽成了更干净的模块懒加载 diagram 类型成为正式特性mermaid.render()也彻底改成了 Promise 风格。v10.6.1 这个版本算是我实测里最稳的一个小版本。用它接 Vue 和原生 HTML 页面都没出过幺蛾子。再往后的 v11 我也试过虽然兼容性做得好但一些老项目的构建工具链还得跟着升级成本略高。所以如果你的目标是“快速跑通、稳定上线”v10.6.1 是一个非常合适的落点。另外标题里那个min.js指的是压缩后的浏览器全量包。它把 Mermaid 所有 diagram 类型都打包进去了全局引入后直接用mermaid这个变量不需要再编译什么前端工程。开发调试、写 Demo、给运维临时页面插一段渲染能力的时候这种方式就非常舒服。1.3 和主流方案对比我的取舍逻辑方案上手成本数据联动自定义程度适合场景Mermaid低中中文档、流程可视化、审批流ECharts 自定义图中高高大数据量、强交互图表antv/x6 / LogicFlow高高高可视化编辑器、画布拖拽Graphviz中低偏后端高离线渲染复杂图我的判断很直接如果需求是“把流程图画出来节点状态能跟着数据变”但没有拖拽编辑、没有自定义连线交互这些重需求Mermaid 就是性价比最高的选择。它不介入你的业务状态管理也不维护节点对象它只负责“字符串进去SVG 出来”这一件事。这也是它最大的优点简单。2. 流程图渲染链路从 text 到 SVGMermaid 到底做了什么2.1 最简调用流程Mermaid 的使用逻辑其实就是一条链路初始化配置 - 传入图表文本 - 得到 SVG 字符串 - 塞进页面容器。核心代码不长import mermaid from mermaid; mermaid.initialize({ startOnLoad: false, theme: base, securityLevel: strict }); const { svg } await mermaid.render(graphDiv, flowchart LR A[开始] -- B{是否通过} B --|是| C[发布] B --|否| D[驳回] ); document.getElementById(container).innerHTML svg;这里有一个容易误会的点mermaid.render(graphDiv, text)的第一个参数不是真正的 DOM 容器 ID而是 Mermaid 内部用来临时挂载解析结果的占位 ID。真正把图显示到页面上是最后那一步把svg字符串写入你自己的容器。所以我建议把render的返回值用变量接住再插入不要指望它自动往某个元素里画。2.2 flowchart 语法核心既然标题核心是流程图那直接记 flowchart 相关的语法就能覆盖 80% 的需求节点形状A[方框]A(圆角节点)A{菱形判断}A((圆形))A不对称]连线A -- B带箭头A --- B不带箭头A -.- B虚线A 加固 B粗线A -- 文字 -- B连线带标签子图区域flowchart TB subgraph 主流程 A[开始] -- B[处理] end subgraph 异常分支 B -- C[报错] end方向关键字LR表示左右走向TB表示从上到下走向。我在实际使用中踩过一个小坑节点 ID 千万别用中文也别带空格。比如开始[开始]这种写法在某些版本里会解析失败。虽然 v10 对文本内容的容忍度高了不少但节点 ID 建议还是用字母、数字、下划线需要展示的文字放到方括号里。2.3 渲染链路里最容易忽略的一个前置条件Mermaid 渲染 SVG 之前需要知道容器大概的尺寸。如果容器处于display: none状态或者还没插入 DOM渲染出来的 SVG 尺寸往往会变成 0。我做弹窗里的流程图时遇到过这个问题弹窗用 Vue 的v-show控制显隐第一次打开弹窗图是完整的关上再打开图宽高就塌了。原因就是页面初始化时mermaid.initialize()已经执行弹窗显示之前图已经渲染完了但容器宽度当时还是 0。解决方式很简单弹窗真正显示之后再调mermaid.render()并重新插入 SVG。3. 三种接入方式实测script 标签、npm 包和本地文件各有各的坑3.1 最稳的方案script 标签 全局变量如果只是在一个普通页面里用直接引 CDN 是最快的script srchttps://cdn.jsdelivr.net/npm/mermaid10.6.1/dist/mermaid.min.js/script script mermaid.initialize({ startOnLoad: true }); /script这种方式的坑不在 Mermaid而在 CDN 资源路径。v10 的 dist 目录里产物很多有mermaid.min.js、mermaid.core.min.js、mermaid.esm.min.mjs。mermaid.min.js是 UMD 构建引入后直接挂一个mermaid全局变量最不容易出错。mermaid.esm.min.mjs是 ES Module 版本必须配合script typemodule才能用别搞混。3.2 npm 方式与 mermaid.core 的区别工程化项目里一般用 npm 安装npm install mermaid10.6.1引入时注意包名默认路径import mermaid from mermaid;npm 包里有mermaid和mermaid.core两个入口。mermaid.core是未注册任何 diagram 类型的精简核心配合按需注册 diagram 使用能省不少体积。日常项目直接 importmermaid就行它会自动注册所有内置图类型。如果打包出来体积太大再考虑把mermaid换成mermaid.core手动引入用到的图类型import mermaid from mermaid/dist/mermaid.core;3.3 构建工具的大坑动态 import 的 base 路径这是我最想提醒你的一件事。Mermaid v10 为了实现懒加载内部会动态 import 一些模块。在 Vite 或 Webpack 工程里如果打包输出的静态资源路径配得不对浏览器运行时会出现Failed to fetch dynamically imported module的报错现象是页面白屏、图完全出不来。我在 Vite 项目里部署到子目录时踩过这个坑。解决办法是配置 Vite 的base路径让它和部署路径一致。Vite 的base默认是/如果你的页面部署在https://example.com/admin/下就要在vite.config.js里设置base: /admin/。这类问题不是 Mermaid 本身的 bug但它会表现得像个 bug排查起来很费时间建议直接记住这个前提。3.4 本地直接双击 HTML 文件的问题用 CDN 方式写本地页面时还有一个很隐蔽的坑file://协议下浏览器会限制很多动态加载行为Mermaid 懒加载模块时也可能因此失败。如果你只是本地写了个 demo双击 HTML 文件发现图渲染不出来别怀疑代码先开一个本地静态服务再访问。最简单的方式python -m http.server 8080然后浏览器访问http://localhost:8080/你的页面.html基本就没这个问题了。VSCode 的 Live Server 插件也可以效果一样。4. 动态渲染数据流让流程图真正“活”起来4.1 用 mermaid.render()而不是 innerHTML startOnLoad很多新手看文档时会直接开startOnLoad: true然后把mermaid代码块丢到页面里等着自动渲染。这招在纯静态页面没问题但在管理后台里不够用因为流程图要跟着接口数据变你得在拿到数据之后手动触发渲染。我建议的做法是全局关闭startOnLoadmermaid.initialize({ startOnLoad: false, securityLevel: strict, theme: base });通过接口拿到流程节点和连线之后再手动执行渲染async function renderGraph(text, containerId) { const container document.getElementById(containerId); container.innerHTML ; const { svg, bindFunctions } await mermaid.render( mermaid-svg- Date.now(), text ); container.innerHTML svg; if (bindFunctions) { bindFunctions(container); } }4.2 bindFunctions 这事不能忽略这个细节我在文档里翻了好几遍才搞明白。当流程图节点绑定了click事件回调时mermaid.render()返回的不只是 SVG 字符串还有一个bindFunctions方法。这个方法的作用是把 SVG 内部的元素事件重新绑定到对应的 DOM 节点上。如果你用container.innerHTML svg把图塞进页面SVG 里的click事件默认是没有绑定的必须再调一次bindFunctions(container)。一次渲染两步操作少了第二步节点点击事件就是静默失败控制台也不报错体验特别迷惑。顺手说一句mermaid.render()的第一个参数是临时 ID我在上面用了Date.now()拼接就是为了避免重复渲染时临时 ID 冲突。如果你固定传一个 ID 连续渲染两三次某些版本会报“ID already exists”之类的错误或者出现意想不到的渲染异常。4.3 数据刷新时的重绘时序真实项目中流程状态可能每隔几秒就刷一次或者用户点一下按钮就重新拉数据。这时候如果每次都全量渲染页面会有闪烁感。我做了三件事来缓解渲染前给容器设置一个最小高度避免旧 SVG 被清空后页面塌陷抖动。渲染入口加一个防抖比如 300 毫秒内多次触发只执行最后一次。异步出错时保留上一次渲染结果不要因为一次接口异常就把页面清空。let renderTimer null; function updateGraph(data) { clearTimeout(renderTimer); renderTimer setTimeout(async () { try { const text buildMermaidText(data); await renderGraph(text, graphContainer); } catch (e) { console.error(流程图渲染失败, e); // 保留上一次渲染结果 } }, 300); }这种写法的好处是用户感知不到重绘的抖动只看到图上节点的颜色或文案被更新了。5. 主题与安全做一套符合自己系统的流程图皮肤5.1 用 themeVariables 统一企业视觉Mermaid 自带了default、dark、neutral、forest、base几个主题。base主题就是专门给二次定制用的。你可以在mermaid.initialize()里通过themeVariables覆盖颜色、边框、字体等变量mermaid.initialize({ theme: base, themeVariables: { primaryColor: #f0f9ff, primaryTextColor: #1f2937, primaryBorderColor: #3b82f6, lineColor: #94a3b8, fontSize: 14px, fontFamily: PingFang SC, Microsoft YaHei, sans-serif }, flowchart: { nodeSpacing: 50, rankSpacing: 50, curve: basis } });这里我建议把flowchart里的nodeSpacing、rankSpacing、curve一并配置好。项目里常见的丑不是颜色丑而是节点挤成一团连线弯来弯去。间距给到 50 左右曲线用basis模式整体会清爽很多。5.2 CSS 覆盖与暗色模式适配Mermaid 渲染完的 SVG 带有固定类名比如连线是.flowchart-link节点矩形是.node rect节点文本是.nodeLabel。你可以在页面自己的样式表里针对这些类名做覆盖.flowchart-link { stroke: #64748b; stroke-width: 1.5px; } .node rect { rx: 6px; ry: 6px; }但有一个限制必须提醒Mermaid 会把themeVariables里的颜色直接写到 SVG 元素的style属性里内联样式的优先级高于外部 CSS。你想靠外链样式表覆盖某个颜色经常会发现没生效。正确做法是回到themeVariables里去改或者渲染完之后用纯 JS 遍历 SVG 元素修改。暗色模式我目前实践出来的方案是监听系统的prefers-color-scheme动态切换初始化的主题变量const isDark window.matchMedia((prefers-color-scheme: dark)).matches; mermaid.initialize({ theme: base, themeVariables: isDark ? { primaryColor: #1f2937, primaryTextColor: #f9fafb, primaryBorderColor: #6366f1, lineColor: #6b7280, } : { primaryColor: #f0f9ff, primaryTextColor: #1f2937, primaryBorderColor: #3b82f6, lineColor: #94a3b8, }, });切换主题后要重新执行一次mermaid.render()把新主题的 SVG 重新渲染一遍。指望旧 SVG 自动换肤做不到。5.3 securityLevel 不是摆设Mermaid 在节点文本里允许嵌 HTML 标签但这个能力也是一把双刃剑。如果把用户输入的内容直接拼进 Mermaid 文本再开低安全等级等于给 XSS 攻击开了门。v10 默认的securityLevel是strict在这个模式下节点里的 HTML 标签会被过滤以html:开头的标签形式会被限制。我的建议是保持默认除非你有非常明确的需求要在节点里渲染富文本否则别改成loose。如果确实需要显示动态文本内容先把输入做一遍转义再拼进图表文本双保险function escapeMermaidText(str) { return String(str).replace(/[]/g, (c) ({ : lt;, : gt;, : quot;, : #39;, }[c])); }6. 性能、报错和那些文档里没写的边界情况6.1 大流程图的体积和性能控制Mermaid 适合中等规模的流程图节点数量在几十个以内体验都不错。但如果你要把上百个节点、几百条边一次性塞进去渲染时间会明显变长页面还可能出现卡顿。我在实际项目里的控制策略是能分块就分块不要贪大。比如一个很长的审批流程按阶段拆成多个子图页面用 Tab 切换每个 Tab 只渲染自己那一段。同时可以调大 Mermaid 的maxTextSize限制默认是 50000 字符但这个值只适合兜底不能指望它解决性能问题。Mermaid v10 的懒加载机制对首屏体积有帮助但如果你用mermaid.min.js全量包首屏还是会加载所有类型的解析器。对加载体积敏感的项目回到 npm 按需注册的方式会更可控。6.2 我遇到的报错与排查记录现象原因处理方式Syntax error on textMermaid 文本语法错误提示会定位到第 N 行附近检查节点 ID、连线符号、引号是否成对图渲染出来是空白容器不可见或动态 import 失败先让容器可见再看控制台网络请求Diagram type not supported用的是 mermaid.core对应图类型没有注册手动注册 diagram或改回 import mermaid 全量包Cannot read properties of undefined (reading render)引入的包路径不对拿到的是空对象检查引入路径推荐直接import mermaid from mermaid本地 file:// 协议下报资源加载失败浏览器限制动态模块加载起本地静态服务不要直接双击 HTML我最想单独提的是“报错不直观”这条。Mermaid 的语法错误提示有时候只给一行Syntax error on text具体哪里错它不说。排查时可以把securityLevel临时调低让它渲染错误信息或者直接把 Mermaid 文本输出到控制台对照语法规则逐行检查。经验是报错大多集中在节点 ID 用了特殊字符、连线文本的引号没闭合、方括号被误写成括号这三类。6.3 生产环境一个容易被忽视的习惯页面里如果同时存在多个图表区域我建议在全局只调用一次mermaid.initialize()后续所有图形都通过mermaid.render()按需渲染。不要在每次渲染前都调 initialize那样会重复注册内部组件增加不必要的开销。另外生产环境建议关闭startOnLoad。原因很简单自动渲染的时机不可控它在 DOM 结构不确定时会抢先执行要么图形尺寸异常要么和你的手动渲染互相覆盖。显式调用mermaid.render()看起来多写了一行代码但它让渲染这件事变得可以预期这在项目维护阶段价值很大。个人经验是别把 Mermaid 当成一个黑盒工具只记 API 调用不够还是要理解“配置一次、渲染多次”这套节奏。掌握了这个不管你是接接口数据、做暗色适配还是改企业主题都不会觉得 Mermaid 在跟你对着干。最后提醒一句升级大版本之前先翻 changelogv10 升 v11 时有几个配置项的变化我见过不止一个项目在升级后翻车。本文还有配套的精品资源点击获取
基于Mermaid的流程图可视化：动态更新与主题定制实战
简介Mermaid.js 10.6.1 压缩版是一款借助简洁文本标记即可渲染流程图、序列图、甘特图、类图等多种图表的 JavaScript 库旨在帮助前端开发者、技术写作者和数据分析人员在网页、文档或报告中快速创建专业图表省去手工绘图和调整样式的繁琐过程。压缩包采用 ZIP 格式内含单个 mermaid.min.js 文件合计约 851KB为经过优化的稳定版本由于是压缩后的独立脚本无需安装额外依赖或访问外部 CDN在离线、内网或弱网环境下同样能正常完成图表渲染。目前已有 502 人学习/下载该版本被众多项目采用社区关注度较高。获取后可直接引用到前端项目通过文本描述即时生成多种图表极大简化可视化流程同时 Mermaid 具备可扩展架构可与 VS Code、Jira、GitLab 等工具链结合在原型设计、功能展示、数据分析等场景中显著提高开发与协作效率。 我最近在做一个内部流程引擎的管理后台需求是把节点状态用图展示出来。领导丢给我一句话“搞个流程图可视化要能自动更新。”我刚听到的时候还挺开心结果一查方案就有点懵手写 SVG 太费劲ECharts 画流程图要自己摆坐标Graphviz 又绕。最后绕了一圈还是回到 Mermaid——具体版本是 v10.6.1.min.js。这篇内容就是我做这个功能时攒下来的实操记录从选型、语法、渲染链路、动态刷新到主题定制基本把 Mermaid v10.6.1 这套整明白了。不管你是要做运维流程图、审批流可视化还是想在文档站里嵌入图表这篇都能当一份可以直接抄作业的参考。1. 为什么折腾一圈我还是选了 v10.6.1 这个版本做流程图1.1 先把话说明白Mermaid 到底解决什么问题Mermaid 是一个纯前端看图工具它把一段类似文本的图表描述语言渲染成 SVG 图形。简单说你给它一行A -- B它给你画出一个带箭头的流程图。写图表的人只需要关注内容结构不需要关心坐标、连线算法和图形布局。我见过很多人第一次接触 Mermaid 时问同一个问题“它和 Draw.io 有什么区别”Draw.io 是拖拽式Mermaid 是写代码式。拖拽式的好处是所见即所得坏处是“图表状态难以和程序数据联动”。Mermaid 的优势恰恰在于图表本身就是一段文本你可以从接口拿数据再拼接成这段文本页面刷新就完成重绘。这对管理后台、监控面板这类场景简直是命中要害——节点状态变了前端代码一变图就跟着变。1.2 v10 是一次重构分水岭如果你翻过 Mermaid 的历史版本会发现 v9 和 v10 之间变化非常大。v10 把整个渲染器用 ESM 方式重构了一遍核心能力被抽成了更干净的模块懒加载 diagram 类型成为正式特性mermaid.render()也彻底改成了 Promise 风格。v10.6.1 这个版本算是我实测里最稳的一个小版本。用它接 Vue 和原生 HTML 页面都没出过幺蛾子。再往后的 v11 我也试过虽然兼容性做得好但一些老项目的构建工具链还得跟着升级成本略高。所以如果你的目标是“快速跑通、稳定上线”v10.6.1 是一个非常合适的落点。另外标题里那个min.js指的是压缩后的浏览器全量包。它把 Mermaid 所有 diagram 类型都打包进去了全局引入后直接用mermaid这个变量不需要再编译什么前端工程。开发调试、写 Demo、给运维临时页面插一段渲染能力的时候这种方式就非常舒服。1.3 和主流方案对比我的取舍逻辑方案上手成本数据联动自定义程度适合场景Mermaid低中中文档、流程可视化、审批流ECharts 自定义图中高高大数据量、强交互图表antv/x6 / LogicFlow高高高可视化编辑器、画布拖拽Graphviz中低偏后端高离线渲染复杂图我的判断很直接如果需求是“把流程图画出来节点状态能跟着数据变”但没有拖拽编辑、没有自定义连线交互这些重需求Mermaid 就是性价比最高的选择。它不介入你的业务状态管理也不维护节点对象它只负责“字符串进去SVG 出来”这一件事。这也是它最大的优点简单。2. 流程图渲染链路从 text 到 SVGMermaid 到底做了什么2.1 最简调用流程Mermaid 的使用逻辑其实就是一条链路初始化配置 - 传入图表文本 - 得到 SVG 字符串 - 塞进页面容器。核心代码不长import mermaid from mermaid; mermaid.initialize({ startOnLoad: false, theme: base, securityLevel: strict }); const { svg } await mermaid.render(graphDiv, flowchart LR A[开始] -- B{是否通过} B --|是| C[发布] B --|否| D[驳回] ); document.getElementById(container).innerHTML svg;这里有一个容易误会的点mermaid.render(graphDiv, text)的第一个参数不是真正的 DOM 容器 ID而是 Mermaid 内部用来临时挂载解析结果的占位 ID。真正把图显示到页面上是最后那一步把svg字符串写入你自己的容器。所以我建议把render的返回值用变量接住再插入不要指望它自动往某个元素里画。2.2 flowchart 语法核心既然标题核心是流程图那直接记 flowchart 相关的语法就能覆盖 80% 的需求节点形状A[方框]A(圆角节点)A{菱形判断}A((圆形))A不对称]连线A -- B带箭头A --- B不带箭头A -.- B虚线A 加固 B粗线A -- 文字 -- B连线带标签子图区域flowchart TB subgraph 主流程 A[开始] -- B[处理] end subgraph 异常分支 B -- C[报错] end方向关键字LR表示左右走向TB表示从上到下走向。我在实际使用中踩过一个小坑节点 ID 千万别用中文也别带空格。比如开始[开始]这种写法在某些版本里会解析失败。虽然 v10 对文本内容的容忍度高了不少但节点 ID 建议还是用字母、数字、下划线需要展示的文字放到方括号里。2.3 渲染链路里最容易忽略的一个前置条件Mermaid 渲染 SVG 之前需要知道容器大概的尺寸。如果容器处于display: none状态或者还没插入 DOM渲染出来的 SVG 尺寸往往会变成 0。我做弹窗里的流程图时遇到过这个问题弹窗用 Vue 的v-show控制显隐第一次打开弹窗图是完整的关上再打开图宽高就塌了。原因就是页面初始化时mermaid.initialize()已经执行弹窗显示之前图已经渲染完了但容器宽度当时还是 0。解决方式很简单弹窗真正显示之后再调mermaid.render()并重新插入 SVG。3. 三种接入方式实测script 标签、npm 包和本地文件各有各的坑3.1 最稳的方案script 标签 全局变量如果只是在一个普通页面里用直接引 CDN 是最快的script srchttps://cdn.jsdelivr.net/npm/mermaid10.6.1/dist/mermaid.min.js/script script mermaid.initialize({ startOnLoad: true }); /script这种方式的坑不在 Mermaid而在 CDN 资源路径。v10 的 dist 目录里产物很多有mermaid.min.js、mermaid.core.min.js、mermaid.esm.min.mjs。mermaid.min.js是 UMD 构建引入后直接挂一个mermaid全局变量最不容易出错。mermaid.esm.min.mjs是 ES Module 版本必须配合script typemodule才能用别搞混。3.2 npm 方式与 mermaid.core 的区别工程化项目里一般用 npm 安装npm install mermaid10.6.1引入时注意包名默认路径import mermaid from mermaid;npm 包里有mermaid和mermaid.core两个入口。mermaid.core是未注册任何 diagram 类型的精简核心配合按需注册 diagram 使用能省不少体积。日常项目直接 importmermaid就行它会自动注册所有内置图类型。如果打包出来体积太大再考虑把mermaid换成mermaid.core手动引入用到的图类型import mermaid from mermaid/dist/mermaid.core;3.3 构建工具的大坑动态 import 的 base 路径这是我最想提醒你的一件事。Mermaid v10 为了实现懒加载内部会动态 import 一些模块。在 Vite 或 Webpack 工程里如果打包输出的静态资源路径配得不对浏览器运行时会出现Failed to fetch dynamically imported module的报错现象是页面白屏、图完全出不来。我在 Vite 项目里部署到子目录时踩过这个坑。解决办法是配置 Vite 的base路径让它和部署路径一致。Vite 的base默认是/如果你的页面部署在https://example.com/admin/下就要在vite.config.js里设置base: /admin/。这类问题不是 Mermaid 本身的 bug但它会表现得像个 bug排查起来很费时间建议直接记住这个前提。3.4 本地直接双击 HTML 文件的问题用 CDN 方式写本地页面时还有一个很隐蔽的坑file://协议下浏览器会限制很多动态加载行为Mermaid 懒加载模块时也可能因此失败。如果你只是本地写了个 demo双击 HTML 文件发现图渲染不出来别怀疑代码先开一个本地静态服务再访问。最简单的方式python -m http.server 8080然后浏览器访问http://localhost:8080/你的页面.html基本就没这个问题了。VSCode 的 Live Server 插件也可以效果一样。4. 动态渲染数据流让流程图真正“活”起来4.1 用 mermaid.render()而不是 innerHTML startOnLoad很多新手看文档时会直接开startOnLoad: true然后把mermaid代码块丢到页面里等着自动渲染。这招在纯静态页面没问题但在管理后台里不够用因为流程图要跟着接口数据变你得在拿到数据之后手动触发渲染。我建议的做法是全局关闭startOnLoadmermaid.initialize({ startOnLoad: false, securityLevel: strict, theme: base });通过接口拿到流程节点和连线之后再手动执行渲染async function renderGraph(text, containerId) { const container document.getElementById(containerId); container.innerHTML ; const { svg, bindFunctions } await mermaid.render( mermaid-svg- Date.now(), text ); container.innerHTML svg; if (bindFunctions) { bindFunctions(container); } }4.2 bindFunctions 这事不能忽略这个细节我在文档里翻了好几遍才搞明白。当流程图节点绑定了click事件回调时mermaid.render()返回的不只是 SVG 字符串还有一个bindFunctions方法。这个方法的作用是把 SVG 内部的元素事件重新绑定到对应的 DOM 节点上。如果你用container.innerHTML svg把图塞进页面SVG 里的click事件默认是没有绑定的必须再调一次bindFunctions(container)。一次渲染两步操作少了第二步节点点击事件就是静默失败控制台也不报错体验特别迷惑。顺手说一句mermaid.render()的第一个参数是临时 ID我在上面用了Date.now()拼接就是为了避免重复渲染时临时 ID 冲突。如果你固定传一个 ID 连续渲染两三次某些版本会报“ID already exists”之类的错误或者出现意想不到的渲染异常。4.3 数据刷新时的重绘时序真实项目中流程状态可能每隔几秒就刷一次或者用户点一下按钮就重新拉数据。这时候如果每次都全量渲染页面会有闪烁感。我做了三件事来缓解渲染前给容器设置一个最小高度避免旧 SVG 被清空后页面塌陷抖动。渲染入口加一个防抖比如 300 毫秒内多次触发只执行最后一次。异步出错时保留上一次渲染结果不要因为一次接口异常就把页面清空。let renderTimer null; function updateGraph(data) { clearTimeout(renderTimer); renderTimer setTimeout(async () { try { const text buildMermaidText(data); await renderGraph(text, graphContainer); } catch (e) { console.error(流程图渲染失败, e); // 保留上一次渲染结果 } }, 300); }这种写法的好处是用户感知不到重绘的抖动只看到图上节点的颜色或文案被更新了。5. 主题与安全做一套符合自己系统的流程图皮肤5.1 用 themeVariables 统一企业视觉Mermaid 自带了default、dark、neutral、forest、base几个主题。base主题就是专门给二次定制用的。你可以在mermaid.initialize()里通过themeVariables覆盖颜色、边框、字体等变量mermaid.initialize({ theme: base, themeVariables: { primaryColor: #f0f9ff, primaryTextColor: #1f2937, primaryBorderColor: #3b82f6, lineColor: #94a3b8, fontSize: 14px, fontFamily: PingFang SC, Microsoft YaHei, sans-serif }, flowchart: { nodeSpacing: 50, rankSpacing: 50, curve: basis } });这里我建议把flowchart里的nodeSpacing、rankSpacing、curve一并配置好。项目里常见的丑不是颜色丑而是节点挤成一团连线弯来弯去。间距给到 50 左右曲线用basis模式整体会清爽很多。5.2 CSS 覆盖与暗色模式适配Mermaid 渲染完的 SVG 带有固定类名比如连线是.flowchart-link节点矩形是.node rect节点文本是.nodeLabel。你可以在页面自己的样式表里针对这些类名做覆盖.flowchart-link { stroke: #64748b; stroke-width: 1.5px; } .node rect { rx: 6px; ry: 6px; }但有一个限制必须提醒Mermaid 会把themeVariables里的颜色直接写到 SVG 元素的style属性里内联样式的优先级高于外部 CSS。你想靠外链样式表覆盖某个颜色经常会发现没生效。正确做法是回到themeVariables里去改或者渲染完之后用纯 JS 遍历 SVG 元素修改。暗色模式我目前实践出来的方案是监听系统的prefers-color-scheme动态切换初始化的主题变量const isDark window.matchMedia((prefers-color-scheme: dark)).matches; mermaid.initialize({ theme: base, themeVariables: isDark ? { primaryColor: #1f2937, primaryTextColor: #f9fafb, primaryBorderColor: #6366f1, lineColor: #6b7280, } : { primaryColor: #f0f9ff, primaryTextColor: #1f2937, primaryBorderColor: #3b82f6, lineColor: #94a3b8, }, });切换主题后要重新执行一次mermaid.render()把新主题的 SVG 重新渲染一遍。指望旧 SVG 自动换肤做不到。5.3 securityLevel 不是摆设Mermaid 在节点文本里允许嵌 HTML 标签但这个能力也是一把双刃剑。如果把用户输入的内容直接拼进 Mermaid 文本再开低安全等级等于给 XSS 攻击开了门。v10 默认的securityLevel是strict在这个模式下节点里的 HTML 标签会被过滤以html:开头的标签形式会被限制。我的建议是保持默认除非你有非常明确的需求要在节点里渲染富文本否则别改成loose。如果确实需要显示动态文本内容先把输入做一遍转义再拼进图表文本双保险function escapeMermaidText(str) { return String(str).replace(/[]/g, (c) ({ : lt;, : gt;, : quot;, : #39;, }[c])); }6. 性能、报错和那些文档里没写的边界情况6.1 大流程图的体积和性能控制Mermaid 适合中等规模的流程图节点数量在几十个以内体验都不错。但如果你要把上百个节点、几百条边一次性塞进去渲染时间会明显变长页面还可能出现卡顿。我在实际项目里的控制策略是能分块就分块不要贪大。比如一个很长的审批流程按阶段拆成多个子图页面用 Tab 切换每个 Tab 只渲染自己那一段。同时可以调大 Mermaid 的maxTextSize限制默认是 50000 字符但这个值只适合兜底不能指望它解决性能问题。Mermaid v10 的懒加载机制对首屏体积有帮助但如果你用mermaid.min.js全量包首屏还是会加载所有类型的解析器。对加载体积敏感的项目回到 npm 按需注册的方式会更可控。6.2 我遇到的报错与排查记录现象原因处理方式Syntax error on textMermaid 文本语法错误提示会定位到第 N 行附近检查节点 ID、连线符号、引号是否成对图渲染出来是空白容器不可见或动态 import 失败先让容器可见再看控制台网络请求Diagram type not supported用的是 mermaid.core对应图类型没有注册手动注册 diagram或改回 import mermaid 全量包Cannot read properties of undefined (reading render)引入的包路径不对拿到的是空对象检查引入路径推荐直接import mermaid from mermaid本地 file:// 协议下报资源加载失败浏览器限制动态模块加载起本地静态服务不要直接双击 HTML我最想单独提的是“报错不直观”这条。Mermaid 的语法错误提示有时候只给一行Syntax error on text具体哪里错它不说。排查时可以把securityLevel临时调低让它渲染错误信息或者直接把 Mermaid 文本输出到控制台对照语法规则逐行检查。经验是报错大多集中在节点 ID 用了特殊字符、连线文本的引号没闭合、方括号被误写成括号这三类。6.3 生产环境一个容易被忽视的习惯页面里如果同时存在多个图表区域我建议在全局只调用一次mermaid.initialize()后续所有图形都通过mermaid.render()按需渲染。不要在每次渲染前都调 initialize那样会重复注册内部组件增加不必要的开销。另外生产环境建议关闭startOnLoad。原因很简单自动渲染的时机不可控它在 DOM 结构不确定时会抢先执行要么图形尺寸异常要么和你的手动渲染互相覆盖。显式调用mermaid.render()看起来多写了一行代码但它让渲染这件事变得可以预期这在项目维护阶段价值很大。个人经验是别把 Mermaid 当成一个黑盒工具只记 API 调用不够还是要理解“配置一次、渲染多次”这套节奏。掌握了这个不管你是接接口数据、做暗色适配还是改企业主题都不会觉得 Mermaid 在跟你对着干。最后提醒一句升级大版本之前先翻 changelogv10 升 v11 时有几个配置项的变化我见过不止一个项目在升级后翻车。本文还有配套的精品资源点击获取
