图即代码：diagram-design 让架构图告别手工维护

1. 从“画图”到“写图”：diagram-design 的核心思路

老实说，diagram-design 这个项目最初不是什么宏大的平台规划，就是我被架构文档里的图反复折腾到崩溃之后，决定把“画图”这件事彻底改成“写代码”。

当时我正在维护一个模拟项目的技术方案文档，架构图、调用链路图、部署拓扑图加起来十几张。每次评审会上产品逻辑一变，图就要跟着动：改个箭头方向、挪个模块位置、加一层节点，看起来都是小事，但用图形化工具改动起来非常痛苦。图层错乱、对齐线失效、导出的 PNG 版本混淆，更别说多人协作时，根本说不清这一版图和上一版图到底差在哪。

diagram-design 的思路很简单：把图当作源码来管理。你不直接拖拽方块和连线，而是用一段结构化的文本描述节点、连线、分组和样式，再交给一个渲染器生成图片。源文件进入版本库，图片只是构建产物。这样图的变化可以被 diff、可以被审查、可以被自动化流程校验，就像代码一样。

这个项目适合谁？我总结下来是三类人：写技术文档写到怀疑人生的开发者和架构师；需要在代码评审、方案评审里频繁更新图表的项目成员；以及只要一碰到“这些图谁来维护”就头大的文档团队。它对新手也很友好，因为文本描述的图表语法比图形化操作更直观，改一行就能看到变化，不需要在工具里翻菜单找按钮。

diagram-design 能解决的核心问题，我认为不是“把图画得更好看”，而是“让图变得可维护”。它把图片从静态资产变成了活代码，这是它最有价值的地方。

1.1 传统画图的痛，几乎都集中在“改动”这两个字上

回想一下你用图形工具画图的流程：先新建画布，拖几个矩形进来，填上文字，然后连线、调样式、对齐、调整间距。第一版图一般一个小时能搞定，好看、清楚、自己也满意。

但图的生命周期从来不在“画完”那一刻，而在之后的每一次修改里。架构调整要换节点，流量路径变化要改箭头，新增模块要重新布局。最麻烦的是，图形文件的格式对 diff 完全不友好。你打开一个图片文件，看到的是一堆二进制数据，根本没法像读代码 diff 一样看明白“谁被删了”“谁被改了”“谁新增了”。

有一次我为了核对两张几乎一样的拓扑图，只能把两张图并排摆在屏幕上，肉眼逐块对比。那感觉就像在没有版本控制的情况下改代码一样折磨。更常见的场景是：团队里某个人改了一版图，导出 PNG 发到群里，群消息一刷过去，后面的人拿到旧图改了另一个版本，最后文档里出现三个不同版本的结构图，谁也不知道哪个才是真的。

所以传统画图工具真正的问题不是“画起来难”，而是“改起来没法追踪”。一旦图需要持续演进，日常协作就会变得异常低效。diagram-design 针对的就是这个场景：既然图的本质是信息结构，那就把结构用文本表达，让图的变更像代码变更一样被管理起来。

1.2 把图当作代码，很多问题就重新有了答案

把一张图从“像素集合”变成“文本描述”，本质上改变了它被管理的方式。我用一个生活化的类比来说明：传统画图像是你在纸上画家具摆放图，画完要改动就得拿橡皮擦，擦完重新画；diagram-design 则像是你用清单和坐标来描述家具的位置，要调整只需改清单里的数字，再重新“打印”一次。

这个转变带来的收益不是锦上添花，而是让一批原本无解的问题有了答案。

第一是版本追踪。源文件进入 Git 之后，每次改动都能看到精确到行的 diff。评审图的时候不再“看图”，而是看文本变更记录。第二是多人协作。因为图有明确的文本结构，两个人改同一个文件会产生冲突，但这个冲突可以被版本系统识别、合并，而不是靠人工肉眼判断两张 PNG 是否一致。第三是自动化。图可以嵌入持续集成流水线，构建时自动渲染，文档发布时自动更新，不再需要某个人手动导出图片到处替换。

第四是可复用。文本描述天然支持模板和参数化。同一个系统架构，我可以定义一套底色、字体、线型的主题文件，然后每个图都引用它。如果团队规范改了配色，我只用改一个地方，所有图重新渲染一遍就全统一了。这在传统画图工具里基本要靠人肉逐个调整，工作量完全不是一个量级。

第五是可检索。文本可以被搜索引擎、IDE、文档系统索引。你可以在整个文档仓库里搜索“数据库节点”，迅速找出所有提到它的图，而不是打开一堆图片文件辨认。

1.3 一套完整的 diagram-design 项目需要解决哪些事

把“写图”从想法落地成项目，需要完整地解决四个环节，这也是我搭建 diagram-design 时的主要工作拆解。

第一个环节是语法设计。你要确定用户用什么方式描述图。我当时的标准是：学习成本低，最好五分钟后就能写出第一张图；表达能力足够，能覆盖流程图、时序图、状态机、拓扑结构这些常见图型；可读性好，即使不渲染成图，光看文本也能大致理解结构。

第二个环节是渲染引擎。语法写好了，需要把它转换成图片。这里我优先考虑的是能否输出 SVG 这类矢量格式。矢量图放大不糊、可以被程序修改、体积小，适合放进技术文档和演示文稿。位图只作为分发用，需要再导出对应规格的 PNG。

第三个环节是工程化集成。源文件、产物、主题配置、模板放在哪，如何让构建命令一条搞定，如何与 Git 钩子、定时任务或 CI 流程配合。这个环节决定了一件事：这套东西是不是真能融入团队日常工作，还是只停留在“个人玩具”阶段。

第四个环节是规范沉淀。图的命名、分组、注释规范、配色规范、依赖关系如何表达，这些都需要像代码规范一样沉淀成约定。图也是代码的一部分，没有约定的图库，过两个月连原作者都看不懂。

2. 方案选型：四条绘图路线的对比与取舍

diagram-design 这类项目并不是从零发明一套完全新的东西，而是把市场上已有的“文本驱动绘图”思路整合成一套可复用的工程方案。在自己的项目里做选型时，我梳理过四条典型路线，它们各有各的适用场景。

2.1 文本建模派：适合软件设计场景的强类型图示

这一类工具的特点是提供了专门为软件设计准备的图表语法，比如类图、时序图、用例图、活动图。语法通常很接近自然语言，一个参与者接一个参与者，一个消息接一个消息，读起来几乎就像剧本。

我推荐这类方案给做架构设计、接口设计、领域建模的团队。原因是它把“图的逻辑”放在第一位：你关心的是谁调用了谁、类之间存在什么关系、状态如何流转，而不是节点怎么排布更美观。这类工具的排版由渲染器自动完成，你只需要明确结构关系。

实际使用中它的优点很明显：上手快，团队内推广阻力小；生成的图结构清晰，适合方案文档；文本源文件本身就是很好的设计记录。缺点是复杂布局的自由度不高，如果你要表达非常精细的排版效果，比如某个节点必须放在画布右上角、某条线必须绕到下面，这类工具通常不支持或者需要额外写很多控制语句。我的建议是，不要为了追求“像素级排版”去对抗渲染器，只要结构表达清楚，自动布局反而更符合统一规范。

2.2 图算法布局派：适合依赖分析与拓扑结构

如果说文本建模派擅长表达“故事线”，那么图算法布局派擅长表达“关系网”。它让你用一种声明式的方式来定义节点和边，然后由内置的算法自动计算布局，通常能生成非常规整的树形结构、层级结构或网络结构。

我在 diagram-design 里大量用这类方案来处理三类图：服务依赖图，用来表达微服务之间的调用关系；部署拓扑图，用来表达组件在主机/容器/网络之间的分布；数据流图，用来表达数据从采集到加工的流向。

这类方案的强项是“自动布局能力”。你把几十个节点和上百条边丢进去，它能在几秒内排出一个清晰的分层布局，节点不会乱叠，边的交叉尽量少。这个表现远超大多数手动画图能达到的质量。它的难点在于需要理解布局算法的基本概念，比如如何通过分层、分组、等级差值来控制图的走向。写节点和边容易，但要把一张复杂的网络图画得漂亮，需要对这些控制参数有手感。

2.3 代码平台的内置绘图组件：适合文档内快速表达

还有一类路线是在文档系统、协作平台或技术社区里直接嵌入图表代码块。我在调研时试过这类方案，它的好处是“不跳出文档编辑环境”。你正在写设计说明书，写到需要一张流程图，直接在文档里插入一段图源码，发布时系统自动渲染成图。

这类方案的体验很顺滑，尤其适合和文档强绑定的场景。因为源文件和文档在一个仓库里，维护心智成本低，不会出现“文档更新了图片没更新”的脱节问题。我在团队里推广 diagram-design 时，第一个落地场景就是技术方案文档，在文档里统一了图源码的编写规范，这样每次文档更新审查时，图的变化也会一并出现在评审列表里。

它的短板是受限于所在平台的能力边界。如果你需要在命令行、脚本、批处理环境里调用图表渲染，或者要把图嵌入到多个不同的输出渠道，内置组件的通用性就不够。所以我在 diagram-design 中把它定位为“面向文档场景的便捷通道”，用于日常设计文档；同时保留独立的渲染命令，用于做自动化任务。

2.4 在线白板：只能当草稿，不该当资产

我也用了相当长一段时间的在线白板类工具。坦白说，白板的自由度和即时性确实无与伦比。头脑风暴、快速对齐思路、临时画个示意，都是它的黄金场景。我用白板画过很多初稿，画完拍照存档，或者导成图片贴在文档里。

但白板有一个致命问题：它没有真正的版本概念。虽然有些白板工具有历史记录，但历史记录只能让你看到“某一天有人改过”，很难精确回答“这一处改动是谁在哪个评审中提出来的”。而且白板文件难以做 diff，难以程序化处理，难以和代码评审流程集成。

所以在 diagram-design 的定位里，白板不是替代对象，而是上游环节。我现在的流程是：先用白板快速发散，确定大体结构；然后把结构用文本描述落地成图的源文件；接下来所有变更都在源码上进行。白板只是临时草稿纸，图资产永远以文本形式沉淀。

2.5 选型对比速查与我的选择标准

为了使用方便，我把这四条路线整理成了一个选型速查表，每次带新项目时直接按这张表判断。

我个人在选型时额外看三个标准。第一个是“是否输出 SVG”。矢量输出意味着我能对图做二次程序化处理，也保证任何分辨率下都清晰。第二个是“命令行是否能脱离编辑器独立使用”。这关系到脚本化构建和 CI 集成，没有命令行能力的工具我基本不会纳入。第三个是“主题样式是否集中定义”。如果每个图都要单独写颜色、字体，那风格统一就是空话，我必须能用一套全局配置控制所有图的外观。

3. 实操：从零搭一套 diagram-design 工作流

理论讲完，下面说点能直接上手的。我会用一个最小但完整的例子，带你从环境准备走到自动化渲染。我会尽量把每一步的命令、参数和原理都讲清楚，你照着做就能在自己的项目里复现这套流程。

3.1 准备环境：装上渲染命令

diagram-design 的第一步是准备好一个能在命令行里调用的渲染器。这类渲染器通常以开源组件的形式发布，通过系统包管理器就能安装。你可以把它理解为一个“文本图纸编译器”：输入图源码文件，输出图片文件。

安装时我有几个经验供参考。第一，优先用稳定版本，不要去追最新的每日构建。图表渲染器的稳定性非常重要，因为一个图集可能涉及上百张图，如果渲染器版本升级后布局算法变化，可能导致所有图重新排列，连锁影响很大。第二，记录安装的版本号，最好在项目里提供一个锁版本的文件。第三，某些隔离环境里安装可能遇到网络限制，建议提前准备离线安装包，或者使用团队内部的软件源镜像。

装完后验证一下命令是否存在。执行版本查询命令能正常输出版本号就算通过。我建议把验证这一步写进项目说明文档，因为团队新成员最容易卡在环境问题上。

3.2 写第一个图：一条消息链路

环境就绪后，用文本文件描述一张最简单的消息链路图。这里我用一类通用的文本图表语法来演示，大部分文本绘图工具的语法结构都类似：先用关键字声明参与者，再用一行行消息描述它们之间的交互。

@actor 用户 U @actor 网关 G @actor 订单服务 O @actor 数据库 DB U -> G : 提交订单 G -> O : 校验订单信息 O -> DB : 查询库存状态 DB --> O : 返回库存结果 O --> G : 返回下单结果 G --> U : 显示订单成功

这个示例的语义很直观：箭头表示方向，冒号后面是消息名称。低于五行的代码就构成了一张完整的时序图。你会注意到它完全没有描述坐标、宽度、颜色这些视觉信息，因为这不是你的职责，渲染器会自动处理。

渲染命令我习惯这样写：

render-diagram 01-order-flow.dsl --format svg --theme default --outdir artifacts/svg

命令里各段的含义分别是：输入文件；输出格式为 SVG；使用名为 default 的主题；渲染结果放入 artifacts/svg 目录。输出后打开 SVG 文件，你会得到一张布局整齐的时序图，参与者横向排布，消息按时间线纵向流动。

如果你想在聊天工具里快速贴图，需要位图格式。同样的命令把--format改成png即可。我在项目里默认输出 SVG 作为正式资产，只在需要分享时额外生成 PNG。PNG 建议指定足够的像素密度，保证截图在 Retina 屏幕上不会发虚。

3.3 工程化目录结构：把源码和产物分开

图一多，项目管理就要跟上。我自己常用的目录结构是这样的：

diagrams/ ├── src/ # 图源文件，一个图一个 dsl 文件 │ ├── 01-api-flow.dsl │ ├── 02-deploy-topo.dsl │ └── 03-state-machine.dsl ├── out/ # 渲染产物，SVG 和 PNG 都放这里 ├── themes/ # 全局主题配置 │ └── default.yaml ├── templates/ # 可复用的片段与模板 │ └── node-styles.yaml ├── manifest.yaml # 构建清单，声明图生成顺序 └── render.sh # 一键渲染脚本

源码和产物严格分开是这套结构的关键约束。src/里的文件是资产，进 Git；out/里的文件是产物，也在 Git 里留一份。很多人会问：产物既然是生成出来的，为什么不加进.gitignore？我的做法是产物也提交，因为文档仓库的使用者不一定安装了渲染器，他们直接就能看到图；同时，评审图变更时可以精确看到 SVG 的 diff，虽然 SVG 的 diff 不如源码那么直观，但至少能看出文件整体发生了哪些区域的变化。

manifest.yaml的作用是按顺序渲染图。有些项目里图有依赖关系，比如先要有总体架构图，再有各模块的分图，构建清单让你固定生成的先后顺序。它还支持给图打标签，比如按子系统分组，这样可以在大量图中只重新渲染某几个分组的图，节省 CI 时间。

3.4 主题与样式统一：改一处，全局生效

图多了以后，样式统一比画出一张漂亮图更重要。我见过不少项目，每张图都用自己的配色、字体和线型，拼在一起像几个不同团队的作品，很不专业。diagram-design 的做法是把样式抽成主题文件，渲染时全局引用。

下面是一个简单的主题配置示例：

theme: background: "#ffffff" font: "Noto Sans CJK SC" colors: primary: "#2f54eb" success: "#52c41a" danger: "#ff4d4f" muted: "#bfbfbf" node: padding: [12, 8] radius: 4 edge: color: "#595959" width: 1.5 arrow: "normal"

这个配置没有绑定具体的工具语法，但思路在所有文本图表方案里都适用：颜色定义成语义名称，节点样式统一，边的风格统一。一旦团队品牌色调整，只需要改主题文件，重新渲染全部图即可。这个能力传统的图形画板很难做到，几乎只能靠人肉逐个改。

我在实践中还发现一个细节：字体配置要优先选系统内置的中文字体，比如“Noto Sans CJK SC”“PingFang SC”“Microsoft YaHei”。很多默认配置用的是纯英文/拉丁字体，中文处理不好会显示成方块，这个问题后面我会在常见问题里专门展开。

3.5 自动化：提交即渲染，文档永不过期

手工执行渲染命令只是第一步，要想真正摆脱“图没人更新”的魔咒，必须把渲染流程接入自动化系统。我在项目里做了两层自动化。

第一层是本地 Git 钩子。在pre-commit钩子里检查src/下的源码文件是否有改动，如果有，就先执行渲染命令把新图生成出来，再将渲染产物加入本次提交。这样每次提交的变更都包含“源码变更 + 对应产物变更”，不会出现源码已经改了、图片还是旧的的情况。

第二层是持续集成流水线。每次推送分支时，CI 里执行一次全量渲染，并将其与仓库中已有的产物做对比，如果有差异说明有人提交了源码但没提交产物，流水线直接标记失败。这个策略看起来严格，但非常管用，等于在流程层面堵住了“图不同步”的漏洞。

伪代码大致是这样：

render_diagrams() { for file in diagrams/src/*.dsl; do render-diagram "$file" --format svg --theme default --outdir diagrams/out/svg done } verify_sync() { git diff --quiet -- diagrams/out/svg || { echo "检测到图产物未同步，请先执行渲染脚本并重新提交" exit 1 } }

这套流程跑起来之后，团队里再也没出现过“文档里的架构图还是三个月前那张”的情况。图在提交时自动更新，在评审时自动被检查，在发布文档时自动生效，整个过程不再依赖某个人的手工纪律。

4. 实战案例：为一个订单系统绘制四张核心图

讲完基础设施，我用一个完整的实战案例来演示 diagram-design 在一个模拟订单系统项目中的应用。这个案例包含四张图：业务实体关系、服务调用时序、部署拓扑、状态流转。这四张图基本覆盖了技术方案评审中最常被问到的问题。

4.1 先列图清单，再动手画

我一开始栽过跟头：急着画图，画到一半发现少了一张关键图，又倒回去补，整个文档结构很乱。后来我养成的习惯是，写文档之前先规划图清单，明确每张图回答什么问题。

这个模拟订单系统的四张图各有分工：实体关系图回答“系统里有哪些核心数据，它们怎么关联”；服务调用时序图回答“一次下单请求经过了哪些环节，每个环节做什么”；部署拓扑图回答“服务跑在哪，依赖哪些基础设施”；状态流转图回答“订单走到每个节点后能去哪些地方，不能去哪些地方”。

每张图对应文档里的一个章节，图的编号、标题和源文件一一对应。这样做的好处是评审时对方说“某张图有问题”，我能立刻定位到源文件、定位到行，当场修改重新渲染，而不是回到画布里去翻找图层。

4.2 实体关系图：只画关键字段

实体关系图描述数据模型。不少新手喜欢把所有字段都堆上去，结果图变成长方形堆叠，根本没法看。我的原则是只展示“与理解关系有关”的字段，比如主键、外键、状态枚举，其余字段留在数据字典里维护。

@entity 用户 { 用户ID: string <<key>> 注册时间: datetime 状态: enum } @entity 订单 { 订单ID: string <<key>> 用户ID: string <<fk>> 总额: decimal 状态: enum } @entity 支付记录 { 支付ID: string <<key>> 订单ID: string <<fk>> 支付状态: enum } 用户 ||--o{ 订单 : "下单" 订单 ||--o{ 支付记录 : "支付"

这里的关键是关系线本身的语义：双竖线表示强关系中“必须存在的一方”，圆圈表示“可选的多方”。这个系统初看很理论化，但它直接影响你理解数据约束。比如“用户和订单之间是必有一方、可有多方”，意味着一个用户可以有多个订单，但订单一定属于某个用户。

渲染成图后，评审者能第一时间看清核心实体的关联关系。我还会在关系线上补充中文注释，因为纯英文的关联名，在中文技术评审里容易产生歧义。

4.3 服务调用时序图：表达成功路径和备用路径

时序图是整个文档里阅读频率最高的图。对于模拟订单系统，我画了一张“发起支付”的时序图，重点表达三件事：正常流程的调用顺序、库存校验的关键步骤、失败时的降级处理。

@actor 客户端 C @actor 网关 G @actor 订单服务 O @actor 支付服务 P @actor 仓库服务 W C -> G : 请求创建订单 G -> O : 校验参数并创建订单 O -> W : 预占库存 W --> O : 库存确认 alt 库存不足 O --> C : 返回库存不足 else 库存充足 O -> P : 拉起支付 P --> O : 支付结果回调 O --> C : 返回下单成功 end

注意里面用了alt分支块来区分成功和失败。这类分支逻辑写在文档里很啰嗦，放在图里则一目了然。时序图要控制参与者的数量，我这张图只有五个参与者，再多就会横向溢出，读起来吃力。如果系统调用链真的很长，我会拆成“主链路图”和“详细展开图”，而不是强行塞进一张图。

4.4 部署拓扑图：标注关键网络信息

部署拓扑图适合用图算法布局类方案。我手写节点和边，由渲染器自动分层，通常能排得比我手动拖拽还整齐。

@node 客户端应用 [type=client] @node 负载均衡 [type=lb] @node 订单服务 [type=server, port=8080] @node 支付服务 [type=server, port=8081] @node 数据库主库 [type=database] @node 数据库从库 [type=database] 客户端应用 -> 负载均衡 : HTTPS 443 负载均衡 -> 订单服务 : HTTP 8080 负载均衡 -> 支付服务 : HTTP 8081 订单服务 -> 数据库主库 : JDBC 3306 订单服务 -> 数据库从库 : JDBC 3306 (只读)

在标注上我坚持两点：端口必须写，因为评审时人家会问；安全相关的信息如“HTTPS”要显式标明。这张图不需要写主机 IP，IP 属于环境配置，而不是架构图要表达的内容。把架构图和配置清单分开，图才不会频繁变动。

部署图是最容易过时的图，因为环境一变就要跟着改。好在用文本描述后，改起来成本很低，无非是改一行节点声明，重新渲染一次。这也正是 diagram-design 在维护性上的优势体现。

4.5 状态机图：让枚举和图保持一致

最后是订单状态的流转图。这张图在评审时最容易吵架，因为状态的命名、流转的合法性，不同人的理解经常不一致。我的建议很直接：状态机图必须和代码里的状态枚举严格对应，否则图就是摆设。

@state 待支付 @state 已支付 @state 已发货 @state 已完成 @state 已取消 @state 退款中 待支付 --> 已支付 : 支付成功 待支付 --> 已取消 : 用户取消 已支付 --> 已发货 : 商家发货 已发货 --> 已完成 : 确认收货 已支付 --> 退款中 : 申请退款 退款中 --> 已取消 : 退款完成

画这张图前，我先翻出了代码里的状态枚举定义，发现枚举里还有一个“支付超时关单”的状态，图里没画出来，这是明显的图与代码不一致。补上之后，我又顺手写了一个 CI 校验脚本：解析图源码中的状态节点，和代码枚举文件做比对，不一致就报错。这个脚本上线后，状态机图基本不再出现过时问题。

5. 高频问题与排查技巧实录

这部分是我在实际跑 diagram-design 项目时踩过坑的总结。任何一个文本绘图工程化方案，用久了都会遇到下面几类问题，提前知道解法能省下大量排查时间。

5.1 中文全部变成方块或乱码

这是新环境里出现频率最高的问题。渲染器默认字体如果只包含拉丁字形，遇到中文就会渲染成一个个方框。我早期在 CI 环境里就栽过一次：本地渲染一切正常，推到流水线里生成的图全是方块。

解决办法是在主题配置里指定中文字体。优先选择系统自带的中文字体名称，比如“Noto Sans CJK SC”。同时要注意，CI 的容器环境不一定预装这种字体，需要在构建阶段显式安装。我一般会在容器安装脚本里加一步字体包安装，并设置环境变量指向字体目录。

排查顺序是：先确认系统里是否安装了字体，执行系统字体查询命令查看中文字体是否在列表中；再检查主题配置里的字体名称是否和系统字体名称完全一致；最后确认渲染日志里是否有字体回退的警告。基本三步能定位大部分问题。

5.2 布局混乱：节点重叠、边绕来绕去

文本绘图工具自动布局虽然强大，但面对复杂的图，偶尔也会排得让人崩溃。节点离得太远、边的交叉数太多、本来属于一组的节点被拆散到两个角落。这通常不是渲染器的 bug，而是你没有给它足够多的“排版约束”。

图算法布局类方案通常会提供分组、层级、排序之类的控制参数。我的经验是，画之前先在代码结构上把图合理分组。比如部署拓扑图，把所有数据库节点放在一个名为“数据层”的组里，所有应用节点放在“服务层”的组里。分组之后，渲染器会优先保证组内聚和组间次序，混乱程度大幅下降。

还有一个实用技巧：给关键路径的边增加更强的“等级约束”，让主流程尽量从上到下、从左到右贯穿。把主路径的边定义为高优先级后，渲染器会优先拉直这条路径，次要路径再围绕它排布。经过这样的调整，复杂图的可读性会明显改善。

5.3 渲染出来还是老图，改了源码没生效

这个问题常见于有缓存机制或增量构建的流程。我排查的思路是逐层核对：先查看源文件是否确实保存成功并改对了；再手动执行一次渲染命令，看输出是否更新；如果手动渲染没问题，那就是自动化流程里命中了旧缓存；最后检查仓库工作区里是否有未合并的改动或者分支切错导致的文件覆盖。

有一种很隐蔽的情况：源文件和应用的产品文件不在同一个目录路径下，渲染脚本用的是相对路径，当前目录不对导致它找了一个残留的旧文件。所以我在脚本里强制写绝对路径，或者先cd到项目根目录再执行渲染命令，避免路径歧义。

5.4 图和代码不一致：图没人维护了

图与实现脱节，是所有文档项目的通病。文本化解决了追踪问题，但没解决“人不去改”的问题。我的经验是，把关键图的校验也做成自动化。具体做法是给特定图写校验脚本：

• 状态机图：解析图里的状态节点，与代码枚举比对，出现多、少、不一致就报错。
• 依赖图：检查是否出现了不允许存在的调用方向，比如网关层调用了数据库，这种依赖违规直接拦在 CI。
• 部署图：核对节点端口和配置中心的服务端口是否一致。

自动化校验脚本让“图过期”从一个隐性风险变成了显性构建错误。出了问题第一时间就有人处理，而不是等到文档评审时才发现图片和真实系统已经彻底对不上。

5.5 图太复杂，渲染时间越来越长

当一张图包含上百个节点和数百条边时，渲染时间会明显上升。我见过一张大图渲染超过一分钟的情况，这在本地还能忍，放到 CI 里就是煎熬。

解决方案有两个方向：拆分和分层。拆分是指把一张巨型图拆成多张子图，比如“系统全景总览图”只留宏观模块和关键连线，细节由各模块自己的图来承担；分层是指在构建顺序上先渲染底层模块图，再渲染聚合的上层图，上层图直接引用下层图作为子图。

我还会在渲染脚本里加一个超时保护和输出缓存。当源文件没有变化时，跳过重新渲染，直接复用上一次的产物。这能显著缩短日常构建时间，只在涉及图变更时才触发全量渲染。

这个流程跑了大半年之后，我的体会是……

diagram-design 给我带来的最大改变，不是我能更快画图，而是我再也不怕图需要改动了。评审会上有人提了一个结构调整的建议，散会后我花十分钟改完源码、重新渲染、更新文档、提起提交。整个过程有记录、有对比、可追溯，不像以前要在画布上重新拖一遍。

最后再分享一个小技巧：我把常用命令封装成了一个脚本，并加了一条自检命令verify。新成员加入项目后，只跑一次diagram verify，就能检查环境、渲染一张样例图、并确认产物是否与仓库一致。这让我少回答了很多次“这个命令怎么用”的问题。如果你的团队也在被文档里的图表维护折磨，我建议不要急着买白板工具或画图软件，先试着把一张最常变更的图画成文本，把它交给版本库去管理。你会发现，图一旦能像代码一样被对待，它就再也没有理由变成文档里那块最不受待见的旧资产了。