企业官网建设流程全解析

前阵子有个同事问我：你们技术方案里的架构图、时序图都用什么画？我说 Mermaid，直接在 VSCode 里写。他一脸疑惑，反手甩给我一堆热搜关键词：vscode mermaid、mermaid live editor、markdown preview mermaid support。他说大家搜来搜去，不就是想解决“在 VSCode 里用 Mermaid 画图”这件事吗？确实，很多人知道 Mermaid 这个名字，也听说过 VSCode 装个插件就能预览，但真到了自己动手配置、写语法、遇到渲染问题的时候，还是会被各种小细节卡住。今天我就把自己这一两年在 VSCode 里写 Mermaid 的插件组合、常用语法、批量导出、踩坑记录和团队协作习惯，完整地摊开来聊一遍。适合所有想在 Markdown 文档里嵌入流程图、时序图、甘特图，又不想被在线工具绑架的开发者。

1. 为什么我放弃了在线流程图工具，改用 VSCode 写 Mermaid

1.1 在线编辑器看起来很香，但一协作就露馅

早几年我用在线流程图工具也挺顺手，拖拽画框、连线、改颜色，看起来“所见即所得”。但真到多人协作的项目里，问题就开始扎堆：同事改了图，我这边看不到改动记录；评审意见只能靠截图加红框；想回退到上一版，发现历史版本被锁在付费功能里。最痛苦的是，图和代码存在于两个世界，代码改了一版，图还是老样子，过两周自己都分不清哪张图对应哪个版本的逻辑。

后来我意识到，对于写代码的人来说，图的本质不是“画出来的作品”，而是“对系统逻辑的表达”。只要这个表达能变成文本，它就能进 Git，能被 diff，能被 review，能被注释，能跟着代码一起演进。这就是 Mermaid 最打动我的地方：它把一个流程图写成类似 Markdown 的纯文本，然后用 JavaScript 渲染成 SVG 或 PNG。既然我已经整天泡在 VSCode 里写 Markdown，那图也应该在这同一个地方解决。

1.2 VSCode + Mermaid 的本质：把图当成代码来管理

有人会说，在线编辑器我也能导出代码，也能保存。问题在于“顺手”。在 VSCode 里写 Mermaid，最核心的体验不是省一个网页标签页，而是整个工作流被统一了：

• 图和 Markdown 文档放在一起，不需要切软件；
• 语法高亮、自动补全、代码折叠都套用编辑器能力；
• 保存文件后预览实时刷新，光标定位到某一行，预览里能快速对应；
• 改动走 Git 流程，评审人在 PR 里直接看 Mermaid 源码，比看一张压缩过的小图片清楚得多；
• 需要交付 PNG/SVG 时，用 mermaid-cli 一条命令批量导出，不需要人肉截图。

所以这篇文章不止是讲“怎么装插件”，更想讲清楚一套能够长期用的工作流：插件怎么选、语法怎么写、导出怎么做、出了问题怎么排。

2. 环境准备：VSCode 插件选型与离线渲染方案

2.1 一套够用且不打架的插件组合

我先直接给结论：日常写 Mermaid，我装的插件就三个，必要时再加一个 Markdown Preview Enhanced。不要一口气装五六个同类插件，预览引擎会互相干扰，到时候报错都不知道该怪谁。

安装方式没什么可说的，打开扩展商店搜名字，点安装，然后重启窗口。需要注意的是：如果你同时装了 Markdown Preview Mermaid Support 和 Markdown Preview Enhanced，两个扩展都会尝试接管预览，偶尔会出现“代码块渲染两次”或者“预览空白”的情况。我自己习惯是用前者做日常预览，用后者做最终导出，两者同时启用但把 Preview Enhanced 的自定义主题关掉，避免样式冲突。

2.2 用 mermaid-cli 把图导出成 PNG/SVG

VSCode 里的预览只能在编辑器里看，真要交付到文档、PPT 或公众号里，还是得有静态图片。mermaid-cli 是官方提供的命令行工具，底层调用 Puppeteer 启动 Chromium 去渲染页面，再截成图片或矢量图。

安装很简单，前提是你机器上已经有 Node.js：

npm install -g @mermaid-js/mermaid-cli

安装完就能用了。先写一个测试用的.mmd文件，内容就是普通的 Mermaid 语法：

flowchart LR A[写代码] --> B[执行 mmdc] B --> C[得到图片]

然后在终端执行：

mmdc -i test.mmd -o test.svg mmdc -i test.mmd -o test.png -w 2048

-w参数是输出宽度，建议导出 PNG 时把它设置成 2048 或更大，不然放到文档里会模糊。第一次运行时 mmdc 会下载一个精简版 Chromium，如果网络条件不好，这一步会卡很久甚至失败。解决办法是让 Puppeteer 直接使用你本机已经装好的 Chrome/Edge：

PUPPETEER_EXECUTABLE_PATH="C:/Program Files/Google/Chrome/Application/chrome.exe" mmdc -i test.mmd -o test.png

Windows 用 set 命令设置环境变量，macOS/Linux 在命令前直接加即可。

2.3 把 VSCode 调成“一边写一边看”的布局

Mermaid 在 VSCode 里最舒服的用法就是：左半边是 Markdown 源码，右半边是实时预览。打开方式很简单：

1. 打开.md文件；
2. 按Cmd + Shift + P（Windows 是Ctrl + Shift + P）；
3. 输入 “Markdown: Open Preview to the Side”；
4. 回车，预览面板会出现在右侧，光标在源码里定位到 mermaid 代码块，预览也会跟着走。

如果你是经常写技术文档的人，建议把预览面板固定住，不要每次重新打开。再配合 VSCode 的自动保存，每次改动语法都能立刻看到结果，这比去 mermaid.live 复制粘贴再截图爽多了。顺带一提，mermaid.live 也不是没用，我通常是拿它做临时调试用的——比如 VSCode 预览报错又看不出来具体位置时，把代码粘过去看官方的报错提示。

3. Mermaid 核心语法：可以直接复制的示例

3.1 流程图 flowchart：使用频率最高的一张图

几乎所有刚接触 Mermaid 的人，第一张图都是流程图。流程图的写法非常直观：节点用中括号包起来，箭头用-->，方向用关键词标注，比如TD表示从上到下，LR表示从左到右。

flowchart TD A[开始] --> B{已经装好 Mermaid 插件了吗} B -- 否 --> C[在扩展商店搜索并安装] C --> D[重载窗口] B -- 是 --> E[写 mermaid 代码块] D --> E E --> F[打开 Markdown 预览查看结果]

这段代码里，B{...}是菱形判断节点，-- 否 -->是带文字的边。如果你想把判断条件写得更清晰，也可以把整段边上的文字用引号包起来：

flowchart LR A[收到需求] --> B{有没有现成接口} B -- "有" --> C[直接接入] B -- "没有" --> D[评估开发量] D --> E{开发量可接受?} E -- 是 --> F[排期开发] E -- 否 --> G[反馈给产品]

说实话，流程图并不需要把所有分支都画得特别复杂，我见过很多人把一个流程图画成十几层嵌套，结果自己看着都晕。Mermaid 的好处是改起来快，所以你完全可以保持“主路径清晰、异常分支单独成段”的写法。

3.2 时序图 sequenceDiagram：接口对接和流程沟通神器

时序图是我在技术方案评审中使用频率最高的一种图，因为它能非常清楚地表达“谁在什么时候调了谁的什么方法”。

sequenceDiagram participant U as 用户 participant FE as 前端页面 participant SVC as 后端服务 participant DB as 数据库 U->>FE: 输入账号密码 FE->>SVC: POST /api/login SVC->>DB: 查询用户信息 DB-->>SVC: 返回用户记录 SVC-->>FE: 返回 token FE-->>U: 登录成功

语法要点说几个：

• participant A as 别名可以让你在代码里用简短名字，而图上显示完整名称；
• ->>是实线带箭头，-->>是虚线带箭头；
• 可以用activate和deactivate把时序图里“方法正在执行”的过程标记出来，比如：

sequenceDiagram participant CLIENT as 客户端 participant API as 网关 participant ORDER as 订单服务 CLIENT->>API: 创建订单 activate API API->>ORDER: 调用订单接口 activate ORDER ORDER-->>API: 返回订单号 deactivate ORDER API-->>CLIENT: 返回成功 deactivate API

时序图在接口对接时特别好用，因为一张图就能把前后端、第三方服务、数据库之间的调用关系说清楚，比坐在会议室里拿画笔在板子上比划高效得多。

3.3 甘特图与饼图：汇报占大头时靠它救场

甘特图是我推荐所有项目经理和小组长必学的 Mermaid 图。它的语法核心是定义任务名、状态、时间点和持续时间：

gantt title 前端版本发布计划 dateFormat YYYY-MM-DD section 开发阶段 需求梳理 :done, a1, 2025-01-06, 2d 组件开发 :active, a2, after a1, 4d 接口联调 :a3, after a2, 3d section 测试阶段 功能测试 :a4, after a3, 2d 回归测试 :after a4, 1d

dateFormat用来定义日期格式，after a1表示该任务在前一个任务之后开始。任务状态用done、active、crit标记，甘特图上会自动显示颜色和进度条。饼图就更简单了，适合展示占比关系：

pie title 团队本周工时占比 "产品需求" : 25 "技术方案" : 20 "编码开发" : 35 "测试修复" : 15 "会议沟通" : 5

饼图虽然最简单，但占比数据稍稍一变就要重开在线工具复制数据再截图；用 Mermaid 的话，改一个数字刷新即出图。这也是“图表即代码”最直观的体验。

3.4 子图 subgraph：复杂系统图的基本组织单元

画系统架构图时，最怕把所有节点堆在一个大画布里，连线和文字缠在一起。Mermaid 的subgraph可以把相关节点圈进一个分组，相当于给图分了个层。

flowchart LR subgraph FE[前端应用] page[页面组件] --> api[API 封装层] api --> request[HTTP 请求] end subgraph BE[后端服务] gateway[网关] --> auth[认证模块] auth --> business[业务服务] end request --> gateway

这样前端、后端各自一层，跨层只留一条主线，阅读体验会好很多。我还习惯在 subgraph 名称里用中文别名，像subgraph FE[前端应用]这样，代码里用英文标识符，图上展示中文，既方便命令操作，也不影响阅读。

4. 从“能画”到“画得规范”：主题定制与项目级复用

4.1 用 init 指令统一主题与品牌色

Mermaid 默认的配色是浅色背景加蓝绿色节点，临时看看没问题，但放到公司文档里，气质总差一截。Mermaid 提供了配置指令，可以在代码块第一行设置主题和自定义颜色：

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f0f3f8", "lineColor": "#556677", "textColor": "#223344"}}}%% flowchart LR A[统一风格] --> B[团队文档] B --> C[视觉协调]

常用主题有default、base、dark、forest、neutral。如果只是自己调试，直接在 mermaid.live 的主题下拉框里切着预览；如果是要统一输出，建议把 init 配置固定成一个模板，复制到所有文档开头。这里有个细节值得提醒：init 指令必须放在 mermaid 代码块的第一行，前面不能有空格，不然部分渲染引擎会把它当成普通注释忽略掉，导致主题不生效。

4.2 用 .mmd 文件管理全项目图表，配合脚本批量导出

很多人都把 Mermaid 直接嵌在.md文档里，这没问题。但当一个项目里的图越来越多，我建议把图单独拆成.mmd文件，统一放在docs/diagrams目录下，然后用脚本批量导出。

目录结构大概是这样的：

docs/ ├── README.md └── diagrams/ ├── auth-flow.mmd ├── order-sequence.mmd └── release-gantt.mmd

在 Linux/macOS 下，一行 for 循环就能把整个目录导出成图片：

mkdir -p docs/images for f in docs/diagrams/*.mmd; do mmdc -i "$f" -o "docs/images/$(basename "$f" .mmd).svg" -b transparent done

-b transparent表示导出透明背景，这样图片放进浅色或者深色文档里都不会留个白色方块。再进一步，你还可以把这段命令写进package.json的 scripts 里：

{ "scripts": { "diagrams": "for f in docs/diagrams/*.mmd; do mmdc -i \"$f\" -o \"docs/images/$(basename \"$f\" .mmd).svg\" -b transparent; done" } }

之后团队统一跑npm run diagrams就能重新生成所有图，不用谁再去手动截图。这也是我最推荐团队使用的方式：源文件入库，图片可再生成。

4.3 Markdown 里嵌 Mermaid 的几个隐藏约定

这里有几个我踩过坑后总结的约定：

• Mermaid 代码块必须用围栏式代码块，标记语言是mermaid，三个反引号后直接跟mermaid，不要加多余空格；
• 一个代码块里只能有一个图定义。如果你想在一篇文档里画三个图，就写三个独立的 mermaid 代码块；
• 不能把 mermaid 代码块嵌套在其他列表项里缩进超过一定层级，否则 Markdown 解析器可能把它当成纯文本；
• 如果你用的是旧版 VSCode 或旧版 Windows 自带记事本编辑的文档，注意中文标点不要混进语法里。最经典的报错就是把中文括号（）写成了节点语法里的英文括号()。

这些约定看起来很基础，但我在帮同事排查问题时，十次有八次都是这类原因。

5. 我们实测踩过的坑：渲染失败、乱码、版本不一致

5.1 预览空白或报错时的标准排查顺序

Mermaid 预览出问题，通常有三种表现：预览区完全空白、显示红框错误信息、或者代码原样展示而不是渲染成图。我的排查顺序是这样：

第一步，看代码块语言标记是不是mermaid，记住是小写。写成了Mermaid或者mmd，部分插件就是不理你。

第二步，看插件有没有被禁用。打开扩展面板，搜索 Markdown Preview Mermaid Support，确认状态是“启用”。插件装好之后如果没生效，按Ctrl+Shift+P输入 “Developer: Reload Window” 重载一次窗口。

第三步，把 mermaid 代码复制到 mermaid.live 的左侧编辑区。live editor 的报错机制比 VSCode 插件更直观，它会用黄色波浪线标出问题行。大部分语法错误（括号不匹配、引号缺失、方向关键字写错）都能在 live editor 里秒级暴露。

第四步，检查文档中是否存在多个同名节点或重复边定义。Mermaid 对边和节点的冲突处理比较宽容，但部分版本会出现“一张图里有两条一模一样的边导致渲染方向混乱”的情况。

还有一个小技巧：如果整个 Markdown 预览打不开，别急着怀疑 Mermaid，先看看普通文字能不能正常显示。有时候是 Markdown Preview Enhanced 的自定义样式写坏了，禁用该插件再试一次。

5.2 中文变成方块的真正原因和解决办法

在 VSCode 的预览里，Mermaid 中文通常没问题，因为预览走的是本地浏览器的字体渲染。但用 mermaid-cli 导出 PNG/SVG 时，中文变成方块的概率就非常高。原因不是 Mermaid 不支持中文，而是 Puppeteer 启动的精简 Chromium 里没有安装中文字体，渲染时找不到对应字形。

解决办法有两个方向：

第一个方向，给 mmdc 指定一个系统已有的中文字体配置文件。新建一个mermaid-config.json：

{ "fontFamily": "'Microsoft YaHei', 'PingFang SC', 'Noto Sans CJK SC', sans-serif" }

然后执行：

mmdc -c mermaid-config.json -i docs/diagrams/auth-flow.mmd -o docs/images/auth-flow.svg

第二个方向，Windows 上如果系统中已经装了微软雅黑，但导出还是乱码，可以检查一下环境变量PUPPETEER_EXECUTABLE_PATH是否指向了你日常使用的 Chrome/Edge。使用完整版浏览器渲染时，字体加载通常比精简版 Chromium 更可靠。

另外提醒一句：SVG 文件里如果引用了本地字体，拷贝到别的机器上可能因为缺字体而显示不对。最稳妥的做法是导出 PNG 用于外部文档，SVG 只在网页场景中使用。

5.3 VSCode 插件里的 Mermaid 版本落后于官网

Mermaid 语言迭代速度不慢，新增了block-beta、quadrantChart等新图型。你明明在 mermaid.live 上跑得好好的，回到 VSCode 预览却报“unknown diagram type”，这时候基本可以断定是插件内置的 Mermaid 版本太旧。

解决办法就是升级插件。在扩展市场里搜索 Markdown Preview Mermaid Support，如果有更新，直接点 Update。更新后如果还不行，再重载一次窗口。VSCode 插件本质上是在本地调用了 Mermaid 的 JS 库，扩展作者不更新，你就没办法使用新语法。所以遇到版本问题别硬调代码，先更新插件。

5.4 Windows 环境下 npm 安装和路径的小麻烦

Windows 上使用 mermaid-cli 最常见的两个问题，一个是 npm 全局安装权限，另一个是路径包含空格。npm 全局安装如果报 EACCES 或权限错误，多半是 Node.js 安装时没有配置好全局目录。用管理员身份打开终端再执行安装能解决，但我更推荐用 nvm-windows 管理 Node.js 版本，这样全局包都装在用户目录下，不需要管理员权限。

路径含空格的问题主要出现在 mmdc 参数上。比如你的项目路径是D:/My Project/docs/diagrams，命令行里没加引号，解析就会出错。按前面那种for循环写法，用双引号包住$f和输出路径，能避掉绝大多数问题。

6. 在实际项目里我是怎么用的：技术方案评审与团队规范

6.1 一次技术评审里的完整示例

拿一次真实的登录授权方案评审举例。我通常会在方案文档开头放一张 Mermaid 流程图，然后用时序图描述具体请求流程。你可以直接参考这个结构：

flowchart TD A[用户访问业务页面] --> B{本地是否已有token} B -- 有 --> C{token是否过期} C -- 否 --> D[携带token访问接口] C -- 是 --> E[调用刷新token接口] E --> F{刷新是否成功} F -- 成功 --> D F -- 失败 --> G[跳转登录页] B -- 没有 --> G D --> H[返回业务数据]

评审时，参会者可以一边看这张图，一边对照代码逻辑提问。因为 Mermaid 源码就在文档里，任何人有疑问可以直接在评论区指出“第几行节点对应哪段代码”，比在图片上画红色箭头要精确得多。这也是我坚持在技术方案里用 Mermaid 而不是纯图片的理由：评审本身就是一次 code review，图也是代码的一部分。

6.2 团队约法三章：源文件、导出文件与命名规范

用了大半年之后，我和团队定了一套简单的规范，分享出来供参考：

• 所有 Mermaid 源文件统一放docs/diagrams，不直接散落在根目录；
• 导出的图片统一放docs/images，命名和源文件保持一致，比如auth-flow.mmd对应auth-flow.svg；
• .mmd文件提交到仓库，导出的.png要不要提交看情况。如果图片只是发布用的，可以加进.gitignore，需要用的时候跑一次npm run diagrams；
• 每张图的标题用%% 注释写在文件顶部，说明这张图什么时候加的、给谁看、对应哪个需求。Mermaid 支持百分号注释，这是很多人忽略的好功能；
• 命名建议用功能名，不要用final2_reallyfinal_v3.mmd，一旦图和代码一样需要长期维护，“v3”这种后缀只会制造混乱。

另外，我强烈建议把 mermaid 代码块写进 VSCode 的用户代码片段里。新建一个 Markdown 代码片段：

{ "Mermaid Block": { "prefix": "mmd", "body": "```mermaid\n$0\n```" } }

以后在 Markdown 里输入mmd再按 Tab，代码块就直接出来了。别小看这个习惯，我写文档时几乎每天都会触发几十次。

6.3 我现在的例行工作流

现在我的日常已经固定成一套动作：在docs/diagrams里直接新建.mmd文件，写到一半打开 VSCode 右侧预览确认布局；写完后在README.md里用 Markdown 语法把图嵌进去；提交 PR 前跑一次npm run diagrams导出新图片。代码改、图就改，图改、文档重新生成。

如果你现在还在各种在线画图工具之间反复横跳，我真心建议花一个下午把本文里的示例都敲一遍。装插件五分鐘，学语法一个钟头，剩下的就是每天省下的大量截图、上传、粘贴和对齐时间。Mermaid 不是万能的，并不适合做像素级好看的 UI 稿或复杂拓扑图，但在“技术方案、接口说明、架构梳理”这些日常场景里，它已经足够能干，而且能干很久。