一、.excalidraw是什么格式的文件？

.excalidraw是Excalidraw的原生文件格式。

Excalidraw 是一个开源的在线虚拟白板工具，以手绘风格的绘图著称。它的.excalidraw文件本质上是一个JSON 文本文件，里面记录了画布上所有元素的完整信息。

1.1 文件内部结构

用任何文本编辑器（如 VS Code、记事本）打开.excalidraw文件，可以看到结构化的 JSON 数据，包含：

1.2 核心特点

• 纯文本格式：本质是 JSON，可读性强，可用任何文本编辑器打开
• 可版本控制：完美适配 Git，diff 时能清晰看到图形元素的增删改
• 无损编辑：保存了完整的绘图信息，随时可重新导入继续编辑
• 跨平台兼容：在浏览器、VS Code、桌面端均可打开

二、在 VS Code 中预览与编辑

2.1 安装插件

在 VS Code 扩展商店搜索并安装：

Excalidraw Editor—pomdtr.excalidraw-editor

安装完成后，无需跳转到浏览器，直接在资源管理器中双击.excalidraw文件，VS Code 就会以可视化编辑器打开。

2.2 工作原理

该插件将 Excalidraw 封装在 VS Code 的WebView中运行：

• 你在画布上的每一次操作，都会通过postMessage将变更后的 JSON 状态同步回写到本地文件
• 文件始终是最新的，保存时自动写入磁盘
• Git 可以正常追踪变更，甚至能在 diff 中看到具体哪些图形元素被修改了

2.3 常用操作

三、生成分享文档的四种方式

3.1 导出为图片（最通用）

在 VS Code 的 Excalidraw 编辑器中，点击左上角☰ 菜单 → Export：

3.2 嵌入 Markdown 文档

对于技术文档和 README，推荐以下工作流：

项目目录 ├── docs/ │ ├── diagrams/ │ │ ├── architecture.excalidraw ← 源文件（Git 追踪） │ │ └── architecture.png ← 导出图片（供文档引用） │ └── README.md

在 Markdown 中引用：

## 系统架构 ![系统架构图](docs/diagrams/architecture.png)

进阶技巧：配合 Git Hooks 或 CI/CD，在提交前自动将.excalidraw导出为 PNG，确保文档中的图片始终与源文件同步。

3.3 生成在线分享链接

如果希望他人能在线查看或协作编辑：

1. 在编辑器中点击☰ 菜单 → Export → Share
2. 或访问 excalidraw.com，将.excalidraw文件内容（JSON）粘贴进去
3. 生成公开链接，对方打开即可查看和编辑
4. 链接支持实时协作，多人同时编辑同一张图

3.4 导出为可交互网页（开发者方案）

如果你是前端开发者，可以将 Excalidraw 集成到自己的项目中：

npminstall@excalidraw/excalidraw

然后在 React 应用中引入组件，加载.excalidraw的 JSON 数据，实现网页内嵌的交互式白板。

四、推荐工作流与最佳实践

4.1 团队协作用.excalidraw，分享用.png/.svg

4.2 让设计图成为"活文档"

1. 源文件入仓：所有.excalidraw文件纳入 Git 版本控制
2. 自动导出：配置 CI/CD 或 Git Hooks，提交时自动导出 PNG/SVG
3. 文档引用图片：README 和文档中引用导出的静态图片
4. 变更可追溯：通过 Git diff 查看图形设计的历史变更

这套工作流让设计图真正成为了"活文档"——既能随时回溯历史版本，又能保证对外分享的文档始终是最新的。

五、快速参考