Excalidraw导出格式全解析：PNG、SVG与JSON的技术实践
在技术团队频繁绘制架构图、流程草图和界面原型的今天，一个常见的痛点浮现出来：如何让一张随手画出的手绘风格图表，既能嵌入文档清晰展示，又能长期维护、多人协作甚至被代码管理？这正是 Excalidraw 解决的核心问题。
作为一款开源的手绘风虚拟白板工具，Excalidraw 不仅以极简设计和自然笔触赢得开发者青睐，更通过其对多种导出格式的深度支持，打通了从“灵感闪现”到“知识沉淀”的完整链路。而其中最关键的环节，就是它提供的三种导出方式——PNG、SVG 和 JSON。它们看似只是文件后缀不同，实则承载着截然不同的工程意图和技术能力。
当你完成一幅系统拓扑图时，也许第一反应是“导出成图片发给同事”。但接下来的问题接踵而至：
- 图片放大后模糊不清怎么办？
- 别人想修改其中一个模块名称却无法编辑？
- 架构变更后如何追溯历史版本？
这些问题的答案，其实就藏在你选择哪种格式导出之中。
PNG：为“展示”而生的静态图像
如果你需要把图表放进 PPT 做汇报、贴进 Markdown 写周报，或者上传到 Wiki 页面作为参考资料，那PNG 是最直接的选择。
它的本质是位图——将画布内容光栅化为像素阵列。Excalidraw 在导出时会创建一个临时的<canvas>元素，按设定的缩放倍率（如 2x 或 4x）渲染所有图形和文字，再调用canvas.toDataURL('image/png')生成 base64 数据，最终触发浏览器下载。
function exportToPNG(elements, appState) { const scale = appState.exportScale || 2; const { width, height } = getVisibleBounds(elements); const tempCanvas = document.createElement('canvas'); tempCanvas.width = width * scale; tempCanvas.height = height * scale; const ctx = tempCanvas.getContext('2d'); ctx.scale(scale, scale); renderScene(ctx, elements, appState); const dataURL = tempCanvas.toDataURL('image/png'); triggerDownload(dataURL, 'diagram.png'); }这段逻辑轻量且兼容性好，几乎能在所有现代浏览器中稳定运行。更重要的是，PNG 支持透明背景和无损压缩，特别适合线条清晰、包含文本的技术图表。相比 JPEG，它不会产生压缩伪影；相比 GIF，它支持更多颜色和 alpha 通道。
但代价也很明显：一旦导出为 PNG，你就失去了编辑能力。你想改个标签？只能回到原图重新导出。而且高分辨率下文件体积可能膨胀，影响网页加载性能。因此，PNG 的定位非常明确——用于最终成果的静态分发，而非过程协作或长期演进。
SVG：保留结构的矢量表达
如果希望图表既高清可缩放，又保留一定的可读性和可修改性，那就该轮到SVG 登场了。
SVG 是基于 XML 的矢量图形格式。Excalidraw 导出时，并非简单截图，而是将每个元素转化为对应的 SVG 标签：矩形变成<rect>，自由线条转为<path>，文本则是<text>，并注入内联样式确保跨平台显示一致。
function generateSVG(elements, dimensions) { let svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${dimensions.width}" height="${dimensions.height}" viewBox="0 0 ${dimensions.width} ${dimensions.height}"> <style>.shape { stroke: #000; fill: none; }</style>`; elements.forEach(el => { if (el.type === 'rectangle') { svg += `<rect x="${el.x}" y="${el.y}" width="${el.width}" height="${el.height}" class="shape"/>`; } else if (el.type === 'text') { svg += `<text x="${el.x}" y="${el.y}" font-size="${el.fontSize}">${el.text}</text>`; } }); return svg + '</svg>'; }这个 XML 结构不仅能在浏览器中无限缩放而不失真，还能用文本编辑器打开修改。比如你可以手动调整某个坐标的数值，或者批量替换字体名称。由于是纯文本，SVG 天然适合纳入 Git 管理，diff 工具能清楚告诉你哪根线被移动了、哪个标签被重命名。
这也让它成为官网文档、技术博客的理想选择。想象一下，你的 API 流程图随着页面响应式布局自动适配屏幕大小，点击还能高亮交互区域——这些都建立在 SVG 的结构化基础之上。
当然也有注意事项：若使用了外部字体或嵌入图像，在离线环境下可能无法正确渲染；此外，未经净化的 SVG 可能携带 JavaScript 片段，存在 XSS 风险，服务端引入前应做安全过滤。
JSON：不只是数据，而是“状态快照”
如果说 PNG 是“照片”，SVG 是“图纸”，那么JSON 就是整套施工方案+现场记录。
当你导出.excalidraw文件时，Excalidraw 实际上保存的是整个画布的完整状态：
{ "type": "excalidraw", "version": 2, "elements": [ { "id": "A1", "type": "rectangle", "x": 100, "y": 50, "width": 160, "height": 80, "strokeColor": "#000000", "fillStyle": "hachure" }, { "id": "T1", "type": "text", "text": "Server", "fontSize": 20 } ], "appState": { "zoom": { "value": 1 }, "currentItemStrokeColor": "#000000" } }注意这里的appState——它不仅记录图形本身，还包括当前缩放比例、选中工具、锁定状态等用户交互信息。这意味着导入时可以真正做到“所见即所得”，连你上次停留在哪个视图都一并还原。
这种全量状态的序列化带来了惊人的工程可能性：
- 模板复用：预置微服务架构模板，新项目一键加载；
- CI/CD 集成：Git 提交新的 JSON 文件后，自动化脚本自动生成 PNG 预览图并发布到内部站点；
- AI 协作闭环：输入“生成订单系统流程图”，AI 返回标准 JSON 结构，前端直接渲染，后续仍可人工调整；
- 版本可追溯：每次架构变更提交 PR，Reviewer 能清晰看到元素增删、连接关系变化。
可以说，JSON 是 Excalidraw 从绘图工具跃迁为协作中枢的关键载体。它让图表不再是孤立产物，而是可编程、可集成、可持续演进的知识资产。
在一个典型的 DevOps 团队工作流中，这三种格式往往协同运作：
- 成员在 Excalidraw 中协作绘制服务拓扑；
- 使用 AI 插件快速生成初稿；
- 完成后分别导出：
- PNG 插入周报演示文稿；
- SVG 嵌入在线文档供查阅；
- JSON 提交至docs/architecture/目录，纳入 Git 版本控制； - 后续任何变更都通过 Pull Request 更新 JSON 文件，触发自动预览构建。
这样的流程解决了多个传统痛点：
| 问题 | 解法 |
|---|---|
| 图表难以复用 | JSON 模板库统一管理 |
| 文档模糊不清 | SVG 替代低质截图 |
| 协作冲突频发 | 实时协同 + Git 分支机制 |
| AI 输出不可编辑 | 输出结构化 JSON 而非图片 |
更重要的是，它建立起一种新的设计哲学：设计即代码。就像我们用 Markdown 写文档、YAML 定义部署配置一样，现在也可以用 JSON 来“编码”系统架构。这种可读、可 diff、可自动化处理的特性，正是工程师思维的最佳体现。
当然，每种格式都有其边界。分享 JSON 前需注意隐私审查，避免泄露未公开的设计草稿；不同版本 Excalidraw 的 schema 可能不兼容，升级时需做好迁移；手动编辑 JSON 也容易因语法错误导致无法加载，建议配合校验工具使用。
但从整体来看，Excalidraw 对三种导出格式的差异化设计，精准覆盖了从个人创作到团队协作、从即时沟通到长期知识管理的全场景需求。它没有试图用单一格式解决所有问题，而是清晰划分职责：PNG 面向展示，SVG 面向呈现，JSON 面向演化。
这种架构思路本身，或许比工具本身更值得借鉴。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
