diagram-design 这个名字，听起来像是一个普通的画图项目，但我在过去大半年里把它做成了一套完整的方法论加工具链。技术写作、方案汇报、系统设计，每个场景都逃不掉一个痛点：一张图能说清楚的事，用文字绕三圈别人还是听不懂；可真动手画图，又常常陷入“图画出来了，但丑到没人愿意细看”的窘境。diagram-design 就是冲着这个问题去的——它解决的问题不是“怎么把图画出来”，而是“怎么把图表设计得清晰、一致、可维护”，并且让整个过程可以交给代码和规范去约束，而不是全靠个人感觉。
这套东西适合谁？如果你需要频繁产出架构图、流程图、时序图，或者需要在团队文档里维护一批经常变动的图表，那它基本能直接改善你的日常。无论你是写文档的工程师、做方案的设计师，还是带项目需要画图讲清楚逻辑的人，下面这些思路和步骤都可以照着复现。我会把项目背后的设计思路、工具选型、实操流程、踩坑记录都摊开讲，尽量让你读完就能上手。
1. 项目定位与核心设计思路
1.1 为什么选择“代码驱动制图”这条路
diagram-design 的核心选择，是把图表用纯文本的方式去描述，再用工具渲染成最终图形。这是跟传统“所见即所得”绘图最大的分岔口。Visio、draw.io、Figma 这类工具并不是不好，它们胜在交互直观，拖拽一下就能出图。但它们的短板也很明显：图一旦多起来，版本管理基本靠“另存为新文件”；别人想改你的图，得先安装同一个软件，还得忍受图层被挪乱后的连锁反应。而代码驱动制图，天然解决了这几个问题。
我用一个类比来说明：所见即所得工具像是在白纸上直接画油画，落笔就定稿，修改成本很高；diagram-design 的做法则像用源代码写网页，页面上看到什么不重要，重要的是源码随时可以 diff、回滚、多人并行改，最后用统一的方式构建出成品。
这个选择并不是要否定 GUI 工具，而是要在“快捷”和“可维护”之间找平衡。diagram-design 的思路是：把图表的“内容结构”和“视觉样式”分开。内容结构用文本描述，这部分进 Git 做版本管理；视觉样式通过主题文件统一控制，换风格不用动内容。实际用下来，这套分离机制带来的收益远超预期，尤其在团队协作的场景里，几乎消灭了“那张最新版图在谁那里”这种问题。
1.2 视觉一致性的三个设计原则
很多图表丑，不是绘制者审美不行，而是没有一套可以重复执行的视觉规则。diagram-design 花了比较多精力在视觉一致性上，提炼出三条原则。
第一条是有限色板。一张图里颜色一旦超过五种，读者就会开始怀疑“这个颜色是不是有特殊含义”。所以我把颜色收敛到一套固定语义：核心组件用一种色、依赖的外部系统用一种色、数据流用一种色、告警或异常用一种色。每种颜色在主题文件里定义一次，全项目复用，谁画图都不许临时发明新色号。这样整套文档的图表放在一起看，就像出自同一个人之手。
第二条是统一的节点隐喻。节点用什么形状、圆角还是直角、边框虚实，都要跟它的“语义”绑定。比如：系统组件用圆角矩形，外部依赖用直角矩形，数据存储用圆柱，决策点用菱形。这个规范听起来细碎，但它是读者快速定位信息的抓手。人脑对形状的识别速度比对颜色更快，形状有规律，扫图的速度能快一大截。
第三条是留白与网格。图表的疏密程度直接影响理解成本。diagram-design 里强制规定节点间距、连线拐点、分组padding这些参数，对齐到统一的网格系统。这样做的好处是，图上的元素永远有呼吸空间，不会挤成一团。很多人画图觉得“信息太多放不下”，其实不是真的放不下，而是没有用网格去规划空间。网格不是限制，它反而是让复杂图保持可读性的底层保障。
2. 工具链选型与关键细节
2.1 主流工具对比：Mermaid、PlantUML、Graphviz、Excalidraw
diagram-design 在选工具的时候，我把市面上常见的几类方案摆在一起对比过。这里直接给出我的对比维度：语法表达能力、渲染效果、生态集成度、中文字体支持、版本管理友好度。
| 工具 | 语法表达能力 | 渲染质量 | 集成度 | 中文字体 | 适用范围 |
|---|---|---|---|---|---|
| Mermaid | 中上，流程图/时序图/状态图都能覆盖 | 现代简洁，默认主题可用 | 极好，Markdown生态随处可用 | 需要额外配置字体 | 文档内嵌图首选 |
| PlantUML | 强，时序图表达力突出 | 偏朴素，定制需要写样式 | 一般，插件支持为主 | 支持较好 | 偏 UML 的场景 |
| Graphviz | 极强，布局算法多 | 默认风格偏学术，需调样式 | 一般，命令行工具 | 依赖系统字体 | 复杂拓扑、架构图底层渲染 |
| Excalidraw | 不依赖语法，手绘风格 | 手绘感强，适合草图和头脑风暴 | 中等，提供文件格式 | 好 | 快速表达想法，不追求严格规范 |
Mermaid 是我最后的主选。它的语法简单到团队成员看十分钟就能上手，而且 GitHub、GitLab 这些代码托管平台原生支持渲染，文档里直接嵌代码块就能出图，省掉了“图挂了”的问题。Graphviz 没有完全弃用，遇到需要精确控制布局的复杂架构图，我会先用 Graphviz 出布局，再做后处理。PlantUML 只在画严格 UML 时序图时才会开，毕竟它的时序图语法确实能打。
需要提醒的是，工具选型不要只看网上评测，要看你的内容形态。如果你的图大量出现在 Markdown 文档里，那 Mermaid 这类支持嵌入 Markdown 的工具就是最优解；如果你主要画精美的对外汇报图，那应该考虑 SVG 编辑类工具。diagram-design 的结论是：默认 Mermaid，遇到特殊场景再切换，不追求一把锤子敲所有钉子。
2.2 主题定制与样式统一的关键参数
选好工具只是开始，真正决定图表质感的是主题定制。Mermaid 默认主题其实挺好看，但放到统一的文档体系里会显得跳。diagram-design 里做了一套团队主题，核心做法是覆盖 themeVariables。
以 Mermaid 为例，我常在配置里干这几件事：定义品牌主色作为 primaryColor，定义边框色和阴影色，调整字体为“等宽优先、中文回退”的字体栈，设置全局圆角大小。这套变量配置一次，整个项目的图都跟着走，比手工逐张去调颜色高效太多。Graphviz 那边同理，node 的 shape、style、fillcolor、fontname 全部写成默认属性，放在一个公共配置里。
主题统一的隐藏价值在后期维护时才会体现。项目跑了半年后，会积累几十张图。如果每张图都是各自临时定义的颜色，那改版的时候就是灾难。但因为有主题变量，全局换肤只是改一行配置的事。这个“变量化”的思路，其实是从前端开发里借鉴过来的，套在图表上同样适用——把会变的东西收敛到少数入口，剩下全是纯内容。
3. 实操过程与核心环节实现
3.1 搭建一个可复用的图表模板工程
diagram-design 的实际操作不是打开在线编辑器画图，而是先搭一个本地工程。这个工程里，每个图都是独立的文本文件，有统一的目录结构，有渲染脚本，有输出目录。这样整套体系是可复现的，换一台机器也能直接跑起来。
一个典型的目录结构是这样：
diagram-design/ ├── src/ │ ├── architecture/ │ │ └── system-overview.md │ ├── flow/ │ │ └── order-process.md │ └── sequence/ │ └── auth-sequence.md ├── theme/ │ └── default.json ├── scripts/ │ ├── render.sh │ └── check.sh └── dist/ ├── svg/ └── png/src 目录按图表的类型分子目录，每个 md 文件里可以放一张图的 Mermaid 源码和必要说明。theme 目录放主题配置，scripts 里放渲染和校验脚本，dist 是产物目录。
渲染脚本我用的是 Node 生态里的工具组合，核心逻辑是读取每个 md 文件里的代码块，调用 Mermaid 的 CLI 生成 SVG，再用工具把 SVG 转成 PNG。脚本本身不复杂，但它把“画图”这个动作变成了“编译”，每次改完内容跑一下命令就能更新所有产物。这个体验跟写代码很接近，也更容易被工程师接受。
3.2 设计一张架构图的完整步骤
拿画一张系统架构图举例，diagram-design 的流程分四步。
第一步是列组件清单。先把所有要出现的系统、模块、数据存储写出来，不急着画，连线的正确性永远优先于美观。第二步是定分组。架构图一般按层级或区域分组，比如“应用层”“服务层”“数据层”，Mermaid 里用 subgraph 来表达，这样读者第一眼就能抓住大结构。第三步是连线。连线只表达真正的依赖关系，宁可少画也不要画一堆“可能有关系”的虚线，图上的线越少，核心链路越突出。第四步才是调样式。用主题变量统一外观，检查有没有节点溢出、线穿节点的问题。
布局这块，Mermaid 默认的流向是上下（TB），但架构图很多时候用左右（LR）更合适。我一般根据目标载体决定流向：文档里嵌入式阅读的图用 TB 更自然，投屏汇报用的架构图用 LR 更能利用宽屏空间。这个决定要在画图前就做好，中途切换流向往往要调整整张图的逻辑顺序，成本很高。
3.3 在团队协作中落地
自己用一套方案不难，难的是让整个团队都按这个方案产出。diagram-design 在团队落地时，我做了三件事。
第一件事是沉淀一个“最小可用规范”文档，只规定必须遵守的内容：文件放哪里、命名格式是什么、颜色语义是什么、什么场景用流程图什么场景用时序图。规范不用长，两页以内，太多规则没人看约等于没有。第二件事是提供模板和示例，新人入队不需要从头理解规范，直接复制已有图的文件，改内容就行，比背规范快得多。第三件事是接入代码评审流程，图表文件也是代码，变更也走评审，评审里重点看语义有没有偏差，接缝处有没有断档，颜色形状是否符合规范。
这套机制跑起来之后，效果很明显：图表不再是一个人维护的稀缺资源，而是团队共享的“文档资产”。谁要改架构图，直接改对应文本文件，提交一次变更，全链路透明。曾经那种“图在某个同事的电脑里，他请假了就没人能动”的情况，彻底成为历史。
4. 常见问题与排查技巧实录
4.1 布局乱、节点重叠怎么办
用 Mermaid 画图时最容易遇到的是节点重叠和连线乱飞。我第一次画一张有二十多个节点、还有跨组连线的架构图时，渲染结果简直没法看，文本框叠在一起，线绕了大半个图。后来排查下来，问题大多出在子图使用不规范和节点顺序上。
一个很实用的排查套路是：先删掉所有 subgraph 看布局是否正常，再逐个加回分组，每次加一个就渲染一次，马上能定位是哪个分组引发的问题。另一个套路是利用不可见连线来辅助排序，Mermaid 的布局对节点声明顺序很敏感，把想放在同一水平线的节点按顺序声明，布局会稳定很多。还有一种情况是节点内容字数差异过大，标题长的节点会把整行撑得很宽，这种情况下可以给文字换行，让节点比例回到合理范围。
Graphviz 的布局问题不太一样，它提供了 rankdir、rank、constraint 这些精细控制手段。遇到自动布局不满意，又不确定怎么调的时候，我的经验是优先加 invisible edge 来微调节点相对位置，而不是去改全局算法参数。全局参数一改，往往是修好了这个图，弄坏了另一个。
4.2 中文字体与导出乱码的处理
中文用户的头号坑一定是字体问题。Mermaid 默认字体对中文不友好，导出的 SVG 在别人电脑上打开经常出现豆腐块或者缺字。这个问题我在项目初期就遇到了，当时生成的 PNG 图里，中文全部变成方框，排查了好久发现是渲染环境里没有中文字体。
解决分两步走。第一，在配置里显式声明字体栈，让 Mermaid 知道优先用系统的中文字体，比如 “PingFang SC”、“Microsoft YaHei”、“Noto Sans CJK SC” 这一组，英文和数字用等宽字体渲染。第二，确保渲染环境真的装了这些字体，尤其是使用 Docker 或者 CI 流水线时，镜像里多半没有中文字体，需要在构建阶段就安装好，否则配置写再多也没用。
还有一个小细节值得注意：导出的 SVG 里文字是矢量，渲染成 PNG 时如果字体缺失，不会报错，只会静默变成豆腐块。所以我在渲染脚本里加了一步自动检查，统计生成图片里是否有异常字形，提前发现这类问题，而不是等图片用到了文档里才被肉眼发现。
4.3 多人协作时的冲突处理
当图表文件进入 Git 之后，多分支并行开发很容易产生冲突。普通代码冲突大家都会处理，但 Mermaid 这种文本也会冲突，比如两个人在不同分支同时往一张架构图里加节点，合并不当会把整个语法搞坏。
我的处理习惯有三个。第一，让连接关系成为主要的冲突识别依据，合并时优先看连线是否指向已经删除的节点，这是大部分合并后报错的根源。第二，尽量细化拆分：一张图别画到无敌大，超过一定复杂度就拆成子图，不同子图放到不同文件，冲突概率能指数级下降。第三，在文件头部用注释块写上维护提示，比如“本图表由系统 A 团队维护，改动前先联系负责人”，这算是个软约束，但在团队里很管用，能减少大量无谓的竞争性修改。
4.4 常见问题速查表
我把平时在项目里被问得最多的问题整理成了一个速查表，方便直接对照处理。
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| 文字变成方框 | 渲染环境缺中文字体 | 安装字体并配置 fontFamily |
| 节点重叠严重 | 子图过多或声明顺序不合理 | 逐个加 subgraph 定位问题，调整节点顺序 |
| 连线穿节点 | 跨组连线过多 | 重构成多个子图并适当使用不可见连线 |
| 布局方向不对 | 未指定流向或容器宽度过窄 | 明确设置 TB/LR，调整图宽 |
| Git 合并冲突 | 多人修改同一文件 | 拆分文件，减少单图复杂度 |
| 导出的 PNG 模糊 | 放大倍数不够 | 用 SVG 作为源格式，按目标尺寸导出 |
| 运行时语法报错 | 特殊字符未转义 | 检查引号、括号，必要时用实体编码 |
5. 从“能画图”到“画好图”的进阶心得
5.1 图表的分层表达
diagram-design 走到后期，最关键的认知变化是：好的图表从来不是把所有信息塞进一张大图，而是把信息分层表达。一个复杂系统，从上到下可以分为全景图、子系统图、模块细节图三个层级。全景图给投资者或新同学看，只展示系统边界和核心链路；子系统图给相关研发看，展示模块之间的关系；模块细节图给具体开发者看，细化到类、接口、数据字段。
很多人画图喜欢“一张图概括一切”，最后的结果就是图里每个元素都很小，谁也看不清，谁也找不到自己关心的部分。我现在的习惯是，在一张新图动笔前先问一句：这张图的读者是谁，他们需要从这里获取什么行动信息。回答清楚这两个问题，图的内容裁剪就水到渠成了。分层的额外好处是，每张图的维护成本都低，改一个模块不用动全景图，不会出现“改一行牵一发动全身”的局面。
5.2 建立自己的素材库
画图画多了，会发现大量场景是重复的。比如各种系统架构图里都会出现网关、认证中心、消息队列、数据库这些组件，如果每次都从头画，效率低，而且很难保持风格统一。diagram-design 专门建了一个素材复用库，把这些高频组件和典型子结构的文字模板沉淀下来。
这个素材库不复杂，就是一组带参数的模板文件。画网关节点用哪种颜色和图标、画外部系统用什么边框，全部有现成模板可复制。素材库的价值在于：新图画起来快，而且天然与既有图风格统一。另一个好处是改模板就能全局更新，比如想把所有外部系统的边框改个颜色，只需要改模板，存量图里的样式甚至不用动，重新渲染一遍就生效了。
5.3 这套体系的后续扩展方向
diagram-design 当前的状态已经能支撑日常图表工作了，但我还有一些规划中的扩展方向。最优先的方向是接入实体关系和数据流校验，让图表不仅仅是一张好看的图，还能在渲染时自动检查出不一致的连线或空引用。另一个方向是沉淀一套针对不同场景的最佳实践示例集，让团队同学在接到画图任务时能直接找到参考案例，而不是每次都在讨论“这里的节点到底该用圆角还是直角”。
这些扩展不需要改变现有工具链，Vite 依赖、CI 脚本、文件组织都能平滑演进。diagram-design 对我来说最大的启示是：画图这件事，看起来是感性工作，但把它当作一份带规范的代码去工程化管理之后，效率和质量的提升是非常明显的。很多时候我们觉得某个工作做不好，不是能力问题，而是没找到合适的方法来约束它。
