Mermaid Live Editor 详解：浏览器里的实时 Mermaid 画板
写 Mermaid 图最怕两件事：语法记不牢、渲染看不到。官网 mermaid.live（Mermaid Live Editor）把这两件事一次解决：左边写代码、右边实时出图，改一个字符立刻看到效果。它的源码开源于 mermaid-js/mermaid-live-editor，是 Mermaid 官方团队维护的配套编辑器。本文从功能布局、核心用法、分享机制到部署实践，完整拆解。
1、项目概述
Mermaid Live Editor 定位为 Mermaid 图表的在线实时编辑与分享工具，与核心库同属 mermaid-js 组织，官方维护、版本随核心库同步演进。仓库约 4.8k Star，技术栈为 Svelte + TypeScript + Vite，纯前端应用，无后端依赖。
基本形态与生态：
- 形态：在线 Web 应用（mermaid.live），支持离线 PWA 安装
- 协议为 MIT，可自由 Fork 二次开发
- 内置编辑器为 CodeMirror，带语法高亮与自动补全
- 与核心库 mermaid 同版本发布，始终用得上最新图型与语法
2、四大核心能力
Live Editor 的能力可以归成四根支柱，覆盖"写—看—存—发"完整链路。
四根支柱：
- 实时渲染：左侧代码区输入，右侧预览区毫秒级出图，语法错误即时标红
- 配置面板：主题、外观、Look（手绘/经典）、安全等级可视化调参
- 导出分享：导出 SVG/PNG，或生成含完整状态的分享链接 / 嵌入代码
- 模板速查：新建图表时按类型给出流程图、时序图、甘特图等模板起点
能力要点：
1. 纯前端运行：图内容不上传服务器，隐私与离线都有保障
2. 自动保存：草稿持久化到浏览器本地，误关页面不丢内容
3. 版本锁定：链接中记录当前 Mermaid 版本，分享出去的图不会因升级变形
3、界面布局与基本用法
打开 mermaid.live，界面分为四块：代码区、预览区、配置区、历史/模板区。核心工作流是"选模板 → 改代码 → 调配置 → 导出"。
// 1. 打开 https://mermaid.live
// 2. 左侧编辑代码，例如：
flowchart LR
A[需求评审] --> B[开发]
B --> C{测试通过?}
C -->|否| B
C -->|是| D[发布]
// 3. 右侧预览即时刷新
// 4. 右上角 Configuration 调整主题：
// {"theme": "dark", "look": "handDrawn"}
// 5. Actions 区选择导出 SVG / PNG 或复制分享链接操作要点：
1. 顶部 "+" 新建图表可从十余种图型模板中选起点
2. 左下 History 面板可回溯最近编辑快照，误删可找回
3. 快捷键 Ctrl+Enter 手动触发渲染，Ctrl+/ 折叠代码面板全屏看图
4. look 设为 handDrawn 可得到手绘风格，适合轻量汇报场景
4、分享机制：链接与嵌入
Live Editor 的分享设计很有特色：不是传文件，而是把"代码 + 配置 + 版本"全部编码进 URL。
// 复制的分享链接形如：
https://mermaid.live/edit#pako:eNpVkM1qw0AMhF9F6NRB8wY...
// "edit" 打开可编辑视图，"view" 打开只读视图：
https://mermaid.live/view#pako:eNpVkM1qw0AMhF9F6NRB8wY...
// 嵌入自己的网页（Actions 面板一键生成）：
<iframe
src="https://mermaid.ink/img/pako:eNpVkM1q..."
style="width:100%;max-width:600px;">
</iframe>分享要点：
1. pako 前缀表示内容经 pako 压缩再 Base64 编码，长图链接也不至于爆炸
2. /view 链接适合发到群聊/文档，接收方不会误改你的图
3. 群聊工具可能截断长链接，此时改用 mermaid.ink 图片直链或导出 PNG
4. 嵌入代码基于 mermaid.ink 免费图片服务，无需自建后端
5、配置详解：主题与外观
Configuration 面板是 Live Editor 区别于"裸渲染"的价值所在，改完的配置随链接一起分享。
常用配置项：
- theme：default / dark / forest / neutral / base，一键换肤
- themeVariables：深挖定制，如 primaryColor 改节点主色、fontSize 调字号
- look：classic / handDrawn，手绘风自 11.x 起支持
- securityLevel：strict / loose / antiscript，控制 HTML 标签与点击事件
配置要点：
1. 主题变量名可在官方主题文档查全表，Live Editor 改动即时预览
2. 复制出的配置 JSON 可直接用于自己项目里的 mermaid.initialize
3. 需要在节点里放 HTML（如加粗、换行）时，把 securityLevel 调为 loose
6、私有化部署
内网环境或需要定制界面时，Live Editor 可自行构建部署，仓库本身就是标准 Svelte 项目。
# 克隆并本地运行
git clone https://github.com/mermaid-js/mermaid-live-editor
cd mermaid-live-editor
npm install
npm run dev # 本地开发，默认 http://localhost:3000
# 构建产物
npm run build # 输出静态文件到 dist/
# 可托管到任意静态服务器 / Nginx / Pages部署要点：
1. Node 20+ 与 Vite 环境，安装即用无后端服务
2. dist 为纯静态产物，可挂到内网 Nginx 供全团队离线使用
3. 项目提供 Dockerfile，容器化部署一条命令完成
4. 二开可锁定特定 mermaid 版本，保证内部文档图渲染一致
7、定位对比：编辑方案三选一
把 mermaid.live、VSCode 插件与 mmdc 命令行放在一张桌上，各自的位置清晰起来。
三者对比：
- mermaid.live：零安装、实时预览、链接分享，适合临时画图与教学演示
- VSCode 插件：编辑项目内 .mmd 文件即渲染，适合与代码同仓库演进
- mmdc CLI：批量把源文件转 SVG/PNG，适合 CI 产物化
选型建议：
1. 临时讨论、发群分享、学习语法 → mermaid.live
2. 图进 Git 随代码演进 → VSCode 插件
3. 构建时批量出图 → mmdc
4. 组合玩法：live 里调好外观，配置 JSON 拷回项目 initialize，视觉统一
8、总结
Mermaid Live Editor（mermaid.live，约 4.8k Star、MIT 协议）是官方出品的在线 Mermaid 编辑器：Svelte + TypeScript 纯前端实现，CodeMirror 编辑 + 毫秒级实时渲染，配置面板可视化调主题与外观，导出覆盖 SVG/PNG/分享链接/iframe 嵌入；内容以 pako 压缩编码进 URL、版本随链接锁定，且支持 PWA 离线与私有化部署。
落地建议：学 Mermaid 语法直接在 live 编辑器里敲，比翻文档快数倍；画好的图用 /view 链接分享给同事评审，定稿后把代码与配置 JSON 沉淀进仓库；内网团队用 Docker 自部署一份，配合 mmdc 完成构建期出图。对于想低成本让全团队用上文本绘图的团队，mermaid.live 是必要的起点工具。
