draw.io代码驱动:XML、CLI与CI/CD自动化出图
1. draw.io其实自带“代码驱动”基因,只是没人告诉你
1.1 从一次手动出图的崩溃说起
如果你搜一下“draw.io 代码驱动”,大概率会先看到一堆单片机驱动屏幕的代码,而不是你想找的东西。我第一次找draw.io自动化玩法时就被这个结果逗笑了。作为一款免费、开源、文件格式开放、自带CLI的绘图工具,它在“代码驱动”这件事上的能力,远比大家以为的冷门。
事情要从一次画图任务说起。那时候团队要做一份覆盖两百多个门店的网络改造拓扑图,每个门店一框设备、几条上行链路、一组标注。我坐在draw.io里拖了一下午:加框、对齐、连线、改字号、导出图片,反复调整到眼花。做到一半我就在想,这种重复劳动,真的不应该由人来做。
也是那次之后,我才认真翻了draw.io的文档,才发现它远不止是个“画图软件”。它的源文件是结构化文本,它自带命令行,它的网页版甚至能通过URL远程加载文件、嵌入自己的站点。换句话说,只要有那么一点点编程基础,你就能让脚本替你生成图、改图、导图。这些东西不藏在大版本更新说明里,不写在弹窗提示里,所以很多人从头到尾都没意识到。
1.2 我理解的“代码驱动”分四层
后来我把draw.io的自动化能力拆成四层,方便自己梳理,也方便团队里的小伙伴上手:
- 文件层:.drawio本质是XML,任何语言都能读写,可以用脚本批量改样式、改文字、改坐标,甚至从零生成一整张图。
- 命令行层:draw.io自带CLI,能无界面导出PNG/SVG/PDF,能指定页面、缩放、边距,能一次性处理整个目录。
- 协议层:通过URL参数,你可以让网页版drawio打开远程文件、进入指定编辑模式,或者用官方viewer把图嵌进自己的站点。
- 生态层:draw.io基于mxGraph构建,源码在GitHub上开放。如果你愿意,可以直接用JS构建、操控图形模型,甚至在自己的产品里集成一个图表编辑器。
这篇文章我按这四层逐个展开,每层都会给实际可复用的命令和代码。你不用一次性全掌握,挑一个自己最痛的点切入就行。
1.3 先判断你需不需要代码驱动
别急着上自动化,先泼盆冷水:如果你的画图场景是“偶尔画一张思路图发给同事”,那GUI拖拽完全够用,代码驱动反而增加学习成本。但如果你符合下面任何一条,建议往下看:
- 每周都要更新一批架构图、拓扑图、流程文档,图的内容跟着系统变更走;
- 有一堆历史图表需要统一改字体、改配色、加水印、换边距;
- 想在CI/CD里自动生成并发布图表,而不是靠人打开GUI手动“导出为图片”;
- 想把服务器清单、数据库表结构这类结构化数据,直接变成一张图。
我个人的判断标准就一句话:图的生命周期越长、更新频率越高,越值得用代码驱动;一次性画完就扔的图,不值得。
2. 解剖.drawio源文件:一张图在XML里到底是什么样
2.1 最小可运行的drawio文件
很多人可能从来没打开过.drawio源文件。我建议你下次随便画一框一箭头,另存为.drawio,再用文本编辑器打开,你会看到一个类似这样的结构:
核心是root下面那堆mxCell。mxCell带vertex="1"是形状节点,带edge="1"是连线。每个节点都通过id互相引用,边的source和target就是两个节点的id。就这么简单。
我第一次从源码角度看到这个结构时,心里只有一个想法:这东西简直就是为了脚本准备的。只要你会字符串拼接,你就能造出一张可以正常打开的drawio文件。
2.2 三个你必须理解的属性
id:全图唯一。手写XML出问题的头号原因就是id重复,或者边引用了不存在的id。style:一个分号分隔的键值字符串,控制形状、颜色、连线方式。你可以把它想象成CSS的行内版。mxGeometry:决定节点位置。注意x/y是相对父节点的坐标,不是页面全局坐标。如果某个盒子被放进了泳道或容器里,坐标就是相对于那个容器的,这是新手最容易算错的地方。
还有个很多人不知道的特性:value里如果style开了html=1,就能直接塞带HTML标签的内容。也就是说,你可以用<b>标题</b><br><font color="#888">副标题</font>这种形式做出带格式的节点文字。脚本生成图时,这个特性非常有用,不用为每个字体样式单独定义形状。
2.3 为什么理解XML是自动化的前置条件
因为一旦理解了格式,一切都变成“字符串处理”。改标题就是替换value,改颜色就是替换style里的fillColor,挪位置就是改mxGeometry里的x/y。任何会写Python、PowerShell、甚至awk的人,都能在不动GUI的情况下批量修改成百上千个图。
我自己的习惯是用lxml解析,遍历感兴趣的mxCell,改完属性再写回。下面这段就能把某个文件里所有节点文字批量替换掉:
注意一个小坑:drawio的XML里命名空间很轻,直接在根上遍历mxCell一般就够了。但如果文件里混入了嵌入对象(图片、表格、附件),元素路径会更复杂。我建议先跑一句print(etree.tostring(root, pretty_print=True))看看实际结构,再写遍历逻辑。
2.4 常用style速查
我整理了几个高频style,直接复制就能用:
| 用途 | style |
|---|---|
| 普通矩形 | rounded=0;whiteSpace=wrap;html=1; |
| 圆角矩形 | rounded=1;whiteSpace=wrap;html=1; |
| 数据库圆柱 | shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15; |
| 云 | ellipse;whiteSpace=wrap;html=1;fillColor=#D8EBFF;strokeColor=#0A66C2; |
| 泳道 | swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;collapsible=1;marginBottom=0; |
| 正交边 | edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=block; |
这些样式参数在GUI的“编辑样式”对话框里也能看到,但脚本里直接写更快。style里的键值顺序无所谓,因为drawio会自己解析,但键值之间必须用分号分隔,最后一个分号写不写都行。
3. 命令行CLI:只装一次,彻底告别手动导出
3.1 安装和环境里的坑
draw.io桌面版自带命令行工具,安装桌面包之后,终端里就有drawio命令。macOS可以用brew install drawio,Linux上通常下载AppImage,Windows装完exe一样能用。装完先验证:
如果你在无显示器的Linux服务器上跑,大概率会遇到Electron的沙箱报错,加--no-sandbox即可:
如果连X server都没有,可能需要配合xvfb-run才能渲染出图:
这一步是“命令行版能跑”和“服务器版能跑”的分水岭。很多人在本地试了CLI没问题,一上CI就报错,基本都是沙箱和显示环境的问题。
3.2 高频导出命令速查
CLI最常用的就是导出,我整理了一个速查表:
| 命令 | 作用 |
|---|---|
drawio -x -f png -o out.png arch.drawio |
导出PNG |
drawio -x -f svg -o out.svg arch.drawio |
导出矢量SVG |
drawio -x -f pdf -o out.pdf arch.drawio |
导出PDF |
drawio -x -f png -s 2 -b 16 arch.drawio |
2倍缩放、16px边距 |
drawio -x -f png -p 0 arch.drawio |
只导出第1页 |
drawio -x -f png -g 1-3 arch.drawio |
导出第1~3页 |
drawio -x -f png --transparent arch.drawio |
透明背景 |
drawio -x -f png *.drawio |
批量导出整个目录 |
几个参数的解释:
-x是进入导出模式,后面一般跟-f指定格式。-o指定输出文件名;不指定时,默认会生成同名的目标格式文件。-s是缩放倍率,导高清图、做PPT配图时常用-s 2,能明显改善文字边缘锯齿。-b是边距,给图片留呼吸感。默认边距偏小,导出后图紧贴边缘,视觉上很局促。--transparent适合导SVG或透明底PNG做网页素材,注意透明背景导出后的文字颜色也要匹配。
3.3 多页文件的导出行为差异
对多页文件要特别注意:不同版本、不同平台,默认行为可能不一样。我在24.x版本上实测,直接drawio -x -f png multi.drawio会把每一页都输出成一个文件,文件名自动带上页码;如果你的脚本死等一个multi.png,可能等出一堆multi-v1.png、multi-v2.png。所以批量脚本里一定要写清楚-p或-g,并且先拿一个两页以上的测试文件验证行为,再铺开。
还有个细节:导出PDF时,多页文件默认会按键分页。如果你想要的是“一整张大图”而不是“分页PDF”,建议导出SVG后自己转换,或者先在模型里把页面尺寸改大。
3.4 一次批量导出200张图的实操
我做过一次“给200多个架构图批量加水印并导出”的活。思路很直白:先用Python往所有.drawio文件里注入一个加了半透明水印文字的mxCell,再用CLI一口气全部导出PNG:
跑之前我以为会出各种问题,实际上唯一卡住我的就是文件名里有空格。变量$f没加引号时脚本直接裂开,加上引号之后干干净净跑完。这种细节,平时手动导出时永远碰不到,只有写脚本才会暴露。还有个忠告:先跑3个文件确认输出命名规则,再放开全量跑,不然日志刷屏幕的时候你根本分不清谁是谁。
4. 用脚本批量生成图形:模板拼接是起点,模型构建才是进阶
4.1 最朴素的模板拼接
如果你只是偶尔生成一张图,直接字符串拼接就够了。我自己写了个极简辅助函数,生成一个矩形节点:
连线同理:
为什么一定要html.escape?因为节点文字里一旦出现&、<、>,XML就非法了。我有一次把一长串带WHERE a < 5 AND b > 3的SQL条件塞进value,drawio直接打不开,后来才发现尖括号没转义。看起来是两行代码的小事,但这类细节才是脚本出图“能跑”和“能扛”的差别。
4.2 从CSV生成网络拓扑图的完整案例
更实用的场景:你有一份CSV服务器清单,里面有设备名、所属分组、IP,以及和上游设备的依赖关系。用二十行Python就能自动排版出一张拓扑图。
思路分三步:
- 读CSV,给每个设备分配一个id和坐标。
- 按分组把列排好:分几组就放几列,组内从上往下排。
- 根据依赖关系生成
edge。
坐标计算我会写成简单的行列映射:
生成完把整段XML拼进标准的mxfile骨架,保存为.drawio。这个文件在本机可以正常打开编辑,也能提交到仓库里,由后续流程自动导出成图片。整个链路是“列表数据 -> 结构化XML -> 可编辑源文件 -> 自动化出图”,这比让一个同事对着Excel手工画图靠谱得多。
这里我要多说一句排版的哲学:脚本生成的图,美观程度通常不如手工精修的图,但它的价值在“可再生成”。下次服务器列表变了,重跑一遍脚本就得到更新后的图,人工画的图可做不到这点。
4.3 为什么不推荐现在就把JSON当主格式
draw.io从24.x开始在部分编辑器里支持JSON格式,但生态兼容性还没到“所有场景默认可开”的程度。我的建议是:对外输出、版本管理、CI/CD都优先用.drawio的XML格式,因为mxfile是draw.io的原生格式,跨版本、跨平台行为最稳定。JSON格式可以尝尝鲜,但别用在自动化流水线上,否则一次编辑器版本升级可能让你的脚本全部翻车。
顺带提一句,我这里说的是“用脚本直接生成的XML”,跟draw.io里的“模板库”是两回事。模板库解决的是“重复图模板”问题,脚本解决的是“数据变图要跟着变”的问题,两者可以共存。真正高频更新的图,脚本的价值远超模板。
5. URL参数与嵌入式viewer:让图表在你的网站里“活”起来
5.1 一个URL就能让drawio打开远程文件
draw.io网页版支持直接在URL里指定要打开的文件。官方约定是在锚点里跟#U或#R,后面接URL编码后的地址:
#U表示打开并允许保存回源地址,#R表示只读打开。如果你管理着一个内部文档站点,想在文档里放一个“用drawio查看这张图”的入口,这个链接就够了。
还可以加UI参数,比如?ui=sketch切换手绘风格皮肤、?dark=1默认暗色、?title=myname自定义标题。我自己用得最多的是?edit=_blank,强制新标签页打开编辑器,避免用户把页面带跑。
5.2 常用URL参数表
我整理了几个实际用过的参数:
| 参数 | 示例 | 作用 |
|---|---|---|
ui |
?ui=sketch |
切换皮肤,sketch是手绘风 |
dark |
?dark=1 |
默认暗色主题 |
title |
?title=arch |
自定义标题 |
edit |
?edit=_blank |
编辑行为控制 |
offline |
?offline=1 |
离线模式 |
注意:URL里的#U后面跟的地址必须做完整的URL编码,常见错误是直接把https://写进去,结果链接变歪。写脚本拼URL时,记得用encodeURIComponent或Python的urllib.parse.quote。
5.3 用官方viewer嵌入自己的站点
如果你不想让用户跳去drawio编辑,而是直接在自己页面里展示可交互的图,官方提供了viewer(查看器)。iframe引入就行:
viewer支持高亮、折叠图层、显示导航缩略图(nav参数),交互体验和编辑器中的查看模式基本一致。这里的highlight参数可以指定高亮颜色,做文档系统时非常实用。
5.4 CORS这个隐形杀手
有一个我踩了大坑的经验:viewer加载远程文件受浏览器CORS限制,如果文件所在的服务器没返回允许*.diagrams.net访问的CORS头,iframe里就永远是一片空白。当时我排查了一下午,最后发现是对象存储的跨域策略没开。
解决办法很直接:把CORS头加上,或者干脆把.drawio文件放到和viewer同域,或者用fetch提前把文件内容读出来再交给viewer。如果你做的是内部工具,建议第一种方案,配置一下就好了。
6. mxGraph生态:比XML更底层的代码驱动路径
6.1 draw.io和mxGraph的关系
你可能不知道,draw.io的画布引擎来自mxGraph,一个老牌的开源图形库。draw.io相当于在mxGraph外面包了一层编辑器、文件格式和协作能力。既然draw.io本身就建立在这套图形模型上,那“代码驱动”当然也有比XML更底层的路径:直接用mxGraph的API在内存里构建图形。
这层玩法适合的场景很明确:你想在自己的产品里嵌入一个和draw.io同源的图表编辑器,或者你希望在纯前端环境中动态生成、修改图,而不用回到文件层面做字符串操作。
6.2 一个最简的mxGraph示例
在Node或浏览器环境里,通过npm引入mxgraph后,核心操作大概是这样:
看到没有,和你在drawio里手动操作是一回事:插入顶点、插入边、修改坐标。只不过这次是从代码发起。beginUpdate和endUpdate是关键,它们把多次修改包成一个事务,否则图形会一遍遍重绘,性能惨不忍睹。
6.3 什么时候才需要用这层
以我的经验,mxGraph这层不是给普通用户准备的,它的引入成本主要在工程化:构建、打包、事件处理、样式覆盖,都要自己搞。如果你只是想让drawio和脚本配合工作,前面几章的内容已经够了。
但如果你做的是一次性内部工具,想让最终用户直接在一个网页里看到实时生成的图,那mxGraph就很有价值。比如从数据库元数据生成ER图,用户改一个表名,图里的节点跟着变。这种体验,用CLI导出的静态图片是给不了的。
我建议把这条路径当作进阶选项,不要一开始就扎进去。先把XML和CLI玩熟,当它们出现瓶颈时,再考虑mxGraph。顺序反过来,大概率会被工程细节劝退。
7. CI/CD里的图表自动化:团队协作流的一次改造
7.1 从commit到成品图的完整流水线
我们团队现在的图表工作流是:
- 研发把.drawio源文件提交到仓库,文件放在
docs/下。 - 数据驱动的图由脚本生成,也提交源XML。
- CI流水线里跑一遍drawio CLI,把所有图导出成PNG/SVG。
- 导出的图片随文档发布,仓库里可以直接展示PNG预览。
CI里最核心的步骤其实就几行,配合GitHub Actions或其他CI的job直接执行:
这套流水线跑起来之后,团队再也不用互相喊“帮我导出一下这张图”,图永远是生成出来的,不是“辛苦导出来”的。
7.2 用脚本做“图表健康检查”
既然.drawio是XML,你还能在CI里做很多人肉检查做不到的事:
- 检查所有图中是否存在孤立节点(没有任何边连接的vertex)。
- 检查重复的id。
- 检查style里是否混入了团队不统一的配色。
举个例子,孤立节点检查,用lxml遍历并把所有vertex="1"的id收集起来,再看所有edge的source/target,没被任何边引用的就是孤立节点。这种检查曾经帮我抓出过两份架构图里忘了连线的关键设备,比peer review靠谱得多。
7.3 版本管理里图和代码一样值得review
很多人纠结“图要不要进Git”。我的答案很明确:.drawio源文件一定要进,导出的图片是可选的。因为源文件是文本,diff能看出谁改了哪个节点的value;图片是二进制,diff毫无意义。让CI在需要的时候重新生成图片就够了,避免提交大量变更频繁的PNG。
如果你嫌Git的文本diff不可读,分享一个小技巧:把.drawio文件用xmllint --format格式化后再提交,diff就会从“一整行乱码”变成“某个节点那一行变了”,review体验好很多。
7.4 一个CI里容易忽略的坑:字体缺失
在容器环境跑drawio导出,最隐蔽的问题是字体。默认镜像里没有中文字体,导出的PNG里所有中文都可能是方框。我遇到过“构建产物明明生成了,客户打开却是满屏豆腐块”的尴尬。解决办法很简单,在CI里装fonts-noto-cjk:
装不装这套字体,直接决定了你的图是不是能看的图。
8. 我踩过的坑,和给想上手的读者的一句话
8.1 特殊字符与转义
最常踩的坑我在前面反复强调过,但它值得单独占一小节:XML的value属性和标签文本是两套转义规则,属性值里的引号也会出问题。我的经验是所有从外部数据带入的值一律走html.escape或对应的XML转义函数,永远不要直接拼原始字符串。
8.2 多页导出的行为差异
drawio CLI在不同版本、不同平台的默认导出行为不完全一样。这属于“文档不写、实测为准”的范畴。我的建议就一句话:写自动化脚本前,先拿一个两页以上的测试文件把你要用的参数跑一遍,确认输出文件名和内容,再铺开到大批量任务。
8.3 无头服务器上的Electron问题
在纯命令行的Linux服务器上,drawio导出依赖Chromium渲染,可能遇到沙箱、字体、无显示环境三类问题。沙箱问题加--no-sandbox,中文字体问题加fonts-noto-cjk,显示环境问题就配合xvfb-run。这几个坑单独出现还好,一旦叠在一起,新手很容易误判成“CLI在服务器上不可用”,其实只是环境变量没配齐。
8.4 我的真实体会
最后说句实在话:draw.io的“代码驱动”能力并不难,难的是你先意识到它有这个能力。我认识很多画图很熟练的人,画了几年图,从来没打开过一次源文件,也没跑过一行CLI。而当你开始用脚本批量生成、用CI自动导出、用viewer嵌入页面时,draw.io就不再是“一个画图工具”,而是你图表生产线上的一个引擎。这句话我没有夸张,你可以先挑一个小场景试试:写个脚本,把某个文件里所有节点文字批量替换一遍,再导出成PNG。跑通一次,你大概就能感受到这个隐藏功能的力量。