Excalidraw图形批量导出脚本

最新推荐文章于 2025-12-20 16:55:34 发布

原创最新推荐文章于 2025-12-20 16:55:34 发布 · 432 阅读

17 ·

CC 4.0 BY-SA版权

文章标签：

#Excalidraw # 批量导出 # 无头浏览器

部署运行你感兴趣的模型镜像

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/excalidraw React 组件，在自定义服务中进行渲染。

这种方式的优势在于可控性强。你可以构建一个专用的“导出服务器”，接收 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);