企业官网建设流程全解析

画图这件事，是每个写文档的人都绕不开的坎。我之前给项目补一份接口文档，里面要画一个下单支付的流程，打开ProcessOn，新建，拖节点，连箭头……折腾二十分钟，图是画出来了，可第二天产品经理说逻辑改一下，我又得重新拖一遍，连线的角度还得调半天，整个人都麻了。后来换了Mermaid配合VSCode插件做流程图实时预览，这类场景基本被根治了：左侧写几行文本，右侧图表立刻刷新，改逻辑就改字，图的样式完全不会乱。

如果你还没接触过Mermaid，我给你一句话解释：它是一种用纯文本描述图表的语法，把流程、时序、甘特、状态这些内容写成类似代码的文本，再由渲染器生成真正的图形。你不需要记住每个细节，只需要掌握最常用的一小部分语法，就能在VSCode里画出能放进技术方案、毕业设计和项目汇报里的流程图。这篇内容我会把VSCode插件选型、5分钟搭好实时预览环境、常用语法写法，以及我实际踩过的报错和排查方法一次性讲清楚。

文章不要求你有很强的编程基础，只要电脑上装好了VSCode，跟着一步一步走就能跑起来。想少走弯路的话，建议不要跳过第4节，报错排查那部分都是我拿真实经历换来的。

1. Mermaid是什么，为什么我的流程图方案从拖拽改成了写代码

1.1 Mermaid不止能画流程图，这些图都能用文本生成

很多人一提到Mermaid就只想到流程图，其实它支持的类型比想象中多。我日常用得最多的是graph流程图和sequenceDiagram时序图，但偶尔也会用gantt甘特图排一下项目计划，用stateDiagram-v2状态图画接口的状态流转，用classDiagram类图描述核心模块关系。

这些图表有一个共同特点：全部由文本节点和连线组成，没有手动拖拽的物理坐标。你写一个A --> B，它就从A连到B；你换一行写A --> C，新的分支自然出现。我最早被Mermaid吸引，就是因为它符合程序员“代码即一切”的习惯，图和代码可以一起提交到Git仓库，需求变了直接改文本，而不是在一堆图形元素里找线条。

另外，Mermaid还支持pie饼图、mindmap思维导图、journey用户旅程图等。你要是平时做项目规划、写产品文档，这些类型也都能用上。学习曲线并不陡，流程图语法半小时能入门，时序图和甘特图各自再花十几分钟看一遍示例，基本就能上手。

1.2 对比一圈之后，为什么我最终留在VSCode

我刚接触Mermaid时，试过Mermaid官方提供的Live Editor在线编辑器，也用Typora写过带Mermaid的Markdown文档，还用过draw.io这类拖拽工具。这几类方案各有各的处境，我用一张表给你看清楚：

这轮对比下来，VSCode方案最大的优势不是单一功能最强，而是它把所有工作放到同一个环境里。我写代码用VSCode，写Markdown用VSCode，画图也用VSCode，文档里的图可以直接引用本地md文件里的Mermaid代码，不需要导出图片上传到文档系统，改起来特别顺。

1.3 这套方案真正解决了我哪些痛点

第一个痛点是版本管理。用拖拽工具生成的图片，本质上是一张静态图，需求改了旧图就作废了。Mermaid源码是文本文件，丢进Git仓库里，谁改过、改了什么都清清楚楚，代码review时也能直接看到流程变化，这是我最满意的一点。

第二个痛点是协作成本。同事拿到一个md文件，装上插件打开就能看到图，不需要单独安装Visio，也不需要一个一个发图片。新人接手项目，直接看标注了Mermaid代码的文档，能同时理解代码逻辑和流程结构。

第三个痛点是效率。画一张带判断分支的流程图，用拖拽工具至少需要5到10分钟，用Mermaid写文本，熟练之后1分钟能完成第一版，后面调整只改箭头和目标节点就行，不会破坏整体布局。后面我会具体演示这个流程。

2. 5分钟搭好VSCode实时预览环境：插件安装与第一次出图

2.1 插件选型：Markdown Preview Enhanced和专用的Mermaid Support怎么选

VSCode插件市场里搜Mermaid，会出现很多结果，我个人的建议是不要贪多，装两个就够了：一个是Markdown Preview Enhanced，另一个是Markdown Preview Mermaid Support。

Markdown Preview Enhanced（以下简称MPE）是老牌Markdown增强插件，支持Mermaid渲染、导出PDF/HTML/PNG、自定义预览主题等，功能非常全。Markdown Preview Mermaid Support则是一个专门负责Mermaid渲染的插件，更轻量，适合你只是想在普通Markdown预览里顺便看到流程图。

如果你只是为了画Mermaid图，不想折腾其他功能，单独装Markdown Preview Mermaid Support也够用，预览时按Ctrl+Shift+V就能看到渲染效果。如果你和我一样，平时还要写技术文档、导出汇报材料，那建议以MPE为主，它能做的事情更多。两个插件同时装一般不会冲突，但我自己实际测试下来，MPE一个就能覆盖绝大多数场景，所以我日常主力就是MPE。

2.2 一步步安装插件并完成基础设置

第1步，打开VSCode，点击左侧边栏的扩展图标，或者按快捷键Ctrl+Shift+X进入扩展市场。在搜索框输入“Markdown Preview Enhanced”，找到之后点Install，等待安装完成。

第2步，如果你决定也装Markdown Preview Mermaid Support，在搜索框换成这个名字，同样点Install。装完之后，建议你用Ctrl+Shift+P打开命令面板，输入“Reload Window”执行重新加载，确保插件完全生效。这一步经常被忽略，新装的插件有时不会立即生效，尤其是在改了配置之后。

第3步，按Ctrl+,打开设置页，在搜索框里输入“markdown-preview-enhanced”，确认插件配置能正常读取。MPE默认配置可以直接使用，不需要额外改太多东西。我自己的设置里只改了两项，一个是预览主题，一个是代码块主题，让暗色环境看起来更舒服：

{ "markdown-preview-enhanced.previewTheme": "one-dark.css", "markdown-preview-enhanced.codeBlockTheme": "one-dark.css" }

如果你用浅色主题，这两项可以删掉，保持默认值即可。配置不用贪多，等熟悉以后按需再调整。

2.3 新建文档，写第一段Mermaid代码

安装完成后，新建一个文件，命名为test.md。这里要注意，文件后缀必须要是.md才行，VSCode和插件才会按Markdown语法处理。

在文件里粘贴下面的内容，这一段是Mermaid源码，不是普通文字：

graph TD A[开始] --> B{是否登录} B -- 是 --> C[进入首页] B -- 否 --> D[跳转登录页] D --> E[输入账号密码] E --> F{校验是否通过} F -- 通过 --> C F -- 不通过 --> E

在Markdown里面真正要让插件识别成Mermaid代码块，需要用三个反引号把这段源码包起来，并在起始反引号后面写上语言标记mermaid。也就是说，代码块的开头要写三个反引号加mermaid，结尾写三个反引号。上面这段只是展示核心语法，实际放进md文件时要加上包裹标记。

写完之后按Ctrl+Shift+V，如果用的MPE，也可以按Ctrl+K V把预览窗口放到右侧。只要配置正确，右侧就会渲染出一张带判断分支的流程图：开始节点是A，菱形判断是B，B分发到“是/否”两条支线，登录校验不通过还会回到输入账号密码的节点重新循环。看到这张图，说明你的实时预览环境已经通了。

2.4 把预览体验调顺手：常用快捷键与导出

预览常用快捷键就两个：Ctrl+Shift+V是整页预览，适合查看文档整体效果；Ctrl+K V是侧边预览，适合边改代码边看结果，我平时用后者更多。

MPE还有一个非常好用的功能，是在预览窗口右键导出。你可以导出为PDF、PNG、JPEG、HTML等多种格式。我一般写方案文档时用HTML导出，做PPT素材时用PNG导出。第一次导出PDF时，插件可能会下载一个无头浏览器组件，需要稍等一会儿，如果下载失败就重新点一次，一般重试就能成功。

另外，MPE支持在Markdown文件顶部写YAML front-matter来控制导出样式，比如设置导出后的页面标题、纸张大小等。新手可以先不用管这个，后续有需求再查官方文档。

3. 流程图核心语法速览：看懂节点、连线和框的含义

3.1 节点形状、连接线和方向，一篇文章看懂

Mermaid流程图语法并不复杂，核心就两块：定义节点和定义连线。节点写法是通过“节点ID + 形状 + 展示文字”组成的，形状不同，渲染出来的图形也不同。

我用一个代码块把常用节点形状都串起来，方便你对照：

graph LR A[矩形] --> B(圆角矩形) B --> C{菱形判断} C -->|是| D((圆形)) C -->|否| E[[子程序]] E -. 虚线注释 .-> F[平行四边形] F ==> G[加粗箭头]

在这个例子里，[ ]显示为矩形，通常表示处理过程；( )显示为圆角矩形，常用来表示开始或结束；{ }显示为菱形，专门用来做判断分支；( ( ) )显示为圆形，一般代表连接点或特殊状态；[[ ]]显示为子程序。连线的写法也有讲究，-->是普通实线箭头，---是不带箭头的实线，-.->是虚线箭头，==>是加粗箭头，-->|文字|是给连线加上注释文字。

方向声明位于graph关键字后面，TD表示从上到下，LR表示从左到右，BT表示从下到上，RL表示从右到左。我个人写逻辑流程时偏爱TD，写模块关系图时用LR多一点。

3.2 带判断和回环的登录流程：一个例子覆盖80%场景

日常画得最多的流程，基本逃不出“开始 -> 判断 -> 分支处理 -> 可能回环 -> 结束”这套结构。我用登录场景再给你拆解一遍：

graph TD S([开始]) --> Input[输入账号密码] Input --> Check{账号密码正确?} Check -- 否 --> Input Check -- 是 --> Role{角色判断} Role -- 普通用户 --> Home[用户首页] Role -- 管理员 --> Admin[管理后台] Home --> E([结束]) Admin --> E

这段代码里出现了几个关键手法：一是用S([开始])把开始节点定义为圆形，视觉上更贴近标准流程图；二是判断节点Check的“否”分支又指回Input，实现回环，用户输错密码可以重新输入；三是用Role{角色判断}做了二级判断，体现不同角色的不同流向。这个结构可以直接套用到订单状态判断、权限校验、数据清洗流程等场景，把节点文字换一下就是新图。

3.3 不只是流程图：时序图和简单的甘特图怎么写

时序图在技术文档里出现的频率相当高，尤其是描述接口调用关系时。比如下单支付，Mermaid语法可以这样写：

sequenceDiagram participant U as 用户 participant O as 订单系统 participant P as 支付系统 U->>O: 提交订单 O->>P: 发起支付请求 P-->>O: 返回支付结果 O-->>U: 展示订单状态

participant用来定义参与者并设置别名，->>表示实线请求，-->>表示虚线返回。渲染出来的图会按时间顺序从上到下排列，非常适合放在接口设计文档里，比截图更清晰，也更容易维护。

甘特图我一般在排项目计划时用，虽然功能没有专业项目管理软件强，但胜在不需要离开文档环境：

gantt title 项目简单计划 dateFormat YYYY-MM-DD section 准备阶段 需求调研 :done, a1, 2025-03-01, 7d 方案设计 :active, a2, after a1, 5d section 开发阶段 模块开发 :a3, after a2, 10d

每一行的格式大致是“任务名 + 冒号 + 状态标记 + 任务ID + 时间范围”。done表示已完成，active表示进行中，未加状态标记的默认是待办。这个对写月度汇报、项目周报很好用。

3.4 流程图各种框的含义，其实和Mermaid是一一对应的

结合前面说到的节点形状，我再把标准流程图里常见框的含义和Mermaid写法对应起来。如果你是在大学作业或毕业设计里画系统流程图，这些对应关系可以帮你把文本代码转换成符合课程要求的图。

另外，在Mermaid中还能用subgraph把一组节点包成子图，渲染出来就是带边框的分组区域。这个特性在画模块边界、系统边界时非常有用，比如把“用户端操作”和“服务端处理”分别放在两个子图里，结构一眼就能看懂。子图写法是subgraph 标题开始，end结束，中间正常写节点和连线。

4. 常见报错与问题排查实录：白屏、语法错误、中文乱码一次说清

4.1 预览白屏：先按这三步排查

预览白屏是我遇到最多的问题，通常不是插件坏了，而是没有满足触发条件。第一次看到白屏别慌，按顺序排查：先确认你打开的文件扩展名是.md，如果后缀是.txt，插件默认不会启动Markdown渲染；再确认你使用的是MPE的预览，而不是VSCode内置的普通Markdown预览，两者的渲染范围不一样；最后检查代码块是否被正确包裹了三个反引号，语言标记是否写成了mermaid。

如果这些都检查过仍然白屏，可以执行一次Ctrl+Shift+P，输入“Reload Window”重新加载窗口。很多时候修改插件配置后，窗口不重载，新的设置不会立刻生效。我碰到过几次白屏，最后都是重载窗口解决的。

4.2 语法报错排查：为什么网上复制的代码也报错

Mermaid的报错信息一般会提示Parse error on line X，但它不会直接告诉你是哪个符号写错了。我总结下来，最常见的错误源有三个：一是节点文字里混进了中文引号、中文括号或全角冒号，Mermaid只能识别英文符号；二是节点ID和显示文字之间的括号没配对，比如写了A[文字忘了右括号；三是子图或代码块的缩进不统一，有的缩进用Tab，有的用空格，导致解析器认为节点定义发生了断层。

网上复制的代买报错，十有八九是上面第二种和第三种情况。我的处理方法是，先把代码粘贴到Mermaid官方在线编辑器里，它会用更友好的方式提示出错位置。确认语法没问题了，再把代码搬回VSCode。还有一个小细节：graph TD和graph TD;差一个分号，有些版本对分号处理宽松，但为了保险，建议在方向声明后不要乱加分号。

4.3 导出PDF/PNG中文变豆腐块：字体和Puppeteer的问题

MPE导出依赖Puppeteer调用无头浏览器渲染页面，而在某些系统环境里，默认字体列表里没有中文字体，于是导出的PDF或PNG里，中文全部显示成一个个方框。这个问题不是你的Mermaid代码写错了，而是渲染环境缺少字体。

解决办法有两种。简单粗暴的做法是给系统安装中文字体，Windows一般自带微软雅黑，macOS自带苹方，一般不会缺；Linux服务器或者精简系统最容易遇到这个问题，装一个fonts-noto-cjk之类的字体包就能缓解。如果想要更可控，可以给MPE配置puppeteer参数，在settings.json里指定渲染时的默认字体，或者导出时在HTML模板中设置font-family。我自己用的方式是尽量在流程节点里少放长句中文，保留关键动作短语，字体压力小了，导出效果也更稳定。

4.4 快捷键冲突、版本不一致、同事看不到图

另一个高频问题是快捷键不管用。Ctrl+K V在某些键盘布局或插件组合下，可能被其他插件抢走。这时可以按Ctrl+Shift+P打开键盘快捷方式设置，搜索“markdown.preview.open”这一类命令名，改成自己习惯的按键。

还有同事打开你的md文件看不到流程图，常见原因是对方根本没装相应插件，或者装的是老版本，不支持你用到的新语法。Mermaid版本迭代比较快，新版语法比如mindmap、stateDiagram-v2，在旧插件上会直接报错或忽略。遇到这种情况，我一般让同事升级插件到最新版，或者干脆把导出的图片也提交到仓库里，方便不装插件的人直接看图。

4.5 一份可以直接抄的报错速查表

为了方便你以后排查，我把常见现象和解决办法整理成一张表：

这张表我贴在项目文档里，团队有人问起来直接发链接，省了很多重复沟通时间。

4.6 用熟之后，我建议你收藏这几个独家技巧

第一个技巧是建立自己的Mermaid模板库。我把登录判断、接口调用、项目排期这些高频场景的Mermaid代码存成一个mermaid-templates.md文件，放在项目docs目录下。接到新需求时复制一段改一改，5分钟出图真不是夸张。

第二个技巧是善用%%注释。Mermaid支持在代码里写注释，以两个百分号开头，整行都会被忽略。我通常在比较复杂的分支前写一行注释，说明这段流程的业务意图，方便自己后续维护，也让同事能快速理解。

第三个技巧是节点文字尽量简短。如果你把一整个长句塞进节点，渲染出来的框会变得特别宽，整个图的比例很难看。我一般会把节点文字控制在6到8个汉字以内，更长的说明写到连线文字或文档正文里。

第四个技巧是养成保存预览的习惯。MPE默认会跟随文件变更自动刷新，但在文件较多、图表较大的时候偶尔会延迟，保存一下基本都能触发刷新。这不算什么高深操作，但在关键时刻能避免“改了不生效”的错觉。

我个人在实际使用中最大的感受是，Mermaid并不是要取代所有画图工具，它更适合那些需要频繁修改、需要进入版本库、需要多人协作的流程图形。你如果平时只是画一张不再改动的手绘风格示意图，拖拽工具也没问题；但只要图会变、会跟着代码走，文本化的Mermaid就会让你轻松很多。

最后再分享一个小技巧：如果你要把Mermaid代码贴进博客、公众号或者团队知识库，最好在发表前导出一次图片，把图和代码同时放上去，这样不管对方环境是否装插件，都能快速看懂你要表达的结构。流程图画得再漂亮，最终目的是让别人理解你的思路，而不是炫技。