1. Typora画图这件事底层到底靠什么跑起来第一次见到有同事在 Typora 里敲几行像伪代码的东西一按回车就出来一张带箭头、带分支的流程图我当时的反应是这不科学。后来把它的渲染链路摸清楚才发现Typora 本身并不绘图它只是一个 Markdown 编辑器真正干活的是一套叫Mermaid的文本绘图引擎被内置进了编辑器的代码块渲染管线里。你写的是字符串它把你的字符串解析成图形描述语言再交给渲染层画出 SVG贴进编辑器里。流程图、时序图、顺序图、甘特图、类图、状态图、饼图全都是同一套引擎的不同语法分支。这套机制的价值在于图形和文档躺在同一个.md文件里纯文本、可 diff、可版本管理。别人改了你一个节点名字git 上一眼就能看出来改的是哪一行而不是像拖拽出来的二进制图形文件那样只能看到文件已变更四个字。做需求文档、毕业设计、系统设计说明的时候这一点非常要命。1.1 Mermaid引擎的渲染机制与开启方式Typora 内置 Mermaid 是默认开启的但版本差异会让渲染表现不同。你要做的第一步是确认开关打开偏好设置 → Markdown → 图表Diagrams确认勾选状态。有些老版本放在语法支持区域名字可能叫 Mermaid勾上就完事。关闭状态下你写的代码块只会显示成一堆带背景色的死文本很多人以为是语法写错了其实只是开关没开。开启之后输入三个反引号加语言标记mermaid按回车Typora 会自动补一段代码块骨架光标落在中间。你把图形描述写进去退出代码块光标移到块外的那一瞬间图形就渲染出来了。这个移出即渲染的行为值得记住新手经常在块里盯着源码纳闷为什么不显示图。编辑器左上角有个源码模式切换按钮切过去能看到原始字符切回来又是图。写复杂图的时候建议保持在源码模式里调渲染后再切回来验收否则每次都要点进块里改来回跳很累。另外要注意渲染出来的图是 SVG可以右键复制图片也可以整体导出。1.2 为什么我推荐用文本绘图而不是拖拽式工具拖拽式绘图工具上手确实快但用到中后期会撞墙。我踩过的坑集中在三处改一处要动全身。节点一多拖动一个框所有连线跟着乱跑对齐、避让、重排。改十次需求等于重画十次图。版本管理几乎失效。图形文件是压缩过的二进制diff 出来毫无意义多人协作只能靠谁最后保存谁说了算。风格不统一。三个人画出三种颜色三种圆角放进同一份文档里像拼贴画。文本绘图把这些问题一次性解决。样式统一靠classDef和主题配置改版靠改文字协作靠 git 合并。代价是你要花两三个小时记语法——而这正是这篇内容存在的理由。我更倾向于把 Mermaid 当成画图的快捷键而不是画图软件日常结构图、流程、排期、交互它能覆盖八成需求真要画复杂的架构大图、精细的电路时序再换专业工具补位。1.3 环境准备与授权问题的现实处理环境上没什么可折腾的官网下载安装包Windows 是 exemacOS 是 dmg装完直接能用。不建议去折腾来路不明的第三方打包版本我见过有人装到的版本被塞了额外的启动脚本编辑器还莫名其妙往外发请求写文档的工具反倒成了风险源。关于授权说句实在话Typora 的免费试用期过了之后启动时会弹出提醒窗口。这个弹窗是授权校验机制在起作用属于正常商业软件的提醒不是什么故障。正规做法是购买许可证学生身份通常可以申请教育优惠价格一个授权可以激活若干台自己的设备对个人用户来说成本并不高。至于网上流传的各种免费序列号激活工具一直弹窗怎么关的方案我不建议碰——轻则激活后反复弹窗、授权状态不稳定重则替换了程序核心文件后续升级直接报错甚至数据丢失。写作环境最重要的是稳定为了省一笔小钱把文档工具搞成半残状态不划算。装好之后建议顺手做两件事把默认主题换成自己喜欢的偏好设置 → 外观 → 打开主题文件夹再在图像设置里配置好图片保存路径把粘贴进来的图片自动复制到./assets之类的相对目录这样整个文档目录可以整体打包带走不会出现图挂了一堆红叉。2. 流程图从最简骨架到复杂分支的完整实操流程图是使用频率最高的一类。我见过它出现在需求评审、毕业设计、工艺说明、审批链路说明各种场合。它的语法结构其实只有三层声明方向、定义节点、连接节点。搞懂这三层剩下的都是形状和样式的排列组合。2.1 方向声明与节点定义的基本写法图的第一行决定整体布局方向写法是graph加上方向缩写或者用flowchart加上方向缩写两个关键字在大部分场景下可以互换但flowchart支持更完整的子图与样式能力新写的图我建议统一用flowchart少踩兼容性的坑。方向缩写一共五个TD或TB表示从上到下BT从下到上LR从左到右RL从右到左。业务流程图一般用TD因为它读起来像文档的自然顺序而输入→处理→输出这种横向链路用LR视觉上更紧凑。节点定义的最小形式是给一个标识符然后跟文案标识符是内部用的变量名文案是显示出来的中文或英文。标识符尽量用英文或拼音避免中文和空格这是我早期踩坑最多的地方一个中文标识符在复杂图里引发的解析报错能让你排查半小时。flowchart TD A[开始] -- B[读取输入] B -- C{校验通过?} C --|是| D[写入数据] C --|否| E[返回错误] D -- F[结束] E -- F这段不到十行就是一张完整的判断分支流程图。你需要理解的重点是节点第一次出现时定义形状之后再用只写标识符即可不需要重复写文案。如果重复写了不同文案后面的会覆盖前面的定义图形位置也会变这是很多人明明定义了两个节点却只显示一个的原因。2.2 流程图各种框的含义与形状对照形状不是随便选的它承载语义。工程文档里如果形状用错评审的时候会被直接挑出来。我把常用形状和它的标准含义整理成一张对照表写流程图前扫一眼就不会出错。语法写法形状名称标准语义A[文案]矩形处理步骤、普通操作A(文案)圆角矩形起止节点、状态入口A([文案])体育场形终止、结束点A[[文案]]子程序框调用子流程、函数A[(文案)]圆柱形数据库、数据存储A((文案))圆形连接点、聚合点A{文案}菱形条件判断、分支A{{文案}}六边形准备、初始化A[/文案/]平行四边形数据输入输出A[\文案\]反向平行四边形数据输入输出反向A文案]非对称形注释、标记我个人的经验是一张业务流程图里最多出现三到四种形状圆角矩形做起止、矩形做操作、菱形做判断、平行四边形做输入输出。形状过多会让图变成符号大杂烩阅读成本反而上升。只有涉及数据库交互时才加圆柱形涉及独立子流程时才加子程序框。毕业设计里的图书管理系统流程图用户管理模块流程图这类图基本可以套用同一个骨架登录校验 → 权限判断 → 主循环 → 增删改查分支 → 数据落库 → 退出。区别只在于分支数量。把形状用对评审老师那一关就稳了一半。2.3 连线类型、文字标注与样式美化连线是流程图的骨架。常用的就几种实线箭头--、无箭头实线---、虚线箭头-.-、粗线箭头。加上文字标注有两种写法一种是把文字塞在箭头中间--文字--另一种是用竖线包裹--|文字|。我习惯用竖线括号的写法因为箭头带文字的语法对中文支持偶尔抽风竖线写法更稳。双向关系用--圆形端点用o--o叉形端点用x--x。跨层级的长连线很容易把图搅乱这时候子图就派上用场了。subgraph可以把一组节点圈起来并加标题适合表达前端层服务层数据层这种分层结构也可以把图按模块拆开让主流程干净清爽。样式方面classDef定义样式类class把类挂到节点上linkStyle按连线序号改线的颜色和粗细。样式不要滥用我的原则是只给三类节点上色——成功路径、异常路径、外部系统。颜色超过三种图就开始显得业余。flowchart LR subgraph 前端 A([用户操作]) -- B[表单校验] end subgraph 服务端 B -- C{业务规则} C --|通过| D[(写入库表)] C --|拒绝| E[返回提示] end classDef ok fill:#d4edda,stroke:#28a745 classDef bad fill:#f8d7da,stroke:#dc3545 class D ok class E bad这段代码同时用到了子图、形状、分支文字和样式类是一个可以直接拿去改名的模板。把子图标题换成你自己的分层名把节点文案换掉就是一张能进正式文档的图。2.4 实战一张用户管理模块流程图的完整拆解拿一个真实场景走一遍。假设要画用户管理模块的操作流程需求是管理员登录后能查询、新增、修改、禁用用户所有写操作要记日志。第一步先想清楚主干。主干是登录 → 鉴权 → 进入管理页 → 选择操作这一步用TD方向就能表达。第二步想清楚分支查询是只读新增要校验手机号唯一修改要判断用户是否存在禁用要考虑是否最后一个管理员。第三步想清楚异常所有分支失败都汇入统一的错误处理节点。写完主干之后再补细节比一开始就堆节点效率高得多。新手最容易犯的错是把异常分支全画在主线上图会变得又宽又乱。正确做法是异常节点单独放在一侧用虚线连过去视觉上就能区分主流程和异常流。还要提一句流程图的方向微调。flowchart TD和flowchart LR有时候换一下图的宽高比会舒服很多。排版进 A4 页面的时候横向过宽的图在导出 PDF 时会被压缩得很小这时候把方向改成TD或拆成两张图阅读体验会明显改善。这个细节我在写需求文档时被排版问题折磨过好几次才总结出来。最后是节点文案的长度控制。一个节点里塞二十个字框会被撑得很长整体比例失调。我的处理办法是把长文案拆成动作 对象两段比如把校验用户提交的手机号是否已被占用改成校验手机号唯一性必要信息保留冗余修饰删掉。图是给人快速扫的不是给人逐字读的。3. 时序图把谁先调用谁这件事讲明白时序图和流程图解决的是两类完全不同的问题。流程图回答按什么顺序处理时序图回答哪个角色在哪一刻向谁发了什么消息等了多久返回了什么。接口联调、协议分析、框架调用链梳理时序图的表达效率是最高的。Typora 里同样用代码块渲染关键字是sequenceDiagram。3.1 参与者声明、消息类型与激活条图的第二行开始声明参与者。写法是participant 标识符 as 显示名也可以用actor代替participant画出来就是个小人图标适合表示真实用户。参与者的声明顺序决定它们在图上的左右排列顺序这一点要提前想好因为顺序错了消息线会交叉成一团麻。消息类型有五种常用写法-实线加实心箭头表示同步调用--虚线箭头表示返回-)表示异步消息箭头是开放的-只有线没有箭头表示不关心返回的单向消息-x表示消息丢失或异常中断。同步调用配虚线返回是最规范的写法看的人一眼就知道哪段是请求、哪段是响应。激活条用activate和deactivate成对出现表示某个参与者在这段时间内处于处理状态。它最大的作用是让读者一眼看出谁在忙。状态机、请求转发链这类图里激活条几乎是必加的没有激活条的时序图看起来会很平。序号可以用autonumber自动生成写在第一行声明之后。加了之后每条消息前面会带上递增数字评审的时候可以直接说第 5 步这里有问题沟通效率很高。3.2 循环、条件、并行与注释的使用场景时序图真正强大的地方在于它能把控制结构画进去。loop表示循环alt和else表示分支opt表示可选分支par和and表示并行critical表示关键区段break表示中断退出。我用得最多的是alt和loop。比如登录流程里密码错误和密码正确是典型的分支用alt包起来图标里会画出分割线重试逻辑用loop包起来会画成一个带标签的框。但要注意别把控制结构嵌太深三层嵌套的时序图基本没法读这时候应该拆成两张图主图只画成功路径异常路径单独出一张。注释用Note over、Note right of、Note left of。Note over A,B表示横跨两个参与者的注释用来解释一段交互的整体意图。我的习惯是在关键节点上挂注释说明这里为什么要加一次校验这个字段是做什么用的因为时序图本身只表达发生了什么不表达为什么。线的样式还可以进一步区分比如把跨系统的调用统一用虚线系统内部的调用用实线。这个约定在跨团队评审时特别有用一眼就能看出哪些是外部依赖、哪些是内部逻辑。3.3 实战一个请求链路的时序图写法拿最常见的登录链路举例。参与者有用户、前端页面、服务端接口、认证服务、数据库。顺序按调用先后排用户 → 前端 → 接口 → 认证 → 数据库。sequenceDiagram autonumber actor U as 用户 participant W as 前端页面 participant S as 服务端接口 participant A as 认证服务 participant D as 数据库 U-W: 输入账号密码并提交 W-S: POST 登录请求 activate S S-A: 校验凭据 activate A A-D: 查询账号记录 D--A: 返回账号与密码摘要 alt 凭据匹配 A--S: 校验通过并签发令牌 S--W: 返回登录成功 W--U: 跳转首页 else 凭据不匹配 A--S: 校验失败 S--W: 返回错误提示 W--U: 显示账号或密码错误 end deactivate A deactivate S这张图有几个值得说的处理一是激活条只加在服务端和认证服务上前端不加因为它们是被动响应加了反而让图变乱二是用alt把成功和失败两条路径并排画出来比两张图更省空间三是每条消息的文案都写成动作 数据读者能直接看出传了什么。写接口文档的时候我会在时序图下面紧跟着放接口字段表图和表互相印证。光有图没有字段说明对接方还是要来问你这一步补上沟通成本能省一大截。4. 甘特图项目排期可视化的低成本方案甘特图在 Typora 里的存在感比时序图低但实用性被严重低估。项目排期、学习计划、内容排产、装修进度都能用它表达。它的语法比前两种更接近表格式思维日期格式、标题、任务段落、任务条目。4.1 语法结构与任务状态的表达起始写法是gantt关键字然后依次声明title、dateFormat、axisFormat、excludes。dateFormat决定你后续写日期时用什么格式常用的是YYYY-MM-DDaxisFormat决定横轴显示成什么样比如%m-%d就只显示月和日excludes用来排除周末或指定日期写excludes weekends就能让排期跳过周六日。任务写在section里一个 section 就是一组。每个任务的基本格式是任务名 : 状态, 标识符, 开始日期, 持续时间。状态有四种写法不写表示待开始done表示已完成active表示进行中crit表示关键任务渲染成红色高亮milestone表示里程碑渲染成菱形。持续时间用30d、2w、1m这种单位d 是天w 是周m 是月。如果同时写了开始日期和持续时间引擎按这个算如果只写持续时间它会接在上一任务后面这个特性在快速排期时很好用但也很容易因为漏写日期导致整条排期错位我建议还是把日期写全。4.2 依赖关系、里程碑与分段任务依赖关系是甘特图的灵魂。写法是不写开始日期而是写after 任务标识符表示这个任务排在另一个任务结束之后。这里有个坑after后面必须跟标识符不是任务名。标识符是你在任务定义里起的那个短名字任务名是显示给人看的中文。新手经常把中文任务名写进after里然后发现图渲染不出来或者依赖没生效。里程碑用milestone标记画出来是一个菱形点适合标需求评审通过首次上线这种零时长的关键节点。它不占时间所以日期写哪一天就在哪一天。分段任务指的是把一个任务拆成若干段语法上写多个同名任务、多条日期或者直接用多个任务条目串起来。我在实际使用中不太用分段而是把大任务拆成几个子任务放进同一个 section这样每段可以独立标状态进度更新更直观。关键路径用crit标出来。项目的关键路径往往只有几条任务标红之后一眼就能看到哪几条拖了整个项目就拖了。这个功能在做项目汇报的时候非常讨巧。4.3 实战一个月迭代排期的排法假设一个为期四周的迭代从某月 1 日开始包含需求、设计、开发、测试、上线五个阶段中间有个里程碑。gantt title 单迭代排期 dateFormat YYYY-MM-DD axisFormat %m-%d excludes weekends section 前期 需求梳理 :done, req, 2024-03-01, 3d 方案设计 :active, dsg, after req, 4d section 开发 接口开发 :crit, dev1, after dsg, 6d 前端联调 : dev2, after dev1, 4d section 验收 测试回归 : tst, after dev2, 3d 灰度上线 :milestone, m1, after tst, 0d排期图的第一价值不是好看而是暴露冲突。我通常会把这张图和实际进度表对照着看哪个任务标了done但实际没完成说明进度同步出了问题哪条关键路径没有缓冲说明这个排期是乐观估计。图中用excludes weekends之后你会直观看到实际工作日和自然日的差距这对跨周排期很重要。另外提醒一点甘特图的日期粒度别太细。按小时排的甘特图在文本绘图里维护成本极高改一次要动十几个条目。排期粒度按天就够了真要细化到小时应该放到看板工具里。5. 顺带能画的其他图类图、状态图、饼图与硬件时序除了上面三类Mermaid 还支持一批高频图表。写系统设计文档的时候这些图能让你不用切换工具就把一份文档写完整。5.1 类图与关系型结构图类图用classDiagram声明。类定义写在花括号里字段和方法各占一行用-#表示公开、私有、受保护。关系符号有讲究|--是继承*--是组合o--是聚合--是关联..是依赖..|是接口实现。这些符号的方向不能写反空心三角永远指向父类实心菱形永远指向整体那一端。这套东西还有个变体叫实体关系图关键字是erDiagram专门画表和表之间的关系一对一和一对多都能标。做数据库设计说明的时候比手画连线图省事太多。5.2 状态图、饼图与用户旅程状态图用stateDiagram-v2起止状态写成[*]中间状态直接写名字转移写成A -- B: 触发条件。它特别适合描述订单状态、工单状态、审批状态这类有明确状态机的业务。复杂状态可以用state 名称 { ... }做嵌套用choice做条件分支用fork和join表示并行状态。饼图是 Mermaid 里最简单的pie加标题然后一行一个标签加冒号加数值引擎自动算百分比。用户旅程图用journey能按阶段画出体验评分做产品复盘时挺好用。5.3 硬件时序图必须换工具为什么 Mermaid 画不了这里必须说清楚一件事避免有人走弯路。网络上搜时钟时序图总线协议时序图这类关键词的人很多但要明确Mermaid 的时序图是消息交互时序不是电平波形时序。你想画时钟线的高低电平、数据线的建立保持时间、片选信号什么时候拉低Mermaid 做不到。这类真波形图有专门的工具比如基于 JSON 描述的波形绘制方案。它的基本思路是用一串字符表示信号的波形变化不同字符代表高电平、低电平、上升沿、下降沿、高阻态还可以在波形上叠标记和文字。写 I2C 的起始条件、SPI 的时钟极性相位、总线的握手时序都适合用它。语法上先定义时钟信号再定义数据信号然后加标注和注释文字。判断标准很简单如果图里要表达信号在第几个时钟周期变成高电平用波形工具如果要表达系统 A 在第几步调用了系统 B用 Mermaid 时序图。这两类图长得像但语义完全不同混用会闹笑话。6. 常见问题与排查技巧实录写得多了问题基本集中在固定的几类。我把它们整理成速查表再补充一些不太容易查到的经验。6.1 渲染失败与报错速查现象常见原因处理方式代码块显示为普通文本图表功能未开启或语言标记拼错检查偏好设置确认标记拼写图不渲染且无提示语法错误被静默吞掉切源码模式逐行排查先简化再恢复中文节点报解析错误节点文案含括号、逗号等符号给文案加英文双引号包裹子图报语法错误子图声明与节点定义顺序混乱先声明子图再在内部写节点连线文字不显示连字符与文字之间缺空格补齐空格或改用竖线包裹写法甘特图依赖不生效after后写了中文任务名改为引用任务标识符时序图顺序错乱参与者声明顺序与预期不符显式声明全部参与者并排序导出 PDF 图被截断图宽超出页面调整布局方向或拆图这张表里最容易被忽略的是中文特殊符号这一类。中文文案里带括号、冒号、逗号、斜杠的时候解析器可能会把它当成语法符号。统一给含特殊符号的文案加双引号能规避掉九成以上的解析异常。6.2 排版、居中与导出相关的问题关于居中这是被问得最多的一类。图片居中的处理方式是在图片外面套一层 HTML 容器给它设置文本居中样式文字居中同理用带样式的容器包住段落即可。需要注意的是这类 HTML 块在部分导出格式里可能失效导出前最好预览一遍。表格内容想上下居中可以给单元格加垂直对齐样式但在 Markdown 表格里生效情况取决于主题的 CSS。如果要严格控制排版建议在导出后用其他工具做最终微调别指望 Markdown 源文件能精确控制到像素级。导出方面Typora 支持导出 HTML、PDF、Word、EPUB 等格式。导出 PDF 前建议先切成阅读模式看一遍确认图表都渲染完成再导否则偶尔会导出成半成品。导出图片格式时注意分辨率默认设置下放大后可能发虚可以在导出选项里调高缩放倍数。主题定制是另一个进阶玩法。Mermaid 的配色可以通过主题 CSS 变量覆盖你在主题文件夹里改一次全文档所有图都跟着变比自己一个个写classDef高效得多。团队协作时把主题文件一起纳入版本管理大家的图就能保持同一套视觉规范。6.3 我踩过的坑与实操心得一条一条说都是实际用出来的经验。第一图不要画太大。我早期喜欢把整个系统的所有流程塞进一张图结果渲染出来密密麻麻导出 PDF 之后字小到看不清。后来改成每张图只讲一件事图的数量多了但每张都能读。判断标准是一张图打印出来一米外能看清主干。第二节点命名要统一。同一个概念在不同图里叫不同名字是文档维护的灾难。我现在会先写一份名词表所有图的节点文案都从表里取改的时候全局替换不会出现用户中心和用户模块两个名字指同一个东西的情况。第三先写文字大纲再画图。直接开画容易陷入细节。我现在的习惯是先用列表把流程写清楚确认逻辑没有遗漏再翻译成语法。翻译过程基本是机械劳动很快而且不会边画边改结构。第四把常用模板存成片段。登录流程、请求链路、迭代排期这几类图结构高度一致我存了几个模板文件新需求来了直接改文案。重复劳动能省则省把时间花在逻辑梳理上更值。第五渲染异常先做二分排查。图突然不显示了不要盯着整段代码看。把代码块砍掉一半看还渲不渲染能渲染说明问题在后半段不能渲染说明问题在前半段几轮下来很快定位。这比逐行读到眼花高效得多。第六注意编辑器的保存与同步。文档和图都在同一个文件里文件损坏意味着全丢。我吃过一次亏之后重要文档都放在版本库目录里编辑器自动保存加上定期提交心里踏实。第七版本升级后回看一遍旧图。渲染引擎升级偶尔会带来语法兼容变化老图可能突然报错或样式跑偏。升级完之后把常用文档翻一遍比在关键时刻掉链子强。最后再分享一个我常用的处理方式把图的源码块上面加一行说明文字写清楚这张图表达什么、更新于什么时间、对应哪个需求编号。图的受众不只是你自己过两个月回头看没有这行说明的图你也不知道当时想说什么。这个习惯看起来琐碎实际省下来的沟通时间相当可观。
Typora+Mermaid文本绘图：流程图、时序图、甘特图实战
1. Typora画图这件事底层到底靠什么跑起来第一次见到有同事在 Typora 里敲几行像伪代码的东西一按回车就出来一张带箭头、带分支的流程图我当时的反应是这不科学。后来把它的渲染链路摸清楚才发现Typora 本身并不绘图它只是一个 Markdown 编辑器真正干活的是一套叫Mermaid的文本绘图引擎被内置进了编辑器的代码块渲染管线里。你写的是字符串它把你的字符串解析成图形描述语言再交给渲染层画出 SVG贴进编辑器里。流程图、时序图、顺序图、甘特图、类图、状态图、饼图全都是同一套引擎的不同语法分支。这套机制的价值在于图形和文档躺在同一个.md文件里纯文本、可 diff、可版本管理。别人改了你一个节点名字git 上一眼就能看出来改的是哪一行而不是像拖拽出来的二进制图形文件那样只能看到文件已变更四个字。做需求文档、毕业设计、系统设计说明的时候这一点非常要命。1.1 Mermaid引擎的渲染机制与开启方式Typora 内置 Mermaid 是默认开启的但版本差异会让渲染表现不同。你要做的第一步是确认开关打开偏好设置 → Markdown → 图表Diagrams确认勾选状态。有些老版本放在语法支持区域名字可能叫 Mermaid勾上就完事。关闭状态下你写的代码块只会显示成一堆带背景色的死文本很多人以为是语法写错了其实只是开关没开。开启之后输入三个反引号加语言标记mermaid按回车Typora 会自动补一段代码块骨架光标落在中间。你把图形描述写进去退出代码块光标移到块外的那一瞬间图形就渲染出来了。这个移出即渲染的行为值得记住新手经常在块里盯着源码纳闷为什么不显示图。编辑器左上角有个源码模式切换按钮切过去能看到原始字符切回来又是图。写复杂图的时候建议保持在源码模式里调渲染后再切回来验收否则每次都要点进块里改来回跳很累。另外要注意渲染出来的图是 SVG可以右键复制图片也可以整体导出。1.2 为什么我推荐用文本绘图而不是拖拽式工具拖拽式绘图工具上手确实快但用到中后期会撞墙。我踩过的坑集中在三处改一处要动全身。节点一多拖动一个框所有连线跟着乱跑对齐、避让、重排。改十次需求等于重画十次图。版本管理几乎失效。图形文件是压缩过的二进制diff 出来毫无意义多人协作只能靠谁最后保存谁说了算。风格不统一。三个人画出三种颜色三种圆角放进同一份文档里像拼贴画。文本绘图把这些问题一次性解决。样式统一靠classDef和主题配置改版靠改文字协作靠 git 合并。代价是你要花两三个小时记语法——而这正是这篇内容存在的理由。我更倾向于把 Mermaid 当成画图的快捷键而不是画图软件日常结构图、流程、排期、交互它能覆盖八成需求真要画复杂的架构大图、精细的电路时序再换专业工具补位。1.3 环境准备与授权问题的现实处理环境上没什么可折腾的官网下载安装包Windows 是 exemacOS 是 dmg装完直接能用。不建议去折腾来路不明的第三方打包版本我见过有人装到的版本被塞了额外的启动脚本编辑器还莫名其妙往外发请求写文档的工具反倒成了风险源。关于授权说句实在话Typora 的免费试用期过了之后启动时会弹出提醒窗口。这个弹窗是授权校验机制在起作用属于正常商业软件的提醒不是什么故障。正规做法是购买许可证学生身份通常可以申请教育优惠价格一个授权可以激活若干台自己的设备对个人用户来说成本并不高。至于网上流传的各种免费序列号激活工具一直弹窗怎么关的方案我不建议碰——轻则激活后反复弹窗、授权状态不稳定重则替换了程序核心文件后续升级直接报错甚至数据丢失。写作环境最重要的是稳定为了省一笔小钱把文档工具搞成半残状态不划算。装好之后建议顺手做两件事把默认主题换成自己喜欢的偏好设置 → 外观 → 打开主题文件夹再在图像设置里配置好图片保存路径把粘贴进来的图片自动复制到./assets之类的相对目录这样整个文档目录可以整体打包带走不会出现图挂了一堆红叉。2. 流程图从最简骨架到复杂分支的完整实操流程图是使用频率最高的一类。我见过它出现在需求评审、毕业设计、工艺说明、审批链路说明各种场合。它的语法结构其实只有三层声明方向、定义节点、连接节点。搞懂这三层剩下的都是形状和样式的排列组合。2.1 方向声明与节点定义的基本写法图的第一行决定整体布局方向写法是graph加上方向缩写或者用flowchart加上方向缩写两个关键字在大部分场景下可以互换但flowchart支持更完整的子图与样式能力新写的图我建议统一用flowchart少踩兼容性的坑。方向缩写一共五个TD或TB表示从上到下BT从下到上LR从左到右RL从右到左。业务流程图一般用TD因为它读起来像文档的自然顺序而输入→处理→输出这种横向链路用LR视觉上更紧凑。节点定义的最小形式是给一个标识符然后跟文案标识符是内部用的变量名文案是显示出来的中文或英文。标识符尽量用英文或拼音避免中文和空格这是我早期踩坑最多的地方一个中文标识符在复杂图里引发的解析报错能让你排查半小时。flowchart TD A[开始] -- B[读取输入] B -- C{校验通过?} C --|是| D[写入数据] C --|否| E[返回错误] D -- F[结束] E -- F这段不到十行就是一张完整的判断分支流程图。你需要理解的重点是节点第一次出现时定义形状之后再用只写标识符即可不需要重复写文案。如果重复写了不同文案后面的会覆盖前面的定义图形位置也会变这是很多人明明定义了两个节点却只显示一个的原因。2.2 流程图各种框的含义与形状对照形状不是随便选的它承载语义。工程文档里如果形状用错评审的时候会被直接挑出来。我把常用形状和它的标准含义整理成一张对照表写流程图前扫一眼就不会出错。语法写法形状名称标准语义A[文案]矩形处理步骤、普通操作A(文案)圆角矩形起止节点、状态入口A([文案])体育场形终止、结束点A[[文案]]子程序框调用子流程、函数A[(文案)]圆柱形数据库、数据存储A((文案))圆形连接点、聚合点A{文案}菱形条件判断、分支A{{文案}}六边形准备、初始化A[/文案/]平行四边形数据输入输出A[\文案\]反向平行四边形数据输入输出反向A文案]非对称形注释、标记我个人的经验是一张业务流程图里最多出现三到四种形状圆角矩形做起止、矩形做操作、菱形做判断、平行四边形做输入输出。形状过多会让图变成符号大杂烩阅读成本反而上升。只有涉及数据库交互时才加圆柱形涉及独立子流程时才加子程序框。毕业设计里的图书管理系统流程图用户管理模块流程图这类图基本可以套用同一个骨架登录校验 → 权限判断 → 主循环 → 增删改查分支 → 数据落库 → 退出。区别只在于分支数量。把形状用对评审老师那一关就稳了一半。2.3 连线类型、文字标注与样式美化连线是流程图的骨架。常用的就几种实线箭头--、无箭头实线---、虚线箭头-.-、粗线箭头。加上文字标注有两种写法一种是把文字塞在箭头中间--文字--另一种是用竖线包裹--|文字|。我习惯用竖线括号的写法因为箭头带文字的语法对中文支持偶尔抽风竖线写法更稳。双向关系用--圆形端点用o--o叉形端点用x--x。跨层级的长连线很容易把图搅乱这时候子图就派上用场了。subgraph可以把一组节点圈起来并加标题适合表达前端层服务层数据层这种分层结构也可以把图按模块拆开让主流程干净清爽。样式方面classDef定义样式类class把类挂到节点上linkStyle按连线序号改线的颜色和粗细。样式不要滥用我的原则是只给三类节点上色——成功路径、异常路径、外部系统。颜色超过三种图就开始显得业余。flowchart LR subgraph 前端 A([用户操作]) -- B[表单校验] end subgraph 服务端 B -- C{业务规则} C --|通过| D[(写入库表)] C --|拒绝| E[返回提示] end classDef ok fill:#d4edda,stroke:#28a745 classDef bad fill:#f8d7da,stroke:#dc3545 class D ok class E bad这段代码同时用到了子图、形状、分支文字和样式类是一个可以直接拿去改名的模板。把子图标题换成你自己的分层名把节点文案换掉就是一张能进正式文档的图。2.4 实战一张用户管理模块流程图的完整拆解拿一个真实场景走一遍。假设要画用户管理模块的操作流程需求是管理员登录后能查询、新增、修改、禁用用户所有写操作要记日志。第一步先想清楚主干。主干是登录 → 鉴权 → 进入管理页 → 选择操作这一步用TD方向就能表达。第二步想清楚分支查询是只读新增要校验手机号唯一修改要判断用户是否存在禁用要考虑是否最后一个管理员。第三步想清楚异常所有分支失败都汇入统一的错误处理节点。写完主干之后再补细节比一开始就堆节点效率高得多。新手最容易犯的错是把异常分支全画在主线上图会变得又宽又乱。正确做法是异常节点单独放在一侧用虚线连过去视觉上就能区分主流程和异常流。还要提一句流程图的方向微调。flowchart TD和flowchart LR有时候换一下图的宽高比会舒服很多。排版进 A4 页面的时候横向过宽的图在导出 PDF 时会被压缩得很小这时候把方向改成TD或拆成两张图阅读体验会明显改善。这个细节我在写需求文档时被排版问题折磨过好几次才总结出来。最后是节点文案的长度控制。一个节点里塞二十个字框会被撑得很长整体比例失调。我的处理办法是把长文案拆成动作 对象两段比如把校验用户提交的手机号是否已被占用改成校验手机号唯一性必要信息保留冗余修饰删掉。图是给人快速扫的不是给人逐字读的。3. 时序图把谁先调用谁这件事讲明白时序图和流程图解决的是两类完全不同的问题。流程图回答按什么顺序处理时序图回答哪个角色在哪一刻向谁发了什么消息等了多久返回了什么。接口联调、协议分析、框架调用链梳理时序图的表达效率是最高的。Typora 里同样用代码块渲染关键字是sequenceDiagram。3.1 参与者声明、消息类型与激活条图的第二行开始声明参与者。写法是participant 标识符 as 显示名也可以用actor代替participant画出来就是个小人图标适合表示真实用户。参与者的声明顺序决定它们在图上的左右排列顺序这一点要提前想好因为顺序错了消息线会交叉成一团麻。消息类型有五种常用写法-实线加实心箭头表示同步调用--虚线箭头表示返回-)表示异步消息箭头是开放的-只有线没有箭头表示不关心返回的单向消息-x表示消息丢失或异常中断。同步调用配虚线返回是最规范的写法看的人一眼就知道哪段是请求、哪段是响应。激活条用activate和deactivate成对出现表示某个参与者在这段时间内处于处理状态。它最大的作用是让读者一眼看出谁在忙。状态机、请求转发链这类图里激活条几乎是必加的没有激活条的时序图看起来会很平。序号可以用autonumber自动生成写在第一行声明之后。加了之后每条消息前面会带上递增数字评审的时候可以直接说第 5 步这里有问题沟通效率很高。3.2 循环、条件、并行与注释的使用场景时序图真正强大的地方在于它能把控制结构画进去。loop表示循环alt和else表示分支opt表示可选分支par和and表示并行critical表示关键区段break表示中断退出。我用得最多的是alt和loop。比如登录流程里密码错误和密码正确是典型的分支用alt包起来图标里会画出分割线重试逻辑用loop包起来会画成一个带标签的框。但要注意别把控制结构嵌太深三层嵌套的时序图基本没法读这时候应该拆成两张图主图只画成功路径异常路径单独出一张。注释用Note over、Note right of、Note left of。Note over A,B表示横跨两个参与者的注释用来解释一段交互的整体意图。我的习惯是在关键节点上挂注释说明这里为什么要加一次校验这个字段是做什么用的因为时序图本身只表达发生了什么不表达为什么。线的样式还可以进一步区分比如把跨系统的调用统一用虚线系统内部的调用用实线。这个约定在跨团队评审时特别有用一眼就能看出哪些是外部依赖、哪些是内部逻辑。3.3 实战一个请求链路的时序图写法拿最常见的登录链路举例。参与者有用户、前端页面、服务端接口、认证服务、数据库。顺序按调用先后排用户 → 前端 → 接口 → 认证 → 数据库。sequenceDiagram autonumber actor U as 用户 participant W as 前端页面 participant S as 服务端接口 participant A as 认证服务 participant D as 数据库 U-W: 输入账号密码并提交 W-S: POST 登录请求 activate S S-A: 校验凭据 activate A A-D: 查询账号记录 D--A: 返回账号与密码摘要 alt 凭据匹配 A--S: 校验通过并签发令牌 S--W: 返回登录成功 W--U: 跳转首页 else 凭据不匹配 A--S: 校验失败 S--W: 返回错误提示 W--U: 显示账号或密码错误 end deactivate A deactivate S这张图有几个值得说的处理一是激活条只加在服务端和认证服务上前端不加因为它们是被动响应加了反而让图变乱二是用alt把成功和失败两条路径并排画出来比两张图更省空间三是每条消息的文案都写成动作 数据读者能直接看出传了什么。写接口文档的时候我会在时序图下面紧跟着放接口字段表图和表互相印证。光有图没有字段说明对接方还是要来问你这一步补上沟通成本能省一大截。4. 甘特图项目排期可视化的低成本方案甘特图在 Typora 里的存在感比时序图低但实用性被严重低估。项目排期、学习计划、内容排产、装修进度都能用它表达。它的语法比前两种更接近表格式思维日期格式、标题、任务段落、任务条目。4.1 语法结构与任务状态的表达起始写法是gantt关键字然后依次声明title、dateFormat、axisFormat、excludes。dateFormat决定你后续写日期时用什么格式常用的是YYYY-MM-DDaxisFormat决定横轴显示成什么样比如%m-%d就只显示月和日excludes用来排除周末或指定日期写excludes weekends就能让排期跳过周六日。任务写在section里一个 section 就是一组。每个任务的基本格式是任务名 : 状态, 标识符, 开始日期, 持续时间。状态有四种写法不写表示待开始done表示已完成active表示进行中crit表示关键任务渲染成红色高亮milestone表示里程碑渲染成菱形。持续时间用30d、2w、1m这种单位d 是天w 是周m 是月。如果同时写了开始日期和持续时间引擎按这个算如果只写持续时间它会接在上一任务后面这个特性在快速排期时很好用但也很容易因为漏写日期导致整条排期错位我建议还是把日期写全。4.2 依赖关系、里程碑与分段任务依赖关系是甘特图的灵魂。写法是不写开始日期而是写after 任务标识符表示这个任务排在另一个任务结束之后。这里有个坑after后面必须跟标识符不是任务名。标识符是你在任务定义里起的那个短名字任务名是显示给人看的中文。新手经常把中文任务名写进after里然后发现图渲染不出来或者依赖没生效。里程碑用milestone标记画出来是一个菱形点适合标需求评审通过首次上线这种零时长的关键节点。它不占时间所以日期写哪一天就在哪一天。分段任务指的是把一个任务拆成若干段语法上写多个同名任务、多条日期或者直接用多个任务条目串起来。我在实际使用中不太用分段而是把大任务拆成几个子任务放进同一个 section这样每段可以独立标状态进度更新更直观。关键路径用crit标出来。项目的关键路径往往只有几条任务标红之后一眼就能看到哪几条拖了整个项目就拖了。这个功能在做项目汇报的时候非常讨巧。4.3 实战一个月迭代排期的排法假设一个为期四周的迭代从某月 1 日开始包含需求、设计、开发、测试、上线五个阶段中间有个里程碑。gantt title 单迭代排期 dateFormat YYYY-MM-DD axisFormat %m-%d excludes weekends section 前期 需求梳理 :done, req, 2024-03-01, 3d 方案设计 :active, dsg, after req, 4d section 开发 接口开发 :crit, dev1, after dsg, 6d 前端联调 : dev2, after dev1, 4d section 验收 测试回归 : tst, after dev2, 3d 灰度上线 :milestone, m1, after tst, 0d排期图的第一价值不是好看而是暴露冲突。我通常会把这张图和实际进度表对照着看哪个任务标了done但实际没完成说明进度同步出了问题哪条关键路径没有缓冲说明这个排期是乐观估计。图中用excludes weekends之后你会直观看到实际工作日和自然日的差距这对跨周排期很重要。另外提醒一点甘特图的日期粒度别太细。按小时排的甘特图在文本绘图里维护成本极高改一次要动十几个条目。排期粒度按天就够了真要细化到小时应该放到看板工具里。5. 顺带能画的其他图类图、状态图、饼图与硬件时序除了上面三类Mermaid 还支持一批高频图表。写系统设计文档的时候这些图能让你不用切换工具就把一份文档写完整。5.1 类图与关系型结构图类图用classDiagram声明。类定义写在花括号里字段和方法各占一行用-#表示公开、私有、受保护。关系符号有讲究|--是继承*--是组合o--是聚合--是关联..是依赖..|是接口实现。这些符号的方向不能写反空心三角永远指向父类实心菱形永远指向整体那一端。这套东西还有个变体叫实体关系图关键字是erDiagram专门画表和表之间的关系一对一和一对多都能标。做数据库设计说明的时候比手画连线图省事太多。5.2 状态图、饼图与用户旅程状态图用stateDiagram-v2起止状态写成[*]中间状态直接写名字转移写成A -- B: 触发条件。它特别适合描述订单状态、工单状态、审批状态这类有明确状态机的业务。复杂状态可以用state 名称 { ... }做嵌套用choice做条件分支用fork和join表示并行状态。饼图是 Mermaid 里最简单的pie加标题然后一行一个标签加冒号加数值引擎自动算百分比。用户旅程图用journey能按阶段画出体验评分做产品复盘时挺好用。5.3 硬件时序图必须换工具为什么 Mermaid 画不了这里必须说清楚一件事避免有人走弯路。网络上搜时钟时序图总线协议时序图这类关键词的人很多但要明确Mermaid 的时序图是消息交互时序不是电平波形时序。你想画时钟线的高低电平、数据线的建立保持时间、片选信号什么时候拉低Mermaid 做不到。这类真波形图有专门的工具比如基于 JSON 描述的波形绘制方案。它的基本思路是用一串字符表示信号的波形变化不同字符代表高电平、低电平、上升沿、下降沿、高阻态还可以在波形上叠标记和文字。写 I2C 的起始条件、SPI 的时钟极性相位、总线的握手时序都适合用它。语法上先定义时钟信号再定义数据信号然后加标注和注释文字。判断标准很简单如果图里要表达信号在第几个时钟周期变成高电平用波形工具如果要表达系统 A 在第几步调用了系统 B用 Mermaid 时序图。这两类图长得像但语义完全不同混用会闹笑话。6. 常见问题与排查技巧实录写得多了问题基本集中在固定的几类。我把它们整理成速查表再补充一些不太容易查到的经验。6.1 渲染失败与报错速查现象常见原因处理方式代码块显示为普通文本图表功能未开启或语言标记拼错检查偏好设置确认标记拼写图不渲染且无提示语法错误被静默吞掉切源码模式逐行排查先简化再恢复中文节点报解析错误节点文案含括号、逗号等符号给文案加英文双引号包裹子图报语法错误子图声明与节点定义顺序混乱先声明子图再在内部写节点连线文字不显示连字符与文字之间缺空格补齐空格或改用竖线包裹写法甘特图依赖不生效after后写了中文任务名改为引用任务标识符时序图顺序错乱参与者声明顺序与预期不符显式声明全部参与者并排序导出 PDF 图被截断图宽超出页面调整布局方向或拆图这张表里最容易被忽略的是中文特殊符号这一类。中文文案里带括号、冒号、逗号、斜杠的时候解析器可能会把它当成语法符号。统一给含特殊符号的文案加双引号能规避掉九成以上的解析异常。6.2 排版、居中与导出相关的问题关于居中这是被问得最多的一类。图片居中的处理方式是在图片外面套一层 HTML 容器给它设置文本居中样式文字居中同理用带样式的容器包住段落即可。需要注意的是这类 HTML 块在部分导出格式里可能失效导出前最好预览一遍。表格内容想上下居中可以给单元格加垂直对齐样式但在 Markdown 表格里生效情况取决于主题的 CSS。如果要严格控制排版建议在导出后用其他工具做最终微调别指望 Markdown 源文件能精确控制到像素级。导出方面Typora 支持导出 HTML、PDF、Word、EPUB 等格式。导出 PDF 前建议先切成阅读模式看一遍确认图表都渲染完成再导否则偶尔会导出成半成品。导出图片格式时注意分辨率默认设置下放大后可能发虚可以在导出选项里调高缩放倍数。主题定制是另一个进阶玩法。Mermaid 的配色可以通过主题 CSS 变量覆盖你在主题文件夹里改一次全文档所有图都跟着变比自己一个个写classDef高效得多。团队协作时把主题文件一起纳入版本管理大家的图就能保持同一套视觉规范。6.3 我踩过的坑与实操心得一条一条说都是实际用出来的经验。第一图不要画太大。我早期喜欢把整个系统的所有流程塞进一张图结果渲染出来密密麻麻导出 PDF 之后字小到看不清。后来改成每张图只讲一件事图的数量多了但每张都能读。判断标准是一张图打印出来一米外能看清主干。第二节点命名要统一。同一个概念在不同图里叫不同名字是文档维护的灾难。我现在会先写一份名词表所有图的节点文案都从表里取改的时候全局替换不会出现用户中心和用户模块两个名字指同一个东西的情况。第三先写文字大纲再画图。直接开画容易陷入细节。我现在的习惯是先用列表把流程写清楚确认逻辑没有遗漏再翻译成语法。翻译过程基本是机械劳动很快而且不会边画边改结构。第四把常用模板存成片段。登录流程、请求链路、迭代排期这几类图结构高度一致我存了几个模板文件新需求来了直接改文案。重复劳动能省则省把时间花在逻辑梳理上更值。第五渲染异常先做二分排查。图突然不显示了不要盯着整段代码看。把代码块砍掉一半看还渲不渲染能渲染说明问题在后半段不能渲染说明问题在前半段几轮下来很快定位。这比逐行读到眼花高效得多。第六注意编辑器的保存与同步。文档和图都在同一个文件里文件损坏意味着全丢。我吃过一次亏之后重要文档都放在版本库目录里编辑器自动保存加上定期提交心里踏实。第七版本升级后回看一遍旧图。渲染引擎升级偶尔会带来语法兼容变化老图可能突然报错或样式跑偏。升级完之后把常用文档翻一遍比在关键时刻掉链子强。最后再分享一个我常用的处理方式把图的源码块上面加一行说明文字写清楚这张图表达什么、更新于什么时间、对应哪个需求编号。图的受众不只是你自己过两个月回头看没有这行说明的图你也不知道当时想说什么。这个习惯看起来琐碎实际省下来的沟通时间相当可观。
