简介Mermaid.js v10.6.1 压缩版是一份面向前端开发者、文档工程师和数据可视化爱好者的图表渲染工具解决在网页与应用中快速生成流程图、序列图、甘特图、类图等专业图表的场景。它采用简洁的文本语法描述图表结构与交互无需手工拖拽绘制特别适合嵌入技术文档、项目 Wiki、产品说明或离线演示环境。压缩包体积仅851KB共1个文件即mermaid.min.js单一 JavaScript 文件引入即用无外部依赖可在内网或弱网环境稳定渲染。目前已有502人学习下载适合需要提升开发效率、统一图表风格并降低维护成本的团队使用。获取后可独立部署到任意前端项目跟随社区生态兼容 VS Code、GitLab 等常用工具便于持续扩展新的图表类型和功能。 上个月给团队内部工具加流程图可视化模块JavaScript 技术栈图表渲染最终选了 Mermaid。最开始我纠结过用 Visio 画好再传图改一个节点就要重新导出手写 SVG 又太耗时间。后来决定用 Mermaid一行文本对应一个流程节点代码和图表共用一套源文件Git 里还能直接看 diff协作效率比以前高了不少。这篇文章就基于 Mermaid v10.6.1.min.js把从环境引入、语法写法到动态渲染、踩坑排查的完整过程梳理一遍适合正在做文档系统、流程审批、知识库或者想给网页加技术架构图的前端开发者参考。1. 整体设计思路为什么把图表交给一段文本1.1 三个候选方案的取舍先聊方案对比。PlantUML 是老牌文本画图工具语法成熟但要跑起来依赖 Java 环境和本地命令想在浏览器端实时渲染得额外搭服务或者塞一个很重的编译器对纯前端团队来说太重。手写 SVG 可控性最强可画一个像样的流程图动辄几百行代码调整节点位置和连线路径非常痛苦基本等于把画画这件事自己扛下来。Mermaid 刚好卡在中间纯 JavaScript 库浏览器直接渲染成 SVG语法比 PlantUML 更接近 Markdown 的书写习惯团队里没接触过的人十分钟就能上手输出是矢量图天然适配响应式布局和主题定制。做选型时我列过一张对比表方案渲染方式输出格式前端实时渲染成本维护难度Mermaid浏览器端 JSSVG低直接引库即可低文本可 diffPlantUML需要 Java/服务端SVG/PNG高依赖服务端中依赖环境手写 SVG浏览器直接绘制SVG中全手写高改一处崩一片对比完基本就定了文本画图这条路更符合团队协作习惯。1.2 v10.6.1 这个版本号的讲究Mermaid 在 v10 之后做了一次比较大的架构调整渲染流程被拆成更细的模块API 也统一改成以 Promise 为主。比如 9.x 时代mermaid.render()返回字符串v10 里返回的是包含svg、bindFunctions等字段的对象直接把返回值当字符串用就会踩坑。10.6.1 属于 10.x 里比较稳定、社区讨论也多的版本真遇到问题基本能搜到现成解法这是选它的实际优势。新版本功能多但对只画流程图、时序图的场景没必要追新。锁定版本还能避免 CDN 缓存更新造成本地和线上渲染行为不一致我在 package.json 里直接写死mermaid: 10.6.1CDN 地址也带10.6.1保证所有人行为一致。1.3 适用的场景边界Mermaid 特别适合四类场景内部文档或 Wiki 里嵌入流程说明低代码平台的流程编排可视化审批流、工单流的动态展示产品原型阶段快速输出架构图。但有一条边界我踩过坑大型复杂图。节点超过五六十个之后自动布局出来的线条会非常乱画布拖拽、框选这些交互也跟不上。如果核心需求是自由拖拽编辑应该去看 AntV X6、LogicFlow 这类图编排引擎Mermaid 的定位始终是“文本渲染”不是“画布编辑”。2. 渲染工具引入CDN、离线包与初始化配置2.1 一条 script 标签跑起来最快上手方式就是 CDN两行代码搞定script srchttps://cdn.jsdelivr.net/npm/mermaid10.6.1/dist/mermaid.min.js/script script mermaid.initialize({ startOnLoad: true }); /script然后在页面任意位置写一个带mermaidclass 的容器放上 Mermaid 文本页面加载后会自动替换成 SVG。用 jsdelivr 是因为可访问性相对稳定备选还有 unpkg。这里有个细节如果页面本身就是技术文档里面各种代码块很多建议给 Mermaid 容器单独指定一个 class不要全用mermaid否则容易误渲染。实际项目里我更倾向不用startOnLoad: true而是手动触发mermaid.run()后面会细说原因。2.2 npm 引入与离线文件选择正规项目建议走 npmnpm install mermaid10.6.1然后模块化引入import mermaid from mermaid; mermaid.initialize({ startOnLoad: false });离线部署时注意要从node_modules/mermaid/dist/mermaid.min.js拷贝到静态目录别拿mermaid.js开发版顶上那个没压缩体积更大。如果项目用 webpack、Vite 这类构建工具优先用mermaid.esm.min.mjs它对 tree-shaking 更友好。压缩后的核心文件约 2.8MB首次加载有压力我的做法是只在需要的路由里动态import()不塞进全站 bundle。2.3 初始化配置和安全级别初始化配置最容易被忽略我常用的配置是这样mermaid.initialize({ startOnLoad: false, theme: base, securityLevel: strict, fontFamily: PingFang SC, Microsoft YaHei, sans-serif, flowchart: { useMaxWidth: true, htmlLabels: true, curve: basis } });theme常用值有 default、dark、neutral、forest、basebase 适合配themeVariables做品牌色统一。securityLevel是关键默认就是 strict会禁掉图表文本里的 HTML 标签和脚本防止渲染用户输入时产生 XSS。只有完全可信的内部数据才临时改成 loose。flowchart.curve控制连线弯曲方式basis 曲线平滑但节点多了视觉上容易缠在一起密集图我一般换成 linear。3. 流程图语法核心拆解3.1 节点定义与基础形状Mermaid 流程图核心就是节点加连线。最简代码flowchart TD A[发起申请] -- B{审批是否通过} B -- 通过 -- C[进入下一环节] B -- 驳回 -- D[退回修改]TD表示从上到下流程较长时换LR从左到右更省纵向空间。A、B 是节点 ID方括号是矩形节点花括号是判断节点。还有圆角A(发起申请)、圆形A((开始))、六边形A{{核对}}。中文字符直接写没问题但标点建议用中文全角避免和语法符号冲突。节点 ID 尽量只用字母、数字、下划线不要带小括号或减号否则加样式、绑事件时很折腾。3.2 连线、标签与子图连线的变体比较多列个常用写法flowchart LR subgraph s1[前端部分] A[采集数据] -- B[发送请求] end subgraph s2[后端部分] C[接收请求] -- D[返回结果] end B -.-|HTTP 请求| C D |响应| E[前端展示]实线--、虚线-.-、粗线线上加文字推荐--|文字|这种写法中文兼容性最好。子图用subgraph包起来可以加标题适合展示多模块协作流程。顺便提醒v10 里官方更推荐flowchart而不是老式graph新语法对子图、方向、样式的支持更一致新项目一律写 flowchart。3.3 样式定制与节点点击样式主要通过classDef和style语句实现flowchart TD A[开始] -- B[处理] classDef green fill:#e8f5e9,stroke:#43a047,stroke-width:2px; class A,B green;单个节点也可以style A fill:#ffcccb。点击事件是高频需求文本里写click A 回调函数名再用mermaid.render()返回的bindFunctions把回调绑定到 SVG 元素上。注意回调函数要挂在全局或者通过bindFunctions注册否则点击没反应。strict 模式下直接用click受限所以动态渲染时我基本都走bindFunctions。4. 动态渲染与业务集成实战4.1 从接口数据生成图的完整代码业务中很少直接用静态文本更多是流程配置存数据库前端拿 JSON 再生成图。核心步骤是把数据拼成 Mermaid 字符串再交给mermaid.renderconst res await fetch(/api/flow); const data await res.json(); let mermaidText flowchart TD\n; data.nodes.forEach((node, idx) { mermaidText N${idx}[${node.label}]\n; }); data.edges.forEach((edge) { mermaidText N${edge.from} --|${edge.label || }| N${edge.to}\n; }); const renderId flow_ Date.now(); const { svg, bindFunctions } await mermaid.render(renderId, mermaidText); const container document.getElementById(flow-container); container.innerHTML svg; if (bindFunctions) { bindFunctions(container.querySelector(svg)); }这里两个关键点renderId不要重复否则 v10 会报 ID 已存在的错SVG 插到容器后要手动调用bindFunctions点击事件才会生效。如果标签来自用户输入拼接前要先转义把引号、换行过滤掉不然破坏图表结构。4.2 startOnLoad 与动态插入的时序问题遇到最隐蔽的问题是页面已经用startOnLoad: true自动渲染完静态图后来动态往 DOM 插了一个带mermaidclass 的节点结果完全没反应。因为 Mermaid 只会在初始化时把已存在的元素处理一遍后续新增的不会自动检测。解决方式await mermaid.run({ nodes: document.querySelectorAll(.mermaid-dynamic) });注意run之后不要再对同一容器整体替换innerHTML否则会把 SVG 结构换掉再次 run 容易重复渲染。我的经验是每个页面提前定好渲染策略要么全部手动 render要么静态加局部 run不要混着来。4.3 在 Vue 和 React 里的接入方式Vue 3 里可以封装一个 MermaidFlow 组件模板放一个 divonMounted里调用mermaid.render结果通过v-html放进去。React 类似在useEffect里异步渲染用dangerouslySetInnerHTML注入。有个细节Mermaid 生成的 SVG 自带style标签如果项目全局 CSS 重置写得太狠比如* { box-sizing: border-box }或者重置 SVG stroke可能把连线颜色冲掉。这种就给 SVG 容器加独立作用域或者收窄重置规则。如果项目用了 Markdown 渲染器比如 markdown-it可以写一个插件识别到 Mermaid 代码块时渲染后调用mermaid.render生成 SVG 再替换进去。知识库和笔记系统里写代码块直接出图体验很好。4.4 用在线编辑器和 VS Code 插件提升效率写复杂语法时我习惯先打开 Mermaid Live Editor实时预览调好再复制进项目。VS Code 装 Markdown Preview Mermaid Support 或 Mermaid Preview 插件在 Markdown 文件里写一个mermaid代码块预览就能直接显示图表。调样式时我会在 Live Editor 里先把主题调成目标值再看它生成了哪些themeVariables拿回来覆盖到自己项目这样省去反复试错。但注意在线工具默认版本未必是 10.6.1遇到预览和本地不一致优先查版本。5. 常见问题与排查技巧实录5.1 高频报错速查表把实际遇到过的问题整理成表方便对照现象原因处理方式mermaid is not definedscript 顺序不对、CDN 被拦截确认引入顺序改本地文件或 npm 引入显示源码而不是图表容器 class 没匹配或文本没有 flowchart 开头检查 class文本首行写 flowchartSyntax error in text中文分号、节点 ID 带特殊符号ID 规范化标签用引号包裹提示 render id 重复多次调用 render 用了相同 id每次用新 id渲染前清空容器点击节点无反应回调没通过 bindFunctions 注册渲染后拿 bindFunctions 绑定部分样式不生效htmlLabels 为 false或全局 CSS 干扰用 classDef 显式声明隔离样式5.2 渲染性能瓶颈与大图处理Mermaid 对大型图表的布局能力比不过专门的图编辑库。我的经验值三十到五十个节点以内渲染基本在一秒左右超过一百个节点布局时间明显拉长图也会变得很难读。应对办法主要有三个拆图把一个大流程拆成多个子流程图懒渲染滚动到容器附近再调用 render预生成后台配置的静态流程在服务端或构建期先渲染成 SVG 再返回前端减少浏览器计算量。导出场景下因为输出是 SVG用 html-to-image 或 html2canvas 转 PNG 即可但务必等字体加载完再截图否则中文字体会变成豆腐块。5.3 安全边界与用户输入过滤最后重点提醒一句不要拿用户输入的任意文本直接拼进 Mermaid 结构。strict 模式默认会过滤大部分 HTML 和脚本但文本里的引号、换行、--仍会破坏图表结构轻则渲染报错重则让别人构造出异常图表。安全做法标签先转义再统一包在引号里比如英文双引号换中文引号换行和--替换成空格。凡是内容来自表单提交的场景都走一遍白名单过滤只保留中英文、数字和常见标点这一步别省。我自己实际项目里最常用的模式是把 Mermaid 渲染封装成独立工具函数输入数据直接出 SVG静态文档、后台配置、用户自定义流程三套场景复用同一套逻辑。折腾下来最大的感受是文本化图表的价值不在省掉鼠标点击而是它变成可版本管理、可搜索、可自动生成的内容资产。如果你现阶段的需求是“快速把流程画出来放到网页里”Mermaid v10.6.1 这个组合完全够用等哪天节点多到排版失控再考虑引入专门的图编辑引擎也不迟。本文还有配套的精品资源点击获取