Excalidraw图形批量导出脚本
在技术文档、产品原型和团队协作日益依赖可视化表达的今天，如何高效管理设计资产成了一个现实挑战。开发者们喜欢用 Excalidraw 绘制具有“手绘感”的架构图或流程图——它轻量、直观、风格独特。但问题也随之而来：每次更新图表后，手动打开文件、截图、保存、重命名……这一连串操作不仅繁琐，还容易出错，尤其当项目中包含几十甚至上百张图时，效率瓶颈立刻显现。
有没有可能像编译代码一样，“一键生成”所有图表图像？答案是肯定的。通过自动化脚本结合无头浏览器技术，我们可以实现 Excalidraw 图形的批量导出，将原本耗时数小时的手工劳动压缩到几分钟内完成，且输出格式统一、可追溯、可集成进 CI/CD 流程。
这不仅是提效工具，更是一种思维方式的转变——把图形当作代码来管理。
文件结构解析：从.excalidraw到 JSON 的可编程世界
Excalidraw 的本地保存文件（.excalidraw）其实是一个标准的 JSON 文本文件。这意味着你完全可以用 VS Code 打开它，看到里面记录了画布上每一个元素的位置、类型、样式和连接关系。这种设计看似简单，实则非常聪明：它让图形具备了“可读性”和“可版本控制”的能力。
比如，当你在一个 Git 仓库中提交一个.excalidraw文件时，下次修改后再提交，你可以清晰地看到哪条线被移动了、哪个文本框内容变了——这是传统 PNG 或 PDF 附件永远做不到的。
这个 JSON 结构主要包括几个核心字段：
version：文件格式版本号，不同版本的 Excalidraw 可能存在兼容性差异；source：来源 URL，用于标识该文件来自哪个实例；elements：最关键的部分，数组形式存储所有图形元素，如矩形、线条、箭头、文本等；appState：视图状态，包括缩放比例、滚动位置等。
值得注意的是，这些数据只是“描述”了图形，并不包含渲染后的图像本身。也就是说，JSON 里没有像素，也没有矢量路径。“手绘抖动”效果是在前端 Canvas 渲染阶段动态生成的，属于视觉表现层，而非数据层。因此，仅靠解析 JSON 是无法直接生成图片的——我们必须回到浏览器环境，让它真正“画出来”。
这也引出了下一个关键环节：如何在无人工干预的情况下完成这个“绘制”过程？
无头渲染：让浏览器自己画画
既然需要真实渲染，那就得有 DOM 和 Canvas 环境。最自然的想法是：模拟用户操作——打开网页、加载数据、等待渲染、截取画面。只不过这一切都发生在没有界面的“后台”。
这就是Headless Browser（无头浏览器）的用武之地。借助 Puppeteer 或 Playwright 这类 Node.js 工具，我们可以启动一个隐藏的 Chromium 实例，自动执行整个导出流程。
典型的工作流如下：
- 启动无头浏览器；
- 访问本地运行的 Excalidraw 页面（例如
http://localhost:3000）； - 将
.excalidraw文件中的 JSON 数据注入到页面的localStorage中； - 刷新页面，触发 Excalidraw 自动恢复会话；
- 等待画布渲染完成；
- 调用
canvas.toDataURL()获取图像 Base64 数据； - 保存为 PNG 或转换为 SVG；
- 关闭页面，处理下一个文件。
整个过程就像是有个“虚拟用户”在背后默默帮你点鼠标、按回车。
为了保证输出质量，有几个参数特别关键：
| 参数 | 推荐值 | 说明 |
|---|---|---|
viewport | 1920x1080 | 模拟高分辨率屏幕，避免布局错乱 |
deviceScaleFactor | 2 | 支持 Retina 高清截图 |
timeout | 10s | 设置合理超时，防止卡死 |
omitBackground | false | 保留网格背景，保持原貌 |
实际编码中，还需要注意一些细节。比如不能立即截图，因为 React 渲染和动画可能存在延迟，必须加个setTimeout或监听特定元素出现后再执行导出。否则很可能抓到一个空白画布。
下面是一段经过优化的核心脚本：
const puppeteer = require('puppeteer'); const fs = require('fs'); const path = require('path'); async function exportDiagram(inputPath, outputPath) { const browser = await puppeteer.launch({ headless: true }); const page = await browser.newPage(); await page.setViewport({ width: 1920, height: 1080, deviceScaleFactor: 2, }); await page.goto('http://localhost:3000', { waitUntil: 'networkidle0' }); const jsonContent = fs.readFileSync(inputPath, 'utf-8'); const data = JSON.parse(jsonContent); await page.evaluate((data) => { localStorage.setItem( 'excalidraw-state', JSON.stringify({ ...JSON.parse(localStorage.getItem('excalidraw-state') || '{}'), initialData: data, }) ); }, data); await page.reload({ waitUntil: 'networkidle0' }); const imageBuffer = await page.evaluate(() => { return new Promise((resolve) => { setTimeout(() => { const canvas = document.querySelector('#app canvas'); if (canvas) { resolve(canvas.toDataURL('image/png')); } else { resolve(null); } }, 1000); }); }); if (imageBuffer) { const base64Data = imageBuffer.replace(/^data:image\/png;base64,/, ''); fs.writeFileSync(outputPath, base64Data, 'base64'); console.log(`✅ 导出成功: ${outputPath}`); } else { console.error(`❌ 导出失败: ${inputPath}`); } await browser.close(); }这段代码虽然简洁，但在生产环境中仍需补充错误重试、并发控制和日志追踪机制。比如同时开启太多浏览器实例可能导致内存溢出，建议使用p-limit控制最大并发数（如 3 个）。
更进一步：组件化集成与服务端渲染
如果你希望摆脱对完整 Web 应用的依赖，还可以选择更底层的方式——直接使用官方提供的@excalidraw/excalidrawReact 组件，在自定义服务中进行渲染。
这种方式的优势在于可控性强。你可以构建一个专用的“导出服务器”，接收 JSON 数据，动态生成 HTML 页面，再通过无头浏览器访问并截图。由于整个流程由你掌控，可以禁用不必要的功能（如协作、AI 插件），提升稳定性和性能。
例如，利用 SSR（服务端渲染）生成初始页面：
import React from 'react'; import { renderToString } from 'react-dom/server'; import { Excalidraw } from '@excalidraw/excalidraw'; function generateHtml(initialData) { const appString = renderToString( <Excalidraw initialData={initialData} viewModeEnabled={true} /> ); return ` <!DOCTYPE html> <html> <body style="margin:0;height:100vh;"> <div id="root">${appString}</div> <script> window.__EXCALIDRAW__DATA__ = ${JSON.stringify(initialData)}; </script> </body> </html> `; }然后让 Puppeteer 加载这个临时页面，等待组件挂载后调用其导出方法。甚至可以直接调用exportToSvg()函数获取 SVG 字符串，绕过 Canvas 截图步骤，获得更高质量的矢量输出。
当然，这条路也有代价：你需要维护一个基于 Express + Webpack/React 的服务环境，部署复杂度上升，适合长期使用的团队级解决方案，而不适用于个人快速脚本。
实际应用场景：让图表融入工程流程
设想这样一个场景：你的团队正在维护一份技术文档网站，使用 Docusaurus 构建，所有架构图都用 Excalidraw 绘制并存放在docs/diagrams/目录下。每当有人更新了一个.excalidraw文件，CI 流水线就会自动触发：
- 拉取最新代码；
- 运行批量导出脚本，生成对应的 PNG 图像；
- 将图像复制到
static/img/目录； - 重新构建文档站点；
- 发布更新后的页面。
最终结果是：读者看到的是清晰的图片，而作者只需关心源文件的编辑。源图一体，版本一致，无需额外沟通。
这种模式已经在不少开源项目和技术博客中落地。更重要的是，它改变了我们对待“图表”的态度——不再是孤立的附件，而是可编程的内容资产。
此外，还可以根据需求灵活调整输出策略：
- 输出 PNG：适合嵌入 Markdown、PPT、邮件，通用性强；
- 输出 SVG：适合打印出版、高清展示，支持无限缩放；
- 添加水印或边框：用于区分测试版与正式版；
- 按标签筛选导出：只导出带有
export:true标记的图表。
甚至可以结合 Git Hooks，在本地 commit 前自动同步导出最新图像，彻底杜绝“源文件更新了但图片没换”的尴尬。
设计考量与最佳实践
在实践中，有几个关键点值得特别关注：
并发与资源管理
Puppeteer 虽强大，但每个浏览器实例都会消耗大量内存。处理上百个文件时，应避免一次性启动过多页面。推荐使用任务队列控制并发数量，例如：
const PLimit = require('p-limit'); const limit = PLimit(3); // 最多3个并发 const promises = files.map(file => limit(() => exportDiagram(file.input, file.output)) ); await Promise.all(promises);错误处理与重试
网络波动、渲染失败、Canvas 未就绪等问题时有发生。建议对关键步骤添加重试机制（如最多重试 2 次），并记录失败文件路径以便后续排查。
安全与隐私
若在公共 CI 环境（如 GitHub Actions）中运行，需警惕敏感信息泄露。建议：
- 对包含机密内容的图表进行脱敏处理；
- 使用加密存储或私有 Runner；
- 导出完成后自动清理临时文件。
格式选择权衡
| 格式 | 优点 | 缺点 |
|---|---|---|
| PNG | 兼容性好，易于查看 | 不可缩放，文件体积大 |
| SVG | 矢量无损，搜索友好 | 渲染兼容性差，字体可能丢失 |
建议优先使用 PNG 保证稳定性；若追求高质量出版，可双路导出。
写在最后：从脚本到范式
这个批量导出脚本本身并不复杂，但它背后体现的是一种现代工程思维：将非结构化内容纳入自动化流程。
过去，图表是“做完就扔”的一次性产物；现在，它可以像代码一样被版本化、测试、审查和发布。这种转变带来的不仅仅是效率提升，更是协作方式的进化。
未来，这条路径还能走得更远：
- 结合 AI 工具，自动生成初稿图表并批量导出；
- 利用 OCR 或语义分析，实现图表内容检索；
- 搭建私有 Excalidraw Server，支持权限管理和 API 访问。
也许有一天，我们会说：“这张图已经过 CI 验证，可以发布。”
自动化之路始于微小脚本，终将成就高效协作的新范式。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
