企业官网建设流程全解析

在 Typora 里画流程图、时序图和甘特图，本质上不是"画"，而是"写"——你写一段纯文本，Typora 帮你渲染成图。我第一次接触这套玩法是在整理一份嵌入式通信协议笔记的时候，几十页的 I2C 时序、SPI 时序靠截图贴图，改一个字节就要重画一遍，后来换成文本驱动的方式，改一行字图就跟着变，从那之后就再也回不去了。这篇内容会把 Typora 里能画的所有图型一次讲透：流程图、时序图、顺序图、甘特图、类图、状态图、ER 图、饼图、思维导图，还会顺带说清楚 BPMN 流程图、WaveDrom 波形图这类"Typora 原生画不了"的东西该怎么补。不管你是写毕业设计文档、整理协议手册、做项目排期，还是单纯想把笔记可视化，这里面的语法和踩坑记录都能直接抄着用。

1. 先把画图这件事想明白：Typora 画图的底层逻辑与选型

1.1 为什么"文本画图"比拖拽画图更适合长期维护

拖拽式绘图工具（各种在线作图站、桌面绘图软件）上手快，但有个致命问题：图是二进制资产。你把它贴进文档里，三个月后想改一个判断分支，得打开原文件、找图层、对准箭头，改完重新导出再替换。而 Typora 这套方案里，图不是资产，是代码块，它和你的正文在同一个.md文件里，跟着 Git 一起走，改起来就是编辑几行文本。

这件事带来的连锁好处很实际。第一是可 diff：代码评审时你能看到"流程图里新增了一个校验节点"，而不是"某某图片被替换"。第二是可复用：一段sequenceDiagram骨架复制到新文档里，改改参与者和消息就成新图。第三是不怕丢：只要源文本在，图随时能重新渲染出来，不存在"原工程文件找不到了"的尴尬。第四是风格统一：所有图共享同一套渲染风格，不会出现这张图像素风、那张图扁平风的拼盘感。

代价也有，就是必须记语法。但常用的其实就十来条，一两个小时能上手，之后收益是长期的。我的判断标准很简单：图需要反复修改、需要进版本库、需要在多个文档间复用，就用文本画图；图是一次性的、对美术效果要求极高的，就去用专业绘图工具。

1.2 Typora 里其实有三条画图通道

很多人以为 Typora 只能画流程图，实际上它内置了三条独立的渲染通道，另外还预留了一条外挂通道，搞清楚这个分类能省掉大量"为什么我的代码不渲染"的困惑。

第一条是Mermaid，这是主力通道，覆盖面最广，流程图、时序图、甘特图、类图、状态图、ER 图、饼图都能画。代码块语言标识写mermaid。

第二条是Flowchart.js，这是早期版本内置的流程图引擎，语法长得像伪代码，用st=>start: 开始这种写法。它功能比 Mermaid 弱，但语法更直观，适合只画简单流程的人。代码块语言标识写flow。

第三条是Sequence（js-sequence-diagrams），专门画时序图的老引擎，代码块标识也是sequence。现在基本被 Mermaid 的sequenceDiagram取代了，知道有这回事就行。

第四条是PlantUML 外挂通道，它依赖本地 Java 运行环境和 PlantUML 的 jar 包，配置好之后能画一些 Mermaid 画不了的东西，比如组件图、部署图、活动图，以及接近 BPMN 风格的业务流程图。

提示：这四条通道都要在 Typora 的偏好设置里手动开启。路径是"文件 → 偏好设置 → Markdown → 图表"，勾选对应引擎后重启预览才生效。默认状态下有的引擎是关闭的，这是新手最常见的"代码写了没反应"的原因。

1.3 三条通道的能力对照与选择建议

选哪条通道不用纠结，看你要画什么图就行。下面这张表是我自己整理的选择清单，遇到问题直接查：

还有一点必须提前说清楚：Typora 内置的 Mermaid 版本通常比官方最新版旧，这意味着你在官网示例里看到的某些新语法，在 Typora 里可能直接报错。最典型的是flowchart关键字、mindmap、timeline、quadrantChart这几类。稳妥做法是——流程图统一用graph开头，别用flowchart，兼容性差异很大。

2. 流程图：从节点形状到图书馆管理系统的整图落地

2.1 节点形状与含义速查，别再乱用框

流程图里每个形状都是有语义的，这不是美术装饰，是工程约定。你写毕业设计文档的时候，导师看一眼框的形状就知道你懂不懂规范。下面这张表是标准含义对照：

记住一个原则：判断一定要用菱形，起止一定要用圆角或胶囊，数据存储一定要用圆柱。我见过太多人把判断写成矩形，导致整张图读起来毫无节奏感，读者不知道哪里会分叉。

2.2 连线、方向与子图的组织方式

方向由开头那一行决定，graph TD是从上到下（Top-Down），graph LR是从左到右（Left-Right），还有BT从下到上、RL从右到左。长流程建议用TD，横向链路建议用LR，因为屏幕是宽屏，横向展开能塞下更多节点。

连线有几种写法，功能差异很明显：

• A --> B实线箭头，表示正常流转。
• A --- B无箭头实线，表示关联关系。
• A -.-> B虚线箭头，表示异步或者可选路径。
• A ==> B粗线箭头，表示主路径或者重点强调。
• A -- 文本 --> B带标签的连线，把条件写在连线上。

带标签的连线还有个简写形式A -->|文本| B，效果一样，但在一些旧版本渲染器里兼容性更好，我个人更推荐用竖线这种写法。

子图用subgraph包起来，对做"系统模块划分"特别有用：

graph TD subgraph 前端层 A[用户界面] --> B[路由分发] end subgraph 服务层 C[业务逻辑] --> D[数据校验] end subgraph 存储层 E[(数据库)] end B --> C D --> E

子图还有个容易踩的坑：中文子图名如果包含空格或特殊符号，要加引号，写成subgraph "用户管理模块"。

2.3 实战：图书管理与用户管理模块流程图

先说个场景。做图书管理系统毕业设计的同学，最常卡在"流程图怎么画才能把借还书逻辑说清楚"。我用下面这张读者借书流程来演示，它同时用到了判断、子流程和数据存储：

graph TD Start([读者发起借书]) --> Check{是否已登录} Check -- 否 --> Login[跳转登录页] Login --> Check Check -- 是 --> Query[查询图书状态] Query --> Stock{库存是否可借} Stock -- 否 --> Wait[加入预约队列] Wait --> End([结束]) Stock -- 是 --> Credit{信用分是否达标} Credit -- 否 --> Reject[拒绝借出并提示] Reject --> End Credit -- 是 --> Create[生成借阅记录] Create --> DB[(写入借阅表)] DB --> Update[库存数量减一] Update --> Notice[推送归还日期提醒] Notice --> End

再看用户管理模块，这是几乎所有后台系统都有的东西，逻辑也更通用：

graph TD A[进入用户管理] --> B{当前角色} B -- 超级管理员 --> C[全部操作权限] B -- 普通管理员 --> D[仅查看与编辑] B -- 审计员 --> E[仅查看日志] C --> F[新增用户] C --> G[编辑用户] C --> H[禁用/启用用户] C --> I[重置密码] F --> J[(用户表)] G --> J H --> J I --> J J --> K[写入操作日志表] D --> G E --> K

这两张图的写法有个共同技巧：把权限判断、状态判断单独抽成菱形节点，不要塞进连线的文字里。很多人的图看起来乱，就是因为判断逻辑全写在箭头上了。

2.4 实战：算法流程图与单片机控制流程

算法类流程图和业务流程图有个区别——算法流程图更强调循环和变量赋值。拿"广告灯左移右移控制"这种单片机作业举例，它的核心是一个循环加一个方向标志位：

graph TD S([程序开始]) --> Init[初始化 IO 口<br/>方向标志 dir = 1] Init --> Loop{主循环} Loop --> ReadKey{是否按下换向键} ReadKey -- 是 --> Toggle[dir = dir × -1] Toggle --> Shift ReadKey -- 否 --> Shift[按 dir 方向移位输出] Shift --> Delay[延时 200ms] Delay --> Loop

这里有个实用细节：节点文本里可以用<br/>换行。写算法流程图时，一个节点里常要放两三行伪代码，用<br/>比拉长一行要好读得多。另外文本里的括号要小心，A[计算 f(x)]这种写法在部分版本里会因为方括号嵌套解析出错，改成A["计算 f(x)"]加引号就稳了。

心得：画算法流程图时，尽量让"判断"节点只有两条出边。三条以上出边的菱形会让读者迷路，正确做法是把多分支拆成连续的二元判断，或者在连线上标注取值范围。

2.5 中文排版、转义与避坑清单

中文在 Mermaid 里基本没问题，但有四类字符会坏事，必须掌握转义方式：

另外强调一下注释写法：Mermaid 里用%%开头的行是注释，不会渲染。这个很有用，写复杂图的时候把废弃的分支注释掉而不是删掉，改回来很快。

中文排版还有个观感问题：Mermaid 默认字体是英文字体优先，中文会走 fallback，有时候字重不一致。这个可以通过自定义主题 CSS 解决，后面第 6 章会讲。

3. 时序图：把 I2C、SPI、AXI 这类信号讲清楚

3.1 语法骨架：参与者、消息、激活条

时序图（顺序图）是这套体系里最有价值的一类图，因为它能表达时间维度上的先后顺序，这是流程图做不到的。骨架就四样东西：参与者声明、消息箭头、激活条、分组块。

参与者用participant声明，可以起别名避免中文太长：

sequenceDiagram participant A as 上位机 participant B as 下位机

消息箭头分五种，别搞混：

• ->无箭头实线，一般不用。
• ->>实线带实心箭头，表示同步请求。
• -->>虚线带箭头，表示返回值或响应。
• -x带叉的实线，表示消息丢失或中断。
• -)开放箭头，表示异步消息。

激活条用activate和deactivate成对出现，表示某个参与者在处理事务：

sequenceDiagram participant C as 客户端 participant S as 服务端 C->>S: 提交表单 activate S S-->>C: 返回处理中 S->>S: 异步落库 deactivate S

分组块是让图变专业的关键。alt/else/end表示条件分支，opt/end表示可选，loop/end表示循环，par/and/end表示并行，rect rgb(...)可以给一段区域上底色。做协议文档时，用alt把"正常响应"和"异常响应"分成两块，比文字描述清楚十倍。

3.2 实战：SPI 正常通信时序图

SPI 通信的本质是"主设备拉低片选，然后在时钟边沿上收发数据"。这个交互过程用时序图表达特别合适，因为它天然就是两条时间线的对话：

sequenceDiagram autonumber participant M as 主控 MCU participant F as SPI Flash Note over M,F: 通信前提：CPOL=0, CPHA=0 M->>F: CS_N 拉低（片选有效） M->>F: SCK 输出时钟（空闲低电平） M->>F: MOSI 发送命令 0x03（读数据） M->>F: MOSI 发送 24 位地址 loop 逐字节读取 M->>F: SCK 上升沿采样 F-->>M: MISO 输出数据位 end M->>F: CS_N 拉高（通信结束） Note over M,F: 一次完整读操作耗时约 40 个时钟周期

同样的思路可以套在 I2C 上。I2C 相比 SPI 多了起始条件、从机地址、应答位这几个关键节点，用时序图把"起始 → 地址 → ACK → 数据 → ACK → 停止"这条链路画出来，比看波形截图直观得多，也方便在文档里加注释。

3.3 实战：Spring Boot 请求链路时序图

后端同学画接口调用链的时候，时序图同样好用。下面是我给一个下单接口画的链路图，用了autonumber自动编号，评审的时候可以直接说"第 7 步有问题"：

sequenceDiagram autonumber participant C as 客户端 participant G as 网关 participant S as 订单服务 participant R as 缓存 participant D as 数据库 C->>G: POST /api/order activate G G->>G: 校验签名与限流 G->>S: 转发请求 deactivate G activate S S->>R: 查询库存缓存 alt 缓存命中 R-->>S: 返回库存值 else 缓存未命中 S->>D: SELECT stock FROM item D-->>S: 返回库存行 S->>R: 回写缓存（TTL 300s） end S->>D: 扣减库存并写入订单 D-->>S: 事务提交成功 S-->>C: 返回订单号 deactivate S

这张图的价值在于：它把"缓存命中"和"未命中"两条路径显式画出来了，新人接手时一眼就能看懂为什么有时响应快有时慢。

注意：时序图里的参与者顺序由第一次出现的顺序决定，如果想让某两个参与者挨在一起，就调整participant声明的先后。不要指望渲染器自动优化布局，它不会。

3.4 真波形怎么画：WaveDrom 的补位方案

时序图画的是"谁在什么时候给谁发了什么"，但它画不出真正的电平波形。做嵌入式的人看 I2C、SPI、AXI 时序，需要看到 SCK 的方波、MOSI 上的数据位、CS 的拉低拉高——这时候 Mermaid 就不够了，得换 WaveDrom。

WaveDrom 用的是 JSON 格式，通过一套字符编码描述波形。字符含义：p表示周期时钟，0表示低电平，1表示高电平，x表示不确定态，z表示高阻，.表示延续上一状态，数字或字母表示数据总线上的值。

{ "signal": [ { "name": "CS_N", "wave": "10......1" }, { "name": "SCK", "wave": "p........" }, { "name": "MOSI", "wave": "x.3.4.5.6", "data": ["D7", "D6", "D5", "D4"] }, { "name": "MISO", "wave": "z.7.8.9.a", "data": ["D7", "D6", "D5", "D4"] } ]}

关键点在于所有信号的wave字符串长度必须一致，否则波形会错位，这是 WaveDrom 最常见的报错来源。上面四条都是 9 个字符，所以对齐了。

Typora 原生不支持 WaveDrom，实际有两条路走：一是用独立的 WaveDrom 在线编辑器或 VS Code 的扩展渲染，导出 SVG 再贴进 Typora；二是自己写一段 HTML 引入 WaveDrom 脚本，但这在 Typora 的实时预览里不一定生效。我的建议是把它当成"配套工具"而不是"Typora 功能"，协议手册里 Mermaid 时序图负责讲交互流程，WaveDrom 波形图负责讲电平细节，两者配合正好。

3.5 顺序图、时序图、波形图的名词辨析

这三个词在国内文档里经常混用，但严格说不是一回事，写规范文档的时候最好区分开：

• **顺序图（Sequence Diagram）**是 UML 的正式术语，强调对象之间的消息传递顺序，重点在"交互"。
• 时序图在日常口语里既可以指顺序图，也可以指硬件领域的时间关系图。硬件圈说的"i2c 时序图"更多指波形。
• **波形图（Waveform）**专指电平随时间变化的曲线，坐标轴是时间和电压。

判断标准很简单：如果重点是"谁调用了谁"，就画顺序图；如果重点是"信号在第几个时钟边沿变化"，就画波形图。我在文档里通常会两个都放，先用顺序图建立整体认知，再用波形图抠细节。

顺带提一句电力电子领域，像"两电平逆变器与三电平逆变器的区别"这种内容，其实也可以用时序图辅助说明——把上下桥臂的驱动信号序列画出来，配合Note标注死区时间，比纯文字好懂得多。虽然这不完全是"通信时序"，但表达方式是一样的。

4. 甘特图：排期、里程碑和进度可视化

4.1 语法拆解：dateFormat 与任务三元组

甘特图的语法结构和其他图差别挺大，它由三个部分构成：全局配置、区段划分、任务定义。

全局配置至少要有dateFormat，告诉解析器你的日期长什么样：

gantt title 项目排期示例 dateFormat YYYY-MM-DD axisFormat %m-%d excludes weekends

axisFormat控制横轴日期的显示格式，excludes weekends会自动跳过周末，做真实排期的时候这个必须加，否则工期会算多。

任务定义是三段式，用冒号分隔：任务名 : 状态标记, 任务ID, 起始时间, 时长。四个字段里除了任务名，其他都可以省，但省多了容易乱，建议至少写 ID 和时长。

状态标记有四个关键词：

起始时间可以写绝对日期2024-03-01，也可以写after 任务ID，后者表示"依赖某任务完成后开始"，这是排期最有用的写法，因为调整前置任务时长后，后续任务会自动顺延。

4.2 实战：一个三阶段的系统开发排期

下面这张图是我给一个中小型系统项目画的实际排期，覆盖需求、开发、测试三个阶段：

gantt title 系统开发排期（含里程碑） dateFormat YYYY-MM-DD axisFormat %m-%d excludes weekends section 需求与设计 需求调研 :done, a1, 2024-03-01, 5d 原型设计与评审 :done, a2, after a1, 4d 数据库设计 :done, a3, after a1, 3d section 编码实现 后端接口开发 :active, b1, after a2, 12d 前端页面开发 :active, b2, after a2, 10d 前后端联调 :b3, after b1, 5d section 测试与上线 集成测试 :crit, c1, after b3, 6d 性能压测 :crit, c2, after b3, 3d 缺陷修复 :c3, after c1, 4d 灰度发布 :milestone, m1, after c3, 0d

这张图里有三个细节值得说。第一，并行的任务不用特殊语法，只要起始时间相同，渲染时就会自动并行排列，比如后端接口开发和前端页面开发。第二，里程碑的时长为 0，写0d或者0都可以，它只是打一个点。第三，关键路径任务加crit，渲染成红色边框，评审时一眼能看到风险点在哪里。

4.3 和 Excel 甘特图、专业控件的取舍

很多人问：Excel 也能做甘特图，为什么要用这个？我的答案是看场景。

Excel 做甘特图的常规套路是用堆积条形图加条件格式：A 列写任务名，B 列写开始日期，C 列写持续天数，D 列写一个公式算偏移量，然后用堆积条形图把"偏移量"设为透明色、"持续天数"设为实体色。这套做法能做，但每次调整任务都要改一堆公式，而且没法进 Git。

我的实际做法是分工：技术方案文档里的排期用 Mermaid 画，因为它跟文档在一起，改需求时顺手就改了；需要给非技术同事看的排期表，导出成 Excel 或者截图给对方。两边不冲突。

心得：Mermaid 甘特图的excludes weekends只影响工期计算和网格显示，不会自动把任务切碎。如果你排的任务跨了三周，它会画成连续一条，而不是分成三小条。想看到"按周切开"的效果，得自己拆任务。

5. 其它常用图：类图、状态图、ER 图、饼图与思维导图

5.1 类图与状态图

类图在做架构设计文档时很有用。语法上，一个类用class 类名 { }包起来，成员用+表示公开、-表示私有、#表示受保护，方法后面加括号：

classDiagram class User { +Long id +String username -String passwordHash +login(pwd) Boolean +changePassword(old, new) Boolean } class Role { +Long id +String name +List~Permission~ permissions } class Permission { +Long id +String code } User "1" --> "n" Role : 拥有 Role "n" --> "n" Permission : 包含

注意泛型里的尖括号要用~包裹，写成List~Permission~，直接写List<Permission>会被当成 HTML 标签吞掉，这是个很隐蔽的坑。

状态图描述的是对象状态之间的迁移，用stateDiagram-v2开头（v2不能省，省了渲染器会走老版本逻辑，效果差很多）：

stateDiagram-v2 [*] --> 待支付 待支付 --> 已支付 : 用户付款成功 待支付 --> 已取消 : 超时未支付 已支付 --> 已发货 : 仓库出库 已发货 --> 已完成 : 用户确认收货 已支付 --> 退款中 : 用户申请退款 退款中 --> 已退款 : 审核通过 已退款 --> [*] 已取消 --> [*]

[*]表示起点或终点。状态图的实用价值在于穷举所有可能的状态和迁移条件，写的时候你会被迫想清楚"这种情况下应该去哪"，我靠这个发现过好几次业务逻辑漏洞。

5.2 ER 图：数据库设计直接出图

ER 图的语法和类图不一样，它描述的是实体、属性和关系。关系类型靠符号区分：||--||一对一，||--o{一对多，}o--o{多对多。

erDiagram READER ||--o{ BORROW : 发起 BOOK ||--o{ BORROW : 被借 CATEGORY ||--o{ BOOK : 归类 READER { bigint id PK varchar name varchar card_no UK datetime created_at } BOOK { bigint id PK varchar isbn UK varchar title bigint category_id FK } BORROW { bigint id PK bigint reader_id FK bigint book_id FK datetime borrow_at datetime due_at datetime return_at }

PK是主键，FK是外键，UK是唯一键，这些标注会直接渲染到字段后面。做数据库设计的同学，把 ER 图直接放进设计文档，比贴一张截图强太多，因为改字段时改一行文本就行。

5.3 饼图、思维导图与象限图

饼图最简单，就两行结构：

pie title 缺陷类型分布 "逻辑错误" : 42 "空指针" : 28 "边界条件" : 19 "并发问题" : 11

思维导图用的关键字是mindmap，缩进表示层级，不需要连线。但这个语法在新版 Mermaid 才支持，Typora 内置版本可能渲染不出来，用之前先测试一下，不行的话就用缩进列表加粗体代替，效果也不差。

象限图quadrantChart用来排优先级特别好用，横轴纵轴各代表一个维度，比如"重要性"和"紧急度"，把待办事项扔进去，四象限一眼分明。同样要注意版本兼容问题。

5.4 PlantUML 与 BPMN：Typora 画不了的部分怎么补

有几个东西 Mermaid 确实做不了，必须换工具。

标准的 BPMN 流程图，Mermaid 的graph只是形似，没有 BPMN 规范里的那些专用图元定义——比如排他网关、并行网关、事件网关，它们在外观和语义上都不一样，BPMN 规范要求排他网关用带 X 的菱形、并行网关用带加号的菱形。想要严格合规，用专门的 BPMN 建模工具（比如各类开源建模器）更靠谱。不过在技术文档里做示意，用 Mermaid 的菱形加文字标注完全够用，只是别声称"这是标准 BPMN"。

PlantUML 能补的部分主要是活动图、组件图、部署图和时序图的高阶写法。配置方式是在 Typora 偏好设置的图表里勾选 PlantUML，然后指定plantuml.jar的本地路径，前提是机器上装了 Java 运行环境。配置成功后就能写：

@startuml start :接收请求; if (参数合法?) then (是) :查询数据库; :组装响应; else (否) :返回参数错误; endif stop @enduml

活动图的好处是语法天然贴近业务语言的描述顺序，写起来像写作文，适合表达复杂的分支合并。

超详细波形用 WaveDrom，前面第 3 章讲过了。复杂拓扑的部署图其实用专业绘图工具更省事，因为服务器、负载均衡、容器这些东西的图标是刚需，Mermaid 画出来只有方框，表达力有限。

提示：判断要不要上 PlantUML 的标准是——如果 Mermaid 能画到八成效果，就别折腾环境配置。PlantUML 需要 JDK，启动有延迟，首次渲染几秒钟是常态，写小文档完全不划算。

6. 环境、主题、导出与协作的工程化细节

6.1 安装、授权与免费替代方案

Typora 的安装没什么门槛，官方站点下载对应平台的安装包，Windows 是 exe，macOS 是 dmg，Linux 有 deb 和 AppImage。安装完第一次打开会提示选择授权方式，请通过官方渠道获取授权，个人长期使用建议购买正式许可，这是最省心的路径，能获得完整更新和技术支持。

如果你预算有限，或者只是临时用一下，完全有合规的替代方案，而且体验差距不大：

这里特别推荐一下 VS Code 那条路：它的 Mermaid 插件版本通常比 Typora 内置的新，前面提到的mindmap、quadrantChart、timeline这些新语法都能渲染，而且可以配合 Git 做版本管理，工程化程度更高。我的实际组合就是——写文档用 Typora（编辑体验好），验证新语法用 VS Code（版本新），两边源文件是同一个。

如果遇到软件提示授权状态异常、反复弹提示这类情况，正确处理方式是检查账号登录状态、确认网络正常，然后联系官方支持渠道解决，不要去找来路不明的工具，那类东西风险很高。

6.2 主题、字体与内容居中

Typora 的主题是 CSS 文件，放在主题文件夹里。打开方式：偏好设置 → 外观 → 打开主题文件夹。你自己新建一个.css文件丢进去，重启就能在主题菜单里看到。

最常改的是三处：正文字体、代码块字体、图表区域样式。中文文档建议指定一套中文字体，避免 fallback 导致的字重不一致：

/* 自定义主题片段 */ :root { --bg-color: #fdfdfd; --text-color: #2b2b2b; } #write { font-family: "思源宋体", "Source Han Serif SC", serif; font-size: 16px; line-height: 1.85; max-width: 860px; } .md-fences { font-family: "JetBrains Mono", "Consolas", monospace; font-size: 14px; }

关于"如何上下居中"这个问题，要分两种情况。图片或段落整体居中，可以用 HTML 包裹：

<div align="center"> <img src="chart.png" width="60%" /> </div>

表格单元格垂直居中，靠自定义 CSS 的vertical-align：

#write table td, #write table th { vertical-align: middle; text-align: center; }

Typora 表格默认是顶对齐，加了这段之后就上下居中了，做参数对照表的时候视觉效果好很多。至于图表区域居中，Mermaid 渲染出来的 SVG 默认居中，不需要额外设置。

6.3 导出、图片清晰度与版本管理

导出走"文件 → 导出"，可以出 PDF、HTML，装了 Pandoc 之后还能出 Word 和图片。这里有几个实际经验：

PDF 导出的分页控制。长流程图经常被硬生生从中间切断，解决办法是在代码块前后留空行，或者在自定义 CSS 里给.md-fences加break-inside: avoid和page-break-inside: avoid，让整个代码块尽量落在同一页。

图片导出的清晰度。导出 PNG 时如果分辨率低，多半是因为缩放比例问题。可以先把窗口放大再导出，或者在 CSS 里提高图表区域的宽度上限。真正的解法是用命令行工具直接把 Mermaid 源码渲染成高分辨率 SVG，矢量图放多大都清晰，适合放进需要打印的文档。

版本管理。这是文本画图最大的优势所在。把.md文件放进 Git 仓库，每次改图都是一次可追溯的提交。我有个习惯：每张复杂图的上方加一行注释说明改动原因，用 HTML 注释写法，不会渲染出来但会在 diff 里显示：

<!-- 2024-03-15: 新增风控校验分支，原因是线上出现过重复下单 --> ```mermaid graph TD A[接收请求] --> B{风控校验} B -- 通过 --> C[创建订单] B -- 拒绝 --> D[返回拦截提示]

时间长了回头看，能知道每个节点为什么存在。这个习惯帮我避免了好几次"这个判断条件到底还要不要"的纠结。

7. 常见问题与排查技巧速查

7.1 代码写了但渲染不出来

这是最高频的问题，按下面顺序排查，基本五分钟能定位：

1. 语言标识写对了吗。Mermaid 是mermaid，Flowchart.js 是flow，PlantUML 是plantuml。写成md、text、markdown都不会渲染。
2. 引擎开启了没。偏好设置 → Markdown → 图表，确认对应引擎的勾选框是选中的。默认可能只开了 Mermaid。
3. 代码块闭合了吗。三个反引号开头，必须三个反引号结尾，中间不能有独立的三个反引号。
4. 有没有语法错误。Mermaid 的容错性一般，一个未转义的括号就能让整块渲染失败，报错信息通常显示在代码块下方的小字里，仔细看。
5. 版本支持吗。前面反复提到的flowchart、mindmap、quadrantChart，在旧版本里就是不认，换graph试试。

7.2 语法报错与兼容性问题

下面这张表是我踩过的坑汇总，遇到报错先查这里：

还有一条经验：Mermaid 对中英文混排的宽度计算不太准，节点文本如果又长又是中英混排，有时候会挤在一起。解决办法是在文本里主动加<br/>控制折行位置，别指望它自动排版。

7.3 排版与导出问题速查

8. 我个人踩过的几个坑

说几个只有真用过才会遇到的细节。

第一个坑：把图的源文本和渲染结果搞混了。早期我会在导出 PDF 之后删掉 Mermaid 源码块，只留图片，觉得文档更干净。结果后来想改一处措辞，发现改不了，只能重画。现在的做法是源码块永远留在文档里，需要给别人看的时候再单独导出一份只含图片的版本。源码是资产，图片只是投影。

第二个坑：子图嵌套太深。我做过一张三层嵌套的流程图，渲染出来节点挤成一坨，连线交叉得像蛛网。Mermaid 的布局算法对深嵌套支持不好，超过两层子图就开始难看了。后来的做法是拆图：一张主流程讲整体，几张细化的子流程分别画，用文字说明它们的调用关系，比硬塞进一张图清楚得多。

第三个坑是甘特图的时间估算。我一开始按"工作日"排任务，写10d，结果渲染出来跨了两周多，跟实际排期对不上。后来才明白，10d就是十个自然日，加excludes weekends只是在显示和计算上跳过周末。想让工期精确对应工作日，得自己数好天数，或者干脆按自然日排，心里有数就行。

第四个坑是导出时的字体。在 macOS 上排得漂漂亮亮的文档，导出 PDF 到 Windows 打开，中文字体全变了，行高也乱。原因是导出 PDF 时字体是嵌入的，但如果 CSS 里指定的字体在系统里找不到，就会走 fallback。解决办法是在主题 CSS 里写完整的字体栈，把不同平台的常见字体都列上，形成一个降级链。

最后一个建议：别一上来就追求画得好看。Mermaid 的默认样式确实朴素，但它的核心价值是"表达清楚"。先把逻辑画对，节点命名统一，分支穷举完整，这些做到了图就已经及格。配色和圆角这些东西，等文档结构稳定了再花时间调主题。我见过太多人卡在配色调了一下午，结果流程逻辑还是错的。

如果后面你想更进一步，可以试试把 Mermaid 渲染接到自动化流程里——文档提交时自动渲染所有图表并检查语法，这样团队里谁写错了语法，提交阶段就能拦下来，比事后人工检查省事得多。