企业官网建设流程全解析

第一次真正意识到这个问题，是在一次项目文档翻新的时候。系统模块调整了，业务流程的分支变了，原来的流程图里三四个节点需要重排，两条连线要改走向，还有一处分支要拆成两条。我当时的做法和大多数人一样：打开绘图编辑器，删掉旧图形，重新拖控件、对齐、连线、调样式、导出发布。整个过程花了四十分钟，而且大部分时间不是在思考业务逻辑，而是和图形布局搏斗。

Mermaid 最近在 Hacker News 上有一个很简洁的项目标题：Mermaid flowcharts you don't have to redraw in a diagram editor。这句话几乎说出了我这两年画流程图最深的感受——流程图本该是代码的产物，而不是绘图工具里的手工对象。Mermaid 能让你用一段文本描述流程结构，然后自动渲染成图；当需求变化时，你只需要修改文本，重新渲染，图表就是新的。

但很多人对 Mermaid 的理解还停留在“一个画图工具”或者“一种 Markdown 代码块”，这其实是把它的价值看小了。这篇文章我想从“为什么要用文本定义流程图”说起，讲清楚 Mermaid 真正解决的问题、上手路径、常见坑，以及它适合放到什么场景里用、不适合放到什么场景里用。

1. 先搞清楚 Mermaid 真正解决的“重画”问题

1.1 传统绘图编辑器为什么会在流程变更时成本很高

传统绘图编辑器的最大问题，不是画不出漂亮的图，而是图一旦画完，就变成了一堆“图形对象”的集合。每个节点是独立对象，每条连线是独立对象，位置、尺寸、样式、对齐关系都是被显式记录下来的。

这在初次画图时没问题。真正的问题出现在变更发生时。业务逻辑一变，你得做的不只是“改文字”，而是：

• 找到需要变化的节点，移动位置；
• 删除或重接连线；
• 调整相邻节点，避免重叠；
• 重新对齐，保证视觉一致；
• 调整样式，保持颜色和形状统一；
• 最后导出图片，替换到文档里。

看起来都是小事，但积少成多。很多团队最终选择不修改旧图，而是重新画一张新图。这不是懒，而是重画往往比调整旧图更快。流程图的本质是表达“流程结构”，但传统编辑器把“结构”和“视觉”强行绑在了一起。你想改结构，就必须一起改视觉，两者之间没有任何抽象层。

1.2 Mermaid 的核心变化：从“画图”到“维护流程定义”

Mermaid 做了一个关键反转：它把图表的本质从“图形对象集合”还原成了“结构化描述”。画图时，你写这样的文本：

graph TD A[需求提出] --> B{评审是否通过} B -- 是 --> C[进入开发] B -- 否 --> D[补充需求] D --> A

Mermaid 解析这段文本，自动生成对应的流程图。你看到的是图，但你维护的是文本定义。每次渲染都是一次全新的生成，所以不存在“上次画错位置”的问题，也不存在“手动对齐”的问题。

“不用重画”这句话的真正含义，不是指 Mermaid 能自动帮你把旧图改成新图，而是指：你根本不需要去“画”图。你修改的是流程的定义，图只是定义的结果。

这里我想强调一个判断：Mermaid 的核心价值不是“帮你省几分钟画图时间”，而是让流程图变成一种可以被版本管理、被 diff、被评审、被复用的资产。

一张图片格式的流程图，在 Git 里就是一个二进制文件，它经历了什么变化，你几乎看不出来。但一段 Mermaid 文本，你可以用 Git 精确地看到每次改动：是新增了一个节点，还是改变了方向，还是移除了一个分支。这带来的变化是工作流层面的，不只是绘图体验层面的。

1.3 这个方案适合谁，不适合谁

Mermaid 适合的是有清晰语义结构的图表。比如：

• 业务流程图：有节点、分支、跳转；
• 时序图：有参与者、消息、交互顺序；
• 状态图：有状态、事件、转换；
• 类图、甘特图、饼图等结构化图表。

这些图的核心信息是“关系”和“流程”，视觉布局只是辅助。Mermaid 能自动处理布局，你只需要关注结构本身。

Mermaid 不适合的场景也很明确：

• 需要精细视觉控制的海报式图表；
• 需要自由摆放元素、不遵循规则布局的架构图；
• UI 原型图、线框图；
• 需要和设计稿风格完全一致的对外材料。

这些问题不是 Mermaid 的 bug，而是它的边界。Mermaid 是流程图 DSL，不是绘图画布。它的布局算法能做的是自动化布局，不是你脑海里想要的那种“手工精调后的完美排版”。

所以在开始用它之前，先做一个判断：你要画的图，核心是信息结构，还是视觉表达？如果是前者，Mermaid 会非常顺手；如果是后者，建议用专业绘图工具，别硬适配。

2. 从零跑通一个 Mermaid 流程图：最小可运行流程

2.1 先写第一张图：graph TD 的最小闭环

Mermaid 的语法上手门槛很低，但有几个基本概念需要先理解。我建议第一次使用直接打开在线编辑器，不要先装任何本地环境。

Mermaid 官方提供了一个在线编辑器 mermaid.live，打开就能用，不需要登录，也不需要下载。左边写代码，右边实时渲染，非常适合从零验证语法。

第一张图，用最简单的流程闭环：

graph TD A[开始] --> B[处理请求] B --> C{是否成功} C -- 是 --> D[返回结果] C -- 否 --> E[记录日志] E --> B

拆开来看这五行的含义：

• graph TD表示这是一张从上到下（Top Down）的流程图；
• A[开始]定义了一个节点，节点 id 是 A，节点文本是“开始”；
• A[开始] --> B[处理请求]表示从 A 连到 B；
• C{是否成功}表示这是一个菱形判断节点；
• C -- 是 --> D[返回结果]表示从 C 到 D 的连线上带有文字“是”。

这里有一个新手容易忽略的点：节点的 id 和节点显示文本是分离的。A[开始]里，A 是 id，用于表示节点的唯一身份；“开始”是显示文本，用于展示。后续你要用 A 来连线，就必须引用 A 这个 id。很多人在复杂图里搞混，原因是把 id 写成了中文或者带特殊字符，导致后续连线报错。

2.2 方向、连线和分支：把流程图的基本语法拆开

方向关键字有四个：

• TD/TB：从上到下；
• BT：从下到上；
• LR：从左到右；
• RL：从右到左。

实际使用时，我建议先默认用TD或LR。先看整体结构是纵向流程还是横向流程，再决定方向。如果节点文本比较长，横向容易撑宽页面；如果节点很多，纵向容易导致图太高。没有绝对最优，需要根据阅读场景调整。

连线类型是流程图语法里最常用的部分：

graph LR A[节点A] --- B[节点B] A --> C[节点C] C -.-> D[节点D] D ==> E[节点E] E -- 带文字 --> F[节点F]

• ---表示无箭头实线；
• -->表示带箭头的实线，最常用；
• -.->表示带箭头的虚线，通常用于弱关系或异步调用；
• ==>表示粗实线，用于强调主路径；
• -- 带文字 -->用于给连线加文字说明。

分支表达式是流程图中最重要的部分。Mermaid 的判断节点用{}表示，它本身只是一个节点，真正的分支逻辑靠连线文字来表达：

graph TD A[收到请求] --> B{参数校验} B -- 通过 --> C[执行逻辑] B -- 不通过 --> D[返回错误]

这个结构表达的就是“如果通过，执行逻辑；如果不通过，返回错误”。理解起来不复杂，但实际绘制时，很多人会把分支逻辑写进节点文本，而不是放到连线上，比如写“参数校验通过？”作为节点文本，然后用三条线指向同一目标。这种做法没有语法错误，但会让图的语义变得混乱，因为阅读者无法快速判断条件和结果之间的对应关系。

2.3 用 subgraph 组织复杂流程

当流程节点超过十五到二十个时，即使语法完全正确，自动布局也会开始显得混乱。这时最有效的技巧是用subgraph对节点分组。

graph TB subgraph 前置阶段 A[创建任务] B[分配负责人] end subgraph 执行阶段 C[执行任务] D{校验结果} end subgraph 收尾阶段 E[归档] F[发送通知] end A --> B --> C --> D D -- 通过 --> E D -- 不通过 --> C E --> F

subgraph的作用是让一组节点在视觉上被框在一起，表达“这些节点属于同一个逻辑模块”。它不参与流程方向，只影响视觉分组。

这里有一个很常见的坑：Mermaid 对subgraph的缩进不敏感，但要求subgraph和end配对。如果你漏写了end，整个图表渲染会失败。而且不同版本的 Mermaid 对子图内部布局的处理不完全一致，所以当你把代码从在线编辑器复制到本地插件或 Markdown 平台时，渲染效果可能略有不同。这属于正常现象，不需要慌张，关键看语义是否一致。

2.4 选择渲染工具：在线编辑器、VSCode 插件、Markdown 内嵌

Mermaid 的上手路径可以分成三个层级：

第一层是在线编辑器。mermaid.live 适合验证语法、快速做一次性图表、学习新语法。它自带多种示例模板，也支持导出 SVG 和 PNG。如果你只是偶尔画一张流程图，用在线编辑器就够了。

第二层是VSCode 插件。在 VSCode 的扩展市场搜索 Mermaid，能找到不少相关插件，比如 Markdown Preview Mermaid Support、Mermaid Preview 等。这类插件的典型工作流是：打开一个.md文件，在代码块里写 mermaid 语法，然后打开侧边预览，实时看到图表效果。这种工作流的最大好处是图表和文档放在同一份文件里，改起来非常快。

第三层是平台内嵌渲染。GitHub、GitLab、很多文档系统都支持在 Markdown 中直接渲染 mermaid 代码块。这意味着你可以在代码仓库里写流程图，提交后在网页上直接看到渲染结果，团队成员不需要安装任何额外工具，只要能看到 Markdown 就能看到图。

我给新手的建议是：先在在线编辑器里跑通语法，再迁移到 VSCode 插件里做日常使用，最后根据团队协作需求决定是否嵌入到仓库或文档平台。

3. 把 Mermaid 放进真实工作流，而不是只用来画一张图

3.1 时序图：另一个被文本化拯救的场景

流程图是 Mermaid 最常用的类型，但并不是唯一受益的类型。时序图在项目文档里出现的频率极高，而且它在传统绘图工具里的维护体验更糟糕。

时序图的核心元素是参与者和消息。编写 Mermaid 时，你会发现它天然适合描述“谁在什么时候给谁发了什么消息”：

sequenceDiagram participant U as 用户 participant A as 前端应用 participant B as 后端服务 participant DB as 数据库 U->>A: 提交表单 A->>B: 发送请求 B->>DB: 执行查询 DB-->>B: 返回结果 B-->>A: 返回数据 A-->>U: 渲染页面

• participant U as 用户定义参与者，并给它起一个显示名；
• ->>表示同步消息；
• -->>表示异步返回。

时序图文本化的优势比流程图更明显，因为时序图的信息结构更严格：参与者、消息类型、顺序。你用鼠标画时序图时，需要手动拖动生命线、调整消息箭头的位置、保证对齐；用 Mermaid 写时序图时，顺序本身就是代码的顺序，消息类型只是符号差异。维护成本完全不在一个量级。

如果你所在的团队经常画时序图，我建议你重点看一下 Mermaid 官方文档里的 sequenceDiagram 部分。语法项不多，但很实用。

3.2 在项目文档和代码仓库里使用 Mermaid

Mermaid 最大的价值，是在它成为文档体系的一部分之后。单独画一张图，它只是输出物；嵌入到文档里，它变成了文档的逻辑组件。

最常见的做法是在 Markdown 文档里直接写 mermaid 代码块：

```mermaid graph TD A[需求] --> B[设计] B --> C[开发] C --> D[测试] D --> E[发布] ```

GitHub 和 GitLab 都能原生渲染这样的代码块。这意味着你的流程图可以放在 README、架构文档、ADR（架构决策记录）里，每次修改都有历史记录，不再需要单独维护一张图片文件。

更重要的是，Mermaid 文本可以参与代码评审。传统图片格式的流程图，评审者只能看整体效果，很难知道改动点在哪里。Mermaid 文本则像代码一样出现在 diff 中，评审者可以清楚地看到哪条连线被改成了什么。

这里有一点要提醒：不是所有 Markdown 平台都能渲染 Mermaid。CSDN 等部分博客平台对 mermaid 代码块的支持情况不同，如果平台不支持，你可能需要把渲染后的图片上传。真正需要优先使用 Mermaid 内嵌的场景是代码仓库和自建文档系统，而不是所有博客平台。

3.3 用命令行和 CI 把图导出成 SVG/PNG

如果 Mermaid 图最终要发布到不支持渲染的平台，或者要嵌入到 PDF 和 PPT 里，就需要把图导出成图片。Mermaid 提供命令行工具，通常通过 mermaid-cli 来使用。

mermaid-cli 的基本思路是：传入一个.mmd文件，工具会启动一个无头浏览器内核，把 Mermaid 渲染成 SVG 或 PNG。常见命令类似：

npx -y @mermaid-js/mermaid-cli -i input.mmd -o output.svg

这个工具适合放进 CI 流程里。比如你的文档仓库中维护了一批.mmd文件，每次提交后自动触发导出，生成最新的 PNG，再发布到文档站点。这样画图的人只需要维护文本，不需要手动导出图片。

需要注意几点：

• mermaid-cli 依赖无头浏览器运行环境，第一次运行可能需要下载浏览器内核文件。如果你们公司的网络环境受限，这一步可能耗时较长或失败；
• 导出的 SVG 在字体渲染上和本地打开 mermaid.live 可能略有差异；
• 如果你在 CI 里导出大量图片，要注意构建时长和资源占用。

mermaid-cli 的适用场景是“批量生成”和“自动化发布”，不是“临时导出”。如果只是偶尔导出一张图，直接在 mermaid.live 里复制导出就行。

3.4 drawio 转 Mermaid：迁移时需注意的边界

现在网上有不少开源工具支持把 drawio 文件转换成 Mermaid 语法，这给团队迁移带来了便利。但我建议对此保持谨慎预期。

drawio 文件本质上是 XML，包含节点、连线、坐标、样式这些信息。Mermaid 是只描述语义结构的 DSL，不包含坐标和样式。所以从 drawio 到 Mermaid 的转换，通常会丢失：

• 节点的精确坐标；
• 手动画布布局；
• 自定义样式、颜色、形状细节；
• 分组和层级信息（部分可能通过拆分子图恢复）。

转换工具能做的是提取节点和连线关系，尽量还原成 Mermaid 的节点和连线。但转换后的图往往是自动布局的，和你原来的手绘布局不同。所以“转换”更像是“提取语义结构”，而不是“完整迁移图片”。

如果你打算把已有 drawio 图迁移到 Mermaid，我的建议是先问一个问题：这些图接下来还要频繁改动吗？如果还要频繁改动，迁移值得做，因为 Mermaid 的维护成本更低。如果这些图已经稳定，只是为了从工具 A 搬到工具 B，那迁移的收益很有限，因为你还要花时间检查转换结果、调整子图、处理丢失的样式。

不要把 drawio 转 Mermaid 当成无损迁移工具。转换完成后，一定要人工检查一遍节点关系和分支逻辑，不要直接信任转换结果。

4. 实际使用中最容易踩的坑，以及一套排查链路

4.1 渲染失败或空白，先别急着改代码

Mermaid 最常见的错误是渲染区域显示一条语法错误信息，或者直接空白。遇到这种情况，不要立刻重写代码，而是按顺序排查。

我的排查链路是：

1. 看渲染面板的报错信息，定位到具体行；
2. 检查语法关键字是否拼写正确，比如graph和TD是否写对；
3. 检查有没有漏掉end，特别是使用subgraph时；
4. 检查节点文本里是否有未转义的特殊字符，比如方括号、括号、引号；
5. 把代码复制到 mermaid.live 里，看是否能正常渲染。

如果 mermaid.live 能渲染，但你的本地插件不能，那问题大概率出在插件版本或渲染环境上，而不是代码本身。

一个容易被忽略的点是：节点文本中尽量不要使用中文括号、引号、分号等全角标点作为语法结构的一部分。Mermaid 对全角符号的解析在不同版本中表现不完全一致，最稳妥的做法是：文本内容可以用中文，但语法符号使用半角。

4.2 中文字体和样式问题

Mermaid 对中文的支持总体没问题，但不同渲染环境的字体表现差异很大。在线编辑器里显示正常，导出成 SVG 后在网页上中文出现乱码或替换字体，甚至导出工具里中文变成方框，都是有可能的。

这类问题通常不是 Mermaid 语法的问题，而是渲染环境的字体问题。解决方向有几个：

• 尝试在样式初始化中指定中文字体；
• 使用 SVG 导出时，检查 SVG 引用的字体是否在你的目标平台存在；
• 如果导出成图片后中文显示异常，换个导出环境试试，比如用 mermaid-cli 或别的版本。

如果在 VSCode 插件里预览时中文正常，但导出 PNG 后中文异常，优先排查你本机字体的兼容性。

4.3 图一复杂就乱：布局是 Mermaid 的自然边界

当节点数量变多时，Mermaid 自动布局的缺陷会被放大。节点太多、连线交叉、分支拥挤，最终图会变得难以阅读。这种情况不是你的语法有问题，而是图表本身的复杂度超过了自动布局的承受范围。

我的经验是：当流程图的节点数超过 20 到 25 个时，开始考虑拆分图或者使用子图。拆图的原则是按业务模块拆，而不是按页面大小拆。比如将“订单处理”拆成“创建订单”“支付流程”“售后流程”三张图，每张图保持节点数在 10 个左右，可读性会大幅提升。

如果业务确实是一个完整流程，必须放在一张图里，那你要接受 Mermaid 的布局结果，不要花大量时间手动调样式。Mermaid 本身不提供精细的坐标控制，强行用样式 hack 来解决布局问题，会牺牲掉文本化最核心的维护性。

4.4 什么时候应该果断放弃 Mermaid

Mermaid 不是万能的。以下几个场景，我建议放弃 Mermaid，选择传统绘图工具或其他可视化方案：

• 需要精细视觉控制：比如对外发布的流程图要讲究排版、留白、品牌色，Mermaid 的自动布局很难满足；
• 自由画布型图表：架构图、拓扑图、思维导图，如果元素可以任意摆放，Mermaid 反而会限制你的表达；
• UI 原型图：线框图需要精确的位置和尺寸，Mermaid 做不到；
• 高交互图表：需要点击、缩放、联动、动态数据的图，Mermaid 也不合适，它更适合静态渲染。

判断标准很简单：如果图的核心是“信息结构”，用 Mermaid；如果核心是“视觉呈现”，用传统工具。两者是互补关系，不是替代关系。

5. 把“不用重画”变成团队的长期习惯

5.1 一个可复用的四步框架：从流程到图资产

我在多个项目里总结了一个四步框架，用来判断和实现“流程图文本化”：

第一步，定义流程结构。不要急着写代码，先在纸上或用文字列出：有哪些节点、哪些分支、哪些状态、先后顺序是什么。

第二步，用最小语法描述。选一个视图类型（graph TD、sequenceDiagram 等），用最少的语法把流程节点和连线表达出来。这个阶段的目标是“能渲染出一张完整的图”，不是“渲染得漂亮”。

第三步，选择视图类型和分组。当结构跑通后，再考虑方向、子图、连线文字和样式。用 subgraph 把模块边界表达清楚。

第四步，纳入版本管理和评审流程。把 Mermaid 文本放进仓库，让团队成员可以通过代码评审来分析流程图改动。

这个框架的核心是“先保证语义，再优化视觉”。很多人一上来就调样式、改颜色，结果语义有问题，全部白做。

5.2 用代码评审来评审流程图的变化

传统图片流程图的评审，通常是“看图说话”：团队成员打开图片，用语言描述“这里分支好像改了，那里多了一个节点”。这种评审方式效率低且容易遗漏。

Mermaid 文本化后，流程图可以像代码一样出现在 Git diff 里。评审者能清楚地看到：

• 哪一行新增了节点；
• 哪条连线被删除或修改；
• 哪个分支条件变了；
• 哪个子图被重构了。

这带来的好处不只是效率，还有责任心。当流程图的变化能精确追溯到提交人和动机时，团队会更愿意在修改时写下清晰的 commit message，文档质量会随之提高。

5.3 我的建议：先在小范围验证，再逐步扩大

最后我想给一个很现实的建议：不要试图一次性把团队所有图表都迁移到 Mermaid。这个迁移本身也可能变成一种重画工作。

更稳妥的做法是：选择一个高频更新、结构清晰的流程图，比如核心业务流程图或系统状态图，先用 Mermaid 重写它，跑一两个迭代周期，看看维护成本的变化。用完之后，让团队切身体会“改文本、不重画”的差异，再决定要不要扩大使用范围。

Mermaid 的长期价值不是把画图工具替换掉，而是改变你对“图”的看法。图不再是一张静态的图片，而是一份可维护、可追踪、可复用的流程定义。它和代码一样，可以长期演进。

所以回到文章开头那句话：Mermaid flowcharts you don't have to redraw in a diagram editor。我更愿意把它理解成一句提醒：流程图应该跟着业务流程走，而不是跟着鼠标走。当你把流程图的维护成本降到可以忽略不记时，团队成员才愿意主动更新它。而一张能被持续更新的流程图，远比一张精美但过时的图更有价值。