企业官网建设流程全解析

流程图这种玩意儿，过去要靠 Visio、ProcessOn 这类可视化工具，画框图、拉箭头、调对齐，改一版逻辑基本等于重画一遍。我自己折腾了几年之后，固定下来的方案很朴素：用 VSCode 写 Markdown，在 Markdown 里用 Mermaid 语法描述流程，再装一个 Markdown Preview Mermaid Support 插件，按Ctrl+K V就能在编辑器右侧看到实时预览。整个过程不用切换窗口，也不用拖拽，5 分钟足够跑通。这篇就把插件安装、基础配置、Mermaid 语法、各种框的含义和常见报错一次讲清楚，适合正在写技术文档、毕业设计、系统流程图或者想提高文档可维护性的人。

1. 为什么用 VSCode 写 Mermaid 流程图

1.1 Mermaid 到底是什么

Mermaid 是一个基于 JavaScript 的“文本图表工具”。它和 Markdown 很像，Markdown 用文本表示排版结构，Mermaid 用文本表示图形结构。你用一行flowchart TD声明方向，再用几行文字描述“谁连到谁”，渲染引擎自动把节点摆好、把线条连好、把颜色配上。GitHub 的 Markdown 预览、很多博客平台和笔记工具都内置了 Mermaid 渲染，说明它已经成了文本绘图的通用语言。

我最早用 Mermaid 是为了维护项目里的接口文档。以前画架构图、流程图用的是 Visio，画完之后是一张图片，存在docs目录里。一旦接口流程变了，要打开.vsdx文件重新拖拽，导出图片覆盖。更麻烦的是，图片没法用git diff看出改动，别人改了之后除非肉眼对比，否则根本不知道哪里变了。Mermaid 本质是把图画代码化，让流程图的修改变成一个普通的文本改动。这样的好处是直接进代码仓库版本管理，评审时git diff能精确到某一根连线，这是传统画图工具做不到的。

1.2 实时预览解决的是“改图效率”问题

有人会说，Draw.io 也有实时预览，为什么非要折腾 VSCode？我的体验是，VSCode 加 Mermaid 的组合解决的不是“画图”这一个点，而是把“写文档”和“画流程”合并成了同一个动作。你在写 README、接口文档、方案设计时，停下来画图是很打断思路的。用 Mermaid 之后，流程图就嵌在文档对应的位置，哪里需要流程说明，哪里就写一段 Mermaid 描述。按一下快捷键，右侧马上刷新，思路不会断。

特别是以下三类朋友，我强烈建议试试：第一类，写技术文档的开发，流程和代码同仓库维护；第二类，做毕业设计的学生，画系统流程图、算法流程图、用户管理模块流程图放论文，用文本画图比反复框选对齐快很多；第三类，做产品需求梳理的人，用流程图表达判断分支、异常分支，改起来比 PPT 舒服。你不需要成为前端工程师，也不需要懂 Canvas、SVG，会写几行文本就行。

2. 五分钟快速搭建 Mermaid 实时预览环境

2.1 环境准备：VSCode 安装、中文界面与插件市场

如果你电脑上还没有 VSCode，先去官网下载安装包。这一步网上教程很多，我只提醒两点：一是尽量到官方站点下载，避免搜索引擎出来的第三方下载站捆绑其他东西；二是安装完成后建议顺手做两件事：设置中文界面，安装常用扩展。设置中文的方法是在扩展面板搜索“Chinese (Simplified) (简体中文) Language Pack”，安装后右下角会提示重启，重启后就是中文界面。很多人第一次打开 VSCode 被英文界面劝退，这步能省掉很多认知成本。

如果你之前已经折腾过 VSCode 配置 Python 或 C/C++ 环境，那你对左侧扩展图标、命令面板、settings.json这些概念应该不陌生。没有配置过也没关系，Mermaid 预览插件的安装比配置编译器简单得多，不需要改系统变量，不需要写launch.json，只需要在扩展面板点一下 Install。插件市场就是 VSCode 左侧那个四个方块图标的扩展面板。搜索插件、安装、启用，三步就能完成。需要提醒的是，尽量只安装来自官方市场、开源地址明确、下载量高的插件。第三方搬运的插件市场可能存在安全风险，还可能和官方插件冲突，不建议碰。

2.2 插件选型：Markdown Preview Mermaid Support 与 Markdown Preview Enhanced

Mermaid 相关插件在扩展市场里非常多，常见的有 Markdown Preview Mermaid Support、Markdown Preview Enhanced、Mermaid Editor、Mermaid Markdown Syntax Highlighting 等。我自己的建议是：不追求全家桶，先装一个稳定的预览插件。我主力用的是 Markdown Preview Mermaid Support，作者是 Matt Bierner，这个作者还做了 Markdown All in One 等一批高质量扩展。该插件可以直接在 VSCode 内置 Markdown 预览中渲染 Mermaid 图，和Ctrl+Shift+V、Ctrl+K V两个内置预览快捷键完美配合。

如果你的需求不止流程图，还想要导出 PDF、PNG、自定义 CSS、数学公式、图表等能力，那就选 Markdown Preview Enhanced，它内置了 Mermaid 支持，功能更像一个完整的 Markdown 工作台。但注意：这两个插件同时装也基本没问题，前提是不要重复启用多个 Mermaid 插件。我见过有人在扩展面板里装了四五个同类插件，结果预览时有的报错、有的空白、有的样式冲突，最后把多余的禁用才恢复。所以装插件的原则很简单：够用就行，遇到问题再补，别一开始就装一筐。

安装步骤其实只有四步。第一步，在扩展市场搜索“Markdown Preview Mermaid Support”；第二步，点击 Install；第三步，新建一个test.md文件；第四步，在文件里写一段最基础的 Mermaid 描述，注意语言标识要填mermaid或mmd，然后打开预览。如果你以前没有写过任何 Mermaid，先别急着画复杂的，从一个三行结构开始，比如flowchart TD表示从上往下画，然后写一个开始节点连到一个判断节点，再连到结束节点。只要能渲染出来，说明环境已经通了。这一步跑通之后，后面所有问题都有了排查基础。

2.3 打开预览的三种方式与快捷键设置

VSCode 内置 Markdown 预览的快捷键有两个：Ctrl+Shift+V是在编辑器外单独打开一个预览页，适合大屏对比；Ctrl+K V是把预览窗口并排在右侧，这是我最常用的。打开侧边预览后，只要你在左边的 Markdown 文件里保存，预览就会实时刷新。Mermaid 也是同一个刷新链路：你改完节点文字，切回预览页，基本秒级更新。这个“实时”体验，才是整个方案的核心价值。

除了快捷键，还可以用命令面板：按Ctrl+Shift+P，输入“Markdown: Open Preview to the Side”，回车。也可以直接右键编辑器标签页，选择“打开侧边预览”。如果你觉得默认快捷键和别的插件冲突，可以自定义按键。打开命令面板，输入“Preferences: Open Keyboard Shortcuts”，搜索命令markdown.showPreviewToSide，然后修改绑定。下面是一个keybindings.json的示例，把侧边预览绑定到Ctrl+Alt+V：

{ "key": "ctrl+alt+v", "command": "markdown.showPreviewToSide" }

保存后立即生效，不用担心需要重启。我习惯把预览快捷键单独留在Ctrl+K V，但如果你经常在终端和 VSCode 之间切换，可以考虑改成更顺手的组合，免得每次都要低头找按键。

3. Mermaid 流程图核心语法与图形含义

3.1 流程图骨架：方向、节点和连线

Mermaid 的 flowchart 语法其实不难，核心就三件事：方向、节点、连线。方向关键字放在图的最开始，flowchart TD表示从上到下，flowchart LR表示从左到右，flowchart BT表示从下到上，flowchart RL表示从右到左。画普通流程、系统流程图、算法流程图，我一般用TD；画时序相关的业务流转，比如从用户点击到后台处理的调用链，用LR更合适。

节点写成节点ID[展示文本]的形式，ID 是你给这个节点起的唯一名字，展示文本是渲染后显示出来的内容。连线最基本的是-->表示有向箭头，---表示无箭头连线，-.->表示虚线箭头，==>表示粗箭头。还可以在连线上写字，比如A -->|是| B表示从 A 到 B 的连线标签是“是”。整个图就是由这些行组成的。你需要理解一个关键点：Mermaid 渲染时会自动计算节点位置，你不用告诉它“这个框放在哪里”，只需告诉它“这个框和那个框什么关系”。这也是 Mermaid 比拖拽画图效率高的原因，它把布局这个最耗时的活儿交给了渲染引擎。

如果一开始不熟悉，我建议先画一个“开始 -> 判断 -> 结束”的三节点图，把方向、节点、连线这三个概念跑通。然后逐步增加节点文本、连线标签、不同形状。不要一上来就画几十个节点的大图，那样报错时不好定位，自动布局也会让你很崩溃。

3.2 各种框的含义与适用场景

用 Mermaid 画流程图，最常被问到的是“这些框到底什么意思”。传统流程图里，不同框形有约定俗成的含义。Mermaid 通过节点语法的不同括号来区分形状。我整理了一个常用速查表：

画常规业务流程图时，我一般只用三种形状：矩形表示操作，菱形表示判断，圆角矩形或体育场形表示开始结束。用太多形状反而可读性差。如果是画图书馆管理系统毕业设计里的流程图，也不建议把所有节点都画在同一张图里。可以把登录、借书、还书、管理员操作拆成几个子图或几张图，每一张用上述基本形状即可。形状只是辅助读者理解，不要为了体现语法多厉害而炫技。

3.3 子图、样式和中文渲染处理

当流程图内容超过十来个节点，建议用subgraph划分子图。子图的基本结构是subgraph 子图名开头，end结束，子图里可以放若干节点和连线。它非常适合表达模块边界，比如在一个用户管理模块流程图中，登录、权限校验、用户 CRUD、日志记录分别放到不同的子图里，整个图看着就清楚很多。渲染时子图外面会有边框和题目标签，读者一眼可以分清楚这是哪个系统或哪个阶段。

样式方面，可以为单个节点写style 节点ID fill:#f66,stroke:#333,color:#fff，也可以用classDef定义一组样式，再用class 节点ID,节点ID2 类名批量应用。比如把判断节点统一涂成黄色，把异常节点统一涂成红色，对阅读体验提升很大。我的经验是，样式规则不要超过三四种颜色，否则图会显得很花。

关于中文显示，这是很多新手会踩的坑。Mermaid 本身支持中文文本，但默认渲染字体不一定覆盖中文字符，有时候会显示成方块，或者因为字体宽度问题导致节点宽度异常。解决办法是在 Mermaid 初始化指令里指定字体，在代码块开头加一段初始化配置，把fontFamily设置成系统中文字体。不同的预览插件对初始化指令的支持不太一样，如果写完没效果，优先看插件的 README，确认支持哪种初始化写法。另一个更省事的办法是换用 Markdown Preview Enhanced 的主题，很多国内用户会在它的配置里设置中文字体。实测下来，在 VSCode 里用中文字体时，大部分节点都能正常显示。

4. 从流程图扩展到思维导图、BPMN 与文档工作流

4.1 用 Mermaid 快速画思维导图和用户模块流程图

Mermaid 新版本还支持思维导图（mindmap），写法更简单，类似列表缩进。不过 VSCode 里的 Markdown 预览插件不一定支持最新语法，所以如果你只是要画思维导图，我更推荐直接用 XMind 这类专业工具，它内置了漂亮的主题和导出能力。Mermaid 的长处还是在需要版本管理的场景。比如用户管理模块流程图，这个在系统设计文档里特别常见：用户进入系统，先判断是否已登录，未登录跳到登录页，登录后判断角色，管理员可以进入管理后台，普通用户只能进入个人中心，所有操作记录写日志。这样一个流程用 Mermaid 文本描述，放在文档中，比截图更好维护。

做毕业设计的时候，很多人会为了“流程图怎么画”发愁。我的建议是：先用 Mermaid 在 VSCode 里画好，导出为 PNG/SVG，再粘贴到论文里。好处是你在论文草稿阶段可以随时改，不用反复截图。比如图书馆管理系统里的还书流程，读者提交还书请求，系统检查是否有逾期罚款，如果有就提示先交罚款，没有就登记归还、更新库存状态，最后生成还书记录。用文本描述这样一个流程，几分钟就能画好，PDF 导出后分辨率也够用。

4.2 BPMN 网关、泳道与 Mermaid 的对应关系

如果是正规的企业流程建模，你会遇到 BPMN 这个名词。BPMN 是一种比 Mermaid 严谨得多的流程建模标准，里面有事件、活动、网关、泳道等概念。BPMN 网关的使用也比较讲究，排他网关、并行网关、包容网关、事件网关各有不同的语义。Mermaid 的 flowchart 虽然可以画出类似的分支结构，但没有严格的网关语义，也没有泳道概念。所以你如果为了应付一个需要严谨建模的项目，应该去用支持 BPMN 的专业工具，而不是硬用 Mermaid。

但这不代表 Mermaid 没用。在很多日常场景下，Mermaid 的作用是“快速表达想法草稿”。你可以在 VSCode 里用 flowchart 把流程先画出来，给团队确认逻辑，等逻辑确认无误，再根据规范迁移到 BPMN 工具。这样等于用 Mermaid 承担了“草图阶段”的工作。我个人很少在正式交付文档里把 Mermaid 直接交给客户，但经常用它做内部沟通和方案讨论。

4.3 联合 Typora、XMind、Zotero 等工具打通写作链路

Mermaid 现在已经不是 VSCode 的专属能力。Typora 内置了对 Mermaid 的支持，打开.md文件就能渲染，适合快速写作；XMind 负责复杂思维导图；Zotero 是文献管理工具，写论文时收集参考文献。我自己的文档工作流是这样：VSCode 写 Markdown 正文，Mermaid 画流程图和时序图，Zotero 管理参考文献，最后导出 Word 或 PDF 交给导师或同事。Mermaid 图作为文本文件存到项目目录里，随时可以再编辑。

如果你愿意折腾，还可以在 VSCode 里装一些 AI 辅助插件，比如 Codex 这类代码生成工具。用自然语言描述你想要的流程，它有可能生成一份 Mermaid 代码，你再粘贴到 Markdown 里微调。我实测下来，简单的分支流程 AI 基本没问题，复杂的业务规则还是自己写更可控。总之，Mermaid 的价值是让流程图的“源文件”变成纯文本，这意味着它可以和其他工具链无缝衔接，不再是一张没法追溯的图片。

5. 常见报错与排查实录

5.1 预览空白、一直转圈或刷新无响应

这是我在各个群里被问到最多的一个问题。预览打开后是一片空白，或者一直显示加载中，常见原因有三个。第一，插件没有真正启用。装完插件后，VSCode 有时候需要重载窗口才生效，你直接在命令面板执行“Developer: Reload Window”即可。第二，你打开的不是 Markdown 文件，或者当前文件后缀不是.md。VSCode 的 Markdown 预览只对 Markdown 文件生效，如果你建了一个.txt文件，自然渲染不了。第三，Markdown 里的 Mermaid 语言标识写错了。预览插件依靠语言标识判断哪段内容是 Mermaid，识别不到就不会渲染。

排查顺序我建议这样：先确认扩展面板里已启用插件；再确认文件后缀和预览方式；然后新建一个最简单的测试文件，只写几行 Mermaid 描述；最后如果还不行，把所有其他 Markdown 预览类插件全部禁用，重载窗口再试。大多数情况下，问题都出在插件冲突上，而不是语法本身。如果你装了 Zotero 翻译插件之类的第三方工具，它不会影响 VSCode，但如果你装了多个 Markdown 预览扩展，冲突概率会显著上升。

5.2 语法看着没问题，但渲染成乱码或样式错乱

渲染出来但形状、颜色或文字不对，这种情况一般是语法细节问题。比如节点文本里带了中文括号，解析器容易被搞混；节点 ID 用了空格也会报错。我遇到过一个很典型的错误：想在节点文字里写“是否登录？”，直接把整句话写在方括号里，看着没问题，但 Mermaid 对某些字符敏感，导致解析中断。解决办法是给文本加引号，比如A["是否登录?"]，大部分情况下能解决。

还有版本差异问题。旧版本的 Mermaid 只支持graph TD，新版本推荐flowchart TD。如果你的插件版本比较旧，写成flowchart可能不识别；如果你在某个在线编辑器里写flowchart，回到老插件报错，那么改成graph试试。方向关键字拼写错误也很常见，TD写成了DT，报错提示一般会很明确，直接看报错所在行就能定位。遇到样式错乱，比如线太多交叉、节点互相重叠，多数不是语法问题，而是图画得太复杂。Mermaid 自动布局适合节点数量适中的图，超过二十个节点就别硬放在一张图里，用子图拆分是最好的解药。

5.3 快捷键失效、预览窗口被侧边栏挡住

Ctrl+K V在部分键盘布局或远程开发环境里确实可能不生效。如果你用的是远程 SSH、WSL 或容器开发，某些键会被终端或另一个扩展截获。这时候不用换电脑，直接改快捷键绑定。按Ctrl+Shift+P，输入“Preferences: Open Keyboard Shortcuts”，搜索markdown.showPreviewToSide，看当前绑定被谁占了，把它改成你顺手的组合键，比如前面提到的Ctrl+Alt+V。改完立刻能用，这也是 VSCode 比普通 Markdown 编辑器灵活的地方。

预览窗口打开后，如果你觉得右侧预览被文件树或代码面板挡住，可以把预览编辑器拖到独立的窗口，或者在命令面板里选择“Markdown: Open Preview”而不是“Open Preview to the Side”。在 Markdown Preview Enhanced 的配置里，也有一项可以控制预览窗口的打开方式，通常叫autoOpenPreviewToTheSide。打开之后，每次进入 Markdown 文件都会自动并排预览，省得每次按快捷键。

5.4 插件版本冲突、升级后崩溃

有一类问题不是配置引起的，而是插件版本或 VSCode 版本升级造成的。最常见的情况是：某天 VSCode 自动更新，某个 Markdown 扩展跟着更新，然后 Mermaid 预览突然失效。遇到这种问题，先别怀疑是自己配置错了。打开 OUTPUT 面板，在右上角下拉框里选择对应扩展的日志，看看有没有红色报错。如果是扩展版本和 VSCode 不兼容，可以直接在扩展列表中点击插件，选择“Install Another Version”，回退到上一个稳定版本。

另一个经验是：不要同时启用多个功能重叠的 Markdown 预览插件。Markdown Preview Enhanced、Markdown Preview Mermaid Support、Markdown All in One 这几个扩展功能有重合，一起使用时，可能会存在样式冲突或重复渲染。我自己的习惯是只装一个 Markdown Preview Mermaid Support 加 Markdown All in One，够用且稳定。如果某个项目需要 Markdown Preview Enhanced 的导出能力，我会单独在工作区里启用，而不是全局启用。

5.5 报错信息速查表

这一节把常见报错和解决办法整理成一张表，方便遇到问题时快速定位。你可以把这张表打印出来贴在显示器旁边，也可以存在项目文档里，遇到问题直接按图索骥。

上面这些解决方案，是我在实际项目中反复验证过的。大部分问题不是单一原因，而是多个因素叠加。遇到报错先别慌，按表格里的顺序逐项排查，一般都能解决。如果表格里的都试过还不行，最后一个通用办法是把 VSCode 设置清空、扩展全部禁用，再从零开始加回来，往往能找到那个隐藏的元凶。

6. 个人实操心得与最后提醒

6.1 我踩过的坑和沉淀下来的习惯

我用了 Mermaid 加 VSCode 至少三年，踩过的坑比写出来的多。最开始我也装了一堆插件，结果光是猜哪个插件在打架就花了一个晚上。现在我坚持一个原则：预览插件只装一个，语法拿不准先到 Mermaid Live Editor 里验证，再粘回 VSCode。Mermaid Live Editor 是官方出的在线测试工具，粘进去就能看渲染结果，报错提示也比本地插件更直接。这个习惯帮我把排查时间压缩了很多。

另外一个很重要的习惯是给文件命名。给团队或论文用的时候，我会把 Mermaid 代码单独放在docs/flow目录下，每个图一个.md文件，命名带上模块名和日期。这样做的好处是，以后流程变更时，能通过 Git 历史看到每一版改动，回滚也方便。如果只是临时画一个图给别人看，那直接在 Markdown 文档里写就好，不用单独拆分。我见过太多人在一个文档里堆了几十张 Mermaid 图，最后改图时连自己都找不到对应代码在哪一段，拆开管理会舒服很多。

6.2 最后分享一个提速小技巧

最后分享一个我每次教别人都会说的小技巧：不要一上来就背语法，你需要记住的就三样东西——方向、节点、连线。遇到拿不准的形状和样式，随时打开 Mermaid 官方文档或者 Mermaid Live Editor，现场验证。你可以把常用的模板存成一个代码片段，比如“开始-判断-结束”的基础框架，以后要画任何流程图，复制模板改文字就行，不用从零开始写。

比如我要画一个登录流程，脑子里只要想清楚：开始节点用一个圆角矩形，判断“是否已登录”用菱形，已登录和未登录各走一条线，最后进入对应页面或抛出错误。把这些关系用文本表达出来，Mermaid 自动排版，VSCode 实时预览。这个过程熟练之后，真的不需要五分钟就能完成。等你看懂了自己画出来的图，再回头看 Visio 里反复拖框拉线的日子，大概率会觉得以前的效率实在浪费了太多时间。