在 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这是早期版本内置的流程图引擎语法长得像伪代码用ststart: 开始这种写法。它功能比 Mermaid 弱但语法更直观适合只画简单流程的人。代码块语言标识写flow。第三条是Sequencejs-sequence-diagrams专门画时序图的老引擎代码块标识也是sequence。现在基本被 Mermaid 的sequenceDiagram取代了知道有这回事就行。第四条是PlantUML 外挂通道它依赖本地 Java 运行环境和 PlantUML 的 jar 包配置好之后能画一些 Mermaid 画不了的东西比如组件图、部署图、活动图以及接近 BPMN 风格的业务流程图。提示这四条通道都要在 Typora 的偏好设置里手动开启。路径是文件 → 偏好设置 → Markdown → 图表勾选对应引擎后重启预览才生效。默认状态下有的引擎是关闭的这是新手最常见的代码写了没反应的原因。1.3 三条通道的能力对照与选择建议选哪条通道不用纠结看你要画什么图就行。下面这张表是我自己整理的选择清单遇到问题直接查图表类型推荐通道代码块标识复杂度上限典型场景流程图 / 系统流程图Mermaidmermaid高业务流转、算法逻辑、模块串联简单流程图Flowchart.jsflow低三五步的极简流程时序图 / 顺序图Mermaidmermaid高协议交互、接口调用链、信号时序甘特图Mermaidmermaid中项目排期、学习计划、迭代节奏类图 / 状态图 / ER 图Mermaidmermaid中架构设计、数据库建模饼图 / 象限图Mermaidmermaid低占比统计、优先级矩阵活动图 / 组件图PlantUMLplantuml高业务流程、系统部署结构数字波形图WaveDrom外挂需插件高I2C、SPI、PWM 等真实电平时序还有一点必须提前说清楚Typora 内置的 Mermaid 版本通常比官方最新版旧这意味着你在官网示例里看到的某些新语法在 Typora 里可能直接报错。最典型的是flowchart关键字、mindmap、timeline、quadrantChart这几类。稳妥做法是——流程图统一用graph开头别用flowchart兼容性差异很大。2. 流程图从节点形状到图书馆管理系统的整图落地2.1 节点形状与含义速查别再乱用框流程图里每个形状都是有语义的这不是美术装饰是工程约定。你写毕业设计文档的时候导师看一眼框的形状就知道你懂不懂规范。下面这张表是标准含义对照语法写法渲染形状标准含义使用场景A[文本]矩形处理 / 步骤普通操作节点A(文本)圆角矩形起止节点开始、结束A([文本])胶囊形起止体育场另一种起止写法A{文本}菱形判断 / 分支条件判断、循环条件A[(文本)]圆柱形数据存储数据库、文件A((文本))圆形连接点跨页跳转、汇合点A文本]非对称形输入输出数据输入、结果输出A[[文本]]双边框矩形子流程调用另一个流程A[/文本/]平行四边形数据输入输出读写数据记住一个原则判断一定要用菱形起止一定要用圆角或胶囊数据存储一定要用圆柱。我见过太多人把判断写成矩形导致整张图读起来毫无节奏感读者不知道哪里会分叉。2.2 连线、方向与子图的组织方式方向由开头那一行决定graph TD是从上到下Top-Downgraph 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 里基本没问题但有四类字符会坏事必须掌握转义方式问题字符现象解决写法圆括号()节点被截断或报错用双引号包住整个文本方括号[]解析层级错乱同上加双引号双引号语法提前结束用#quot;实体替换竖线 与连线标签语法冲突百分号%与注释语法冲突加引号或改用全角井号#被当成实体起始符用#35;实体替换另外强调一下注释写法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: 通信前提CPOL0, CPHA0 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 weekendsaxisFormat控制横轴日期的显示格式excludes weekends会自动跳过周末做真实排期的时候这个必须加否则工期会算多。任务定义是三段式用冒号分隔任务名 : 状态标记, 任务ID, 起始时间, 时长。四个字段里除了任务名其他都可以省但省多了容易乱建议至少写 ID 和时长。状态标记有四个关键词标记含义渲染效果done已完成灰色填充active进行中高亮填充crit关键路径红色边框milestone里程碑菱形标记起始时间可以写绝对日期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 也能做甘特图为什么要用这个我的答案是看场景。方案优势劣势适用场景Mermaid 甘特图纯文本、易版本管理、改一行就更新不支持资源分配、工作量只能估技术文档、个人计划、研发排期Excel 甘特图直观、能算工时、能联动其他表修改麻烦、复制容易错位、无法 diff给管理层汇报、需要精确工时统计专业项目管理工具资源平衡、依赖网络、进度追踪完整重、需要团队协同、脱离文档中大型项目、多人协作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~直接写ListPermission会被当成 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 与 BPMNTypora 画不了的部分怎么补有几个东西 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 是 exemacOS 是 dmgLinux 有 deb 和 AppImage。安装完第一次打开会提示选择授权方式请通过官方渠道获取授权个人长期使用建议购买正式许可这是最省心的路径能获得完整更新和技术支持。如果你预算有限或者只是临时用一下完全有合规的替代方案而且体验差距不大替代方案图表能力优点适用情况VS Code Markdown 预览插件支持 Mermaid 全语法免费、插件生态好、版本新已经在用 VS Code 的人各类开源 Markdown 编辑器多数内置 Mermaid免费、跨平台只想写笔记不想付费在线 Markdown 编辑器支持 Mermaid免安装临时查看渲染效果本地 Mermaid 命令行工具支持导出 SVG/PNG可进 CI 流程需要批量出图这里特别推荐一下 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 aligncenter img srcchart.png width60% / /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 代码写了但渲染不出来这是最高频的问题按下面顺序排查基本五分钟能定位语言标识写对了吗。Mermaid 是mermaidFlowchart.js 是flowPlantUML 是plantuml。写成md、text、markdown都不会渲染。引擎开启了没。偏好设置 → Markdown → 图表确认对应引擎的勾选框是选中的。默认可能只开了 Mermaid。代码块闭合了吗。三个反引号开头必须三个反引号结尾中间不能有独立的三个反引号。有没有语法错误。Mermaid 的容错性一般一个未转义的括号就能让整块渲染失败报错信息通常显示在代码块下方的小字里仔细看。版本支持吗。前面反复提到的flowchart、mindmap、quadrantChart在旧版本里就是不认换graph试试。7.2 语法报错与兼容性问题下面这张表是我踩过的坑汇总遇到报错先查这里报错现象根本原因解决方式图渲染成空白首行关键字拼错检查graph/sequenceDiagram/gantt拼写节点文字被截断文本含括号且未加引号用A[文本(含括号)]泛型显示成空尖括号被当 HTML 标签用~代替 时序图箭头报错箭头符号用成了非法组合只用-、--、-x、-)甘特图日期错乱dateFormat与书写格式不符两处格式必须完全一致甘特图工期偏短没排除周末加excludes weekends连线上%报错与注释语法冲突加引号或改全角状态图布局差用了stateDiagram而非v2改为stateDiagram-v2还有一条经验Mermaid 对中英文混排的宽度计算不太准节点文本如果又长又是中英混排有时候会挤在一起。解决办法是在文本里主动加br/控制折行位置别指望它自动排版。7.3 排版与导出问题速查问题现象处理方式图太长超出页面横向溢出需要滚动改用graph LR竖排或拆成两张图PDF 里图被切断分页位置尴尬加break-inside: avoid或调整前后空行导出图片模糊放大后锯齿明显改导出 SVG或用命令行工具高分辨率渲染中文显示成方框字体缺失主题 CSS 里指定中文字体栈表格内容顶对齐视觉不整齐加vertical-align: middle主题改完不生效仍显示旧样式重启应用或检查 CSS 文件名是否被识别8. 我个人踩过的几个坑说几个只有真用过才会遇到的细节。第一个坑把图的源文本和渲染结果搞混了。早期我会在导出 PDF 之后删掉 Mermaid 源码块只留图片觉得文档更干净。结果后来想改一处措辞发现改不了只能重画。现在的做法是源码块永远留在文档里需要给别人看的时候再单独导出一份只含图片的版本。源码是资产图片只是投影。第二个坑子图嵌套太深。我做过一张三层嵌套的流程图渲染出来节点挤成一坨连线交叉得像蛛网。Mermaid 的布局算法对深嵌套支持不好超过两层子图就开始难看了。后来的做法是拆图一张主流程讲整体几张细化的子流程分别画用文字说明它们的调用关系比硬塞进一张图清楚得多。第三个坑是甘特图的时间估算。我一开始按工作日排任务写10d结果渲染出来跨了两周多跟实际排期对不上。后来才明白10d就是十个自然日加excludes weekends只是在显示和计算上跳过周末。想让工期精确对应工作日得自己数好天数或者干脆按自然日排心里有数就行。第四个坑是导出时的字体。在 macOS 上排得漂漂亮亮的文档导出 PDF 到 Windows 打开中文字体全变了行高也乱。原因是导出 PDF 时字体是嵌入的但如果 CSS 里指定的字体在系统里找不到就会走 fallback。解决办法是在主题 CSS 里写完整的字体栈把不同平台的常见字体都列上形成一个降级链。最后一个建议别一上来就追求画得好看。Mermaid 的默认样式确实朴素但它的核心价值是表达清楚。先把逻辑画对节点命名统一分支穷举完整这些做到了图就已经及格。配色和圆角这些东西等文档结构稳定了再花时间调主题。我见过太多人卡在配色调了一下午结果流程逻辑还是错的。如果后面你想更进一步可以试试把 Mermaid 渲染接到自动化流程里——文档提交时自动渲染所有图表并检查语法这样团队里谁写错了语法提交阶段就能拦下来比事后人工检查省事得多。