开发者福音：Excalidraw支持代码模式直接导出图形

开发者福音：Excalidraw支持代码模式直接导出图形

在技术文档、系统设计和团队协作中，一张清晰的架构图往往胜过千言万语。但你有没有经历过这样的场景？刚写完一篇微服务调用关系说明，回头一看配图还是三个月前的老版本；或者想在 PR 中更新组件依赖，却因为“不会用绘图工具”而干脆不加图示？

这类问题背后，其实是传统图形创作方式与现代工程实践之间的脱节——我们已经用 Git 管理代码、用 CI/CD 自动部署，可图表依然停留在“截图+粘贴”的手工时代。

直到最近，Excalidraw 推出的“代码模式直接导出图形”功能，终于为这个长期痛点提供了真正契合开发者工作流的解决方案。它不只是多了一个导出按钮，而是重新定义了“画图”这件事本身：从手动拖拽，走向编写、生成、集成、自动化。

为什么是 Excalidraw？

市面上绘图工具不少，为何 Excalidraw 能脱颖而出？关键在于它的定位非常精准：不做全能型选手，专攻“技术人表达思想”这一细分场景。

它没有复杂的样式面板或企业级权限体系，相反，整个界面干净得近乎极简。但它用一种独特的“手绘风”线条，巧妙地降低了沟通的心理门槛——不像 Visio 那样正式压抑，也不像白板涂鸦那样随意难读。这种风格既保留了草图的灵活性，又具备足够的结构化信息承载能力。

更重要的是，它的底层数据模型是完全开放且结构化的 JSON。这意味着每一根线、每一个框都不是像素堆砌，而是可以被程序读取、修改和生成的数据对象。

这为后续的自动化能力打下了坚实基础。

图形也能“编程”？看看它是怎么做到的

当你在 Excalidraw 里画一个矩形时，其实系统内部记录的是类似这样的结构：

{ "type": "rectangle", "x": 100, "y": 100, "width": 200, "height": 80, "label": { "text": "API Server" }, "strokeColor": "#000" }

是不是很像你在 React 组件里写的 props？没错，这种设计让熟悉前端开发的人几乎零学习成本就能理解其数据逻辑。

所有图形元素都遵循统一 schema，包括位置、类型、文本标签、颜色、连线关系等。整个画布的状态就是一个 JSON 数组，可以直接序列化存储、通过 Git 提交，甚至做 diff 对比。

比如，当有人把“数据库”框向右移动了 30 像素，在 Git 提交记录里会显示为：

- "x": 400 + "x": 430

而不是像传统绘图软件那样，整个二进制文件变了个“黑盒”，根本看不出改了啥。

从“画图”到“写图”：代码模式如何运作

真正的飞跃发生在v2.5 版本之后，Excalidraw 社区推出了excalidraw-cli工具，允许你在无头环境下将 JSON 文件渲染成 PNG 或 SVG 图像。

这意味着什么？

意味着你可以把图形生成纳入 CI/CD 流程，就像编译代码一样“编译出图”。

具体流程如下：

1. 编写一个.excalidraw.json文件，描述你要的图表内容；
2. 在本地或服务器上运行命令：
   bash excalidraw export --input arch-diagram.excalidraw.json --output arch.png
3. 输出一张高质量的手绘风格 PNG/SVG，可直接嵌入文档、Wiki 或 PPT。

整个过程无需打开浏览器，也无需人工操作 UI。如果你使用的是 MkDocs、Docusaurus 或 VuePress 这类静态站点生成器，完全可以实现“每次提交代码，自动刷新配套架构图”。

更进一步，结合 AI 模型（如 LLM），还能构建“文字 → 图表”的全自动流水线。

设想这样一个场景：

“新增 Payment Service，由 Order Service 调用，通过 Kafka 异步通知 Notification Service。”

只需一行自然语言输入，脚本调用 LLM 解析语义，输出标准 JSON 结构，再交给excalidraw-cli渲染成图。整个过程几秒完成，且保证风格一致、布局规范。

实战案例：微服务文档自动化

来看一个真实可行的工作流设计。

假设你的团队正在维护一份系统架构文档，过去的做法是：

• 架构师画好图 → 导出 PNG → 插入 Markdown → 手动上传仓库；
• 后续变更靠“记得去改图”，结果往往是文档滞后于实际架构。

现在，我们可以这样重构流程：

graph LR A[PR 提交新架构描述] --> B{CI 检测 .arch.yml} B --> C[调用 Python 脚本] C --> D[生成 .excalidraw.json] D --> E[执行 excalidraw-cli 渲染] E --> F[输出 PNG 并替换旧图] F --> G[自动提交文档更新]

其中.arch.yml可能长这样：

services: - name: Order Service position: [100, 100] color: "#ff6b6b" - name: Payment Service position: [300, 100] color: "#4ecdc4" - name: Notification Service position: [500, 100] color: "#ffd93d" connections: - from: Order Service to: Payment Service type: sync - from: Payment Service to: Notification Service type: async via: Kafka

Python 脚本负责将其转换为符合 Excalidraw schema 的 JSON，再触发渲染。最终产出的不只是图片，更是一套可复现、可追溯、可审计的技术资产。

优势不止于“省事”

也许你会问：这不就是个自动画图工具吗？有什么特别的？

其实，它的价值远超“提升效率”这一层。真正重要的是，它改变了我们对待图形内容的方式：

换句话说，图形也被纳入了软件工程的最佳实践中：版本控制、变更追踪、同行评审、自动化测试。

举个例子，如果某个新人提交了一个新服务接入方案，附带的架构图如果不符合规范（比如用了错误的颜色标识外部系统），CI 脚本甚至可以在渲染阶段报错，阻止合并。这就实现了“设计合规性检查”的自动化。

如何开始使用？几个实用建议

虽然技术门槛低，但在落地过程中仍有一些经验值得参考：

1. 建立“图形组件库”

将常用元素抽象成可复用片段，比如：

// components/db.js export const postgresDB = (x, y, label) => ({ type: "ellipse", x, y, width: 100, height: 60, strokeColor: "#666", backgroundColor: "#f0fff0", fillStyle: "solid", label: { text: label || "PostgreSQL" } });

团队成员只需调用函数即可插入标准化数据库图标，避免每个人“自由发挥”。

2. 使用 ID 管理关联性

为关键节点设置固定 ID：

{ "id": "svc-payment", "type": "rectangle", ... }

便于后续脚本查找、高亮或做影响分析。

3. 控制单图复杂度

建议单幅图不超过 10–15 个主节点。太复杂的拓扑可用模块化方式拆分，比如按领域、按层级分别生成，再拼接展示。

4. 借助外部布局引擎

Excalidraw 本身不提供自动布局，但可以在生成 JSON 前使用 dagre 或 Graphviz 计算坐标，确保生成的图清晰易读。

例如：

const g = new dagre.graphlib.Graph(); g.setGraph({ rankdir: "LR" }); g.setDefaultEdgeLabel(() => ({})); nodes.forEach(node => g.setNode(node.id, { width: 120, height: 60 })); edges.forEach(edge => g.setEdge(edge.from, edge.to)); dagre.layout(g); // 将 layout 后的 x/y 注入 Excalidraw 元素 elements.forEach(el => { const node = g.node(el.id); if (node) { el.x = node.x - el.width / 2; el.y = node.y - el.height / 2; } });

这样即使批量生成几十个服务的调用链路，也不会乱成一团。

5. 注意安全边界

若集成 LLM 解析敏感架构信息，务必做好上下文隔离，避免将内部系统细节发送到第三方 API。推荐使用本地部署模型（如 Llama 3）处理核心业务逻辑。

它不只是工具，更是一种思维方式

Excalidraw 的这次升级，看似只是增加了一个 CLI 工具，实则推动了一种新的技术表达范式：图形即代码（Diagrams as Code）。

正如当年“基础设施即代码”（IaC）让我们告别手动配置服务器，“文档即代码”（Doc as Code）让知识沉淀变得可持续，如今“图表即代码”也在填补最后一块拼图。

未来，我们或许会看到更多场景被重塑：

• 技术方案评审中，PR 不仅包含代码变更，还自动生成前后对比架构图；
• 故障复盘报告里，时间线图由日志解析自动生成；
• 新员工入职手册中的系统概览，每天凌晨自动同步最新状态；

这些不再是理想主义的设想，而是已经在部分领先团队中落地的现实。

写在最后

Excalidraw 并非第一个支持代码生成图形的工具，但它可能是第一个真正做到“开发者友好”与“视觉亲和力”兼备的产品。它没有追求大而全，而是牢牢抓住“技术人画技术图”这一核心需求，用最朴素的方式解决了最普遍的痛点。

它的成功提醒我们：有时候，创新不在于造得多复杂，而在于是否真正理解用户的挣扎，并给出恰到好处的解法。

下次当你又要打开绘图软件时，不妨停下来想一想：这张图能不能用代码写出来？如果能，也许你离高效、准确、可持续的技术表达，只差一次npm install的距离。