开发者必备：Excalidraw集成Markdown的工作流方案

开发者必备：Excalidraw集成Markdown的工作流方案

在技术团队的日常协作中，你是否经历过这样的场景？写完一段微服务架构描述后，同事反馈：“这段文字太抽象了，能不能画个图？”于是你不得不停下思路，打开 Figma 或 Draw.io，重新梳理逻辑、拖拽组件、调整样式……等图画好了，文档早已失去了写作时的流畅感。

这种“图文割裂”的困境，在敏捷开发中尤为常见。而如今，一种新的工作范式正在悄然兴起：在 Markdown 里直接画画——通过将手绘风格白板工具 Excalidraw 深度融入技术文档流程，开发者终于可以实现“边写边画、所见即所得”的一体化表达。

这不仅是一个工具链的升级，更是一种思维方式的转变：从“先写后补图”到“图文同步演进”，让技术思维在文字与图形之间自由流动。

为什么是 Excalidraw？

市面上的绘图工具并不少，但大多数都偏向设计人员或产品经理，对开发者而言往往“太重”。Visio 功能复杂，Figma 学习成本高，而且它们生成的通常是二进制文件，难以纳入 Git 版本控制。相比之下，Excalidraw 的出现像是一股清流。

它是一款开源的虚拟白板应用，主打“草图感”而非“完美渲染”。它的界面极简，几乎没有学习门槛，点开就能画。更重要的是，它的所有图形数据都以JSON 格式存储，这意味着：

• 图表可以被 Git 追踪，每次修改都能清晰看到差异；
• 可以用代码生成图表，也可以用 AI 解析图表内容；
• 能轻松嵌入各种基于文本的系统，比如 Obsidian、VS Code、Docusaurus 等。

换句话说，Excalidraw 把“画图”这件事，变成了和写代码一样的工程化操作。

它是怎么工作的？

Excalidraw 本身运行在浏览器中，基于 React 和 Canvas 构建。当你画一个矩形或连线时，其实是在操作一个结构化的 JSON 对象。例如，一个简单的矩形元素可能长这样：

{ "type": "rectangle", "x": 100, "y": 200, "width": 160, "height": 80, "strokeStyle": "hachure", "backgroundColor": "#fff" }

这些数据保存为.excalidraw文件，本质上就是一个文本文件。正是这个特性，让它能够无缝接入 Markdown 工作流。

当我们在 Obsidian 或其他支持插件的编辑器中输入：

![[architecture.excalidraw]]

系统并不会把它当作普通图片处理，而是由 Excalidraw 插件拦截请求，加载对应的 JSON 数据，并在 Canvas 上重绘出手绘风格的图形。双击即可进入编辑模式，修改后自动保存回原文件。

整个过程完全发生在本地，无需联网上传，既高效又安全。最终输出时，还能导出为 PNG、SVG 甚至 React 组件，灵活适配不同发布场景。

实时协作与 AI 辅助：不只是个人工具

虽然 Excalidraw 非常适合个人记录灵感，但它也原生支持多人实时协作。多个开发者可以同时在一个白板上讨论架构设计，每个人的笔触都会实时同步，类似 Google Docs 的体验。

背后的技术依赖于 WebSocket 和 CRDT（无冲突复制数据类型）协议，确保并发编辑不会产生冲突。这对于远程团队来说尤其有价值——不再需要靠截图+文字说明来沟通，而是真正实现了“共绘一张图”。

更进一步，Excalidraw 还集成了 AI 辅助绘图能力。你可以输入一句自然语言指令，比如：

“画一个用户登录的前后端交互流程图”

AI 就会自动生成一个初步框架，包含前端、网关、认证服务、数据库等基本模块和连接关系。虽然目前还不能替代人工精修，但对于快速搭建草图、启发思路已经足够有用。

关键在于，AI 生成的是结构化 JSON，而不是一张死图。你可以继续编辑、调整布局、增删元素，就像处理任何其他代码一样。

如何集成进你的 Markdown 流程？

不同的文档平台有不同的集成方式，但核心思路一致：扩展 Markdown 的解析能力，使其能识别并渲染.excalidraw文件。

在 Obsidian 中使用（客户端插件模式）

Obsidian 是目前最成熟的集成环境之一。只需安装社区维护的Excalidraw Plugin，就可以立即开始使用。

步骤非常简单：
1. 创建api-flow.excalidraw文件；
2. 在design.md中引用：
```markdown
## 接口调用流程

![[api-flow.excalidraw]]
```
3. 双击嵌入区域即可内联编辑，保存后自动更新。

由于 Obsidian 本身基于文件系统，所有.md和.excalidraw文件都存放在本地，天然适合 Git 管理。你可以像提交代码一样提交设计图变更，PR 中也能清楚看到谁改了哪条线。

在 Docusaurus/VitePress 中构建静态站点（构建时预处理模式）

如果你的团队使用静态站点生成器发布技术文档，也可以通过构建阶段转换实现集成。

这里的关键是使用@excalidraw/excalidraw-node这个 Node.js 库，在 CI/CD 流水线中批量将.excalidraw文件转为 SVG 或 PNG。

下面是一个自定义 Remark 插件的实现示例：

// remark-excalidraw.js const visit = require("unist-util-visit"); const fs = require("fs"); const path = require("path"); const { renderToSVG } = require("@excalidraw/excalidraw-node"); function remarkExcalidraw() { return async (tree, file) => { visit(tree, "image", async (node) => { if (node.url.endsWith(".excalidraw")) { const fullPath = path.join(path.dirname(file.path), node.url); const data = JSON.parse(fs.readFileSync(fullPath, "utf8")); const svgString = await renderToSVG({ elements: data.elements, appState: { exportBackground: true }, }); const base64Svg = Buffer.from(svgString).toString("base64"); node.type = "html"; node.value = `<img src="data:image/svg+xml;base64,${base64Svg}" alt="${node.alt}" />`; } }); }; } module.exports = remarkExcalidraw;

这个插件会在构建时扫描 Markdown 的 AST（抽象语法树），发现.excalidraw引用后，就调用服务端渲染 API 生成 SVG，并以内联 Base64 形式插入 HTML。最终产出的页面无需额外资源加载，非常适合部署在内网或离线环境。

真实工作流：一名后端工程师的一天

让我们看一个具体案例。假设你是一名后端工程师，正在设计一个新的订单履约系统。

1. 你在项目根目录创建docs/design.md和sequence.excalidraw；
2. 写下第一段描述：
   ```markdown
   ## 订单状态流转

用户下单后，系统需依次触发库存锁定、支付确认、物流调度三个阶段：

![[sequence.excalidraw]]
```
3. 双击图表区域，启动 Excalidraw 编辑器，快速画出三个服务模块及事件流向；
4. 提交到 GitLab，发起 Merge Request；
5. 团队成员在 MR 页面直接查看嵌入的图表，评论某条连线逻辑有误；
6. 你本地修改后再次提交，CI 自动构建文档并部署预览页；
7. 最终合并主干，文档与代码一同归档。

整个过程中，没有跳出编辑器，没有手动导出图片，也没有“最新版在哪”的困惑。图文始终同步，版本清晰可追溯。

它解决了哪些老问题？

特别是最后一点，很多团队曾尝试用截图贴图的方式解决，结果导致文档臃肿、更新滞后。而现在，一张 SVG 不仅轻量，还能随主题切换亮暗模式，真正做到了“一次绘制，多端可用”。

工程实践建议

要在团队中顺利落地这套工作流，除了技术选型，还需要一些配套规范：

✅ 拆分大图，保持模块化

避免单个.excalidraw文件过大。建议按功能拆分，如auth-flow.excalidraw、payment-sequence.excalidraw，便于复用和维护。

✅ 统一命名约定

采用清晰的命名规则，例如：[模块]-[类型].excalidraw，如user-onboarding-wireframe.excalidraw，方便检索和组织。

✅ 结合 AI 提效，但不盲信

AI 生成的初稿可以节省起始时间，但必须人工校验逻辑正确性。尤其涉及业务规则、异常路径时，切忌“照单全收”。

✅ 设置构建兜底机制

在 CI 中加入检查脚本，确保所有.excalidraw文件都能成功转为静态图像。若转换失败，则阻断发布，防止文档缺失。

✅ 重视备份与兼容性

虽然格式开放，但仍建议定期归档重要图表。未来若 Excalidraw 协议升级，旧版文件可能存在解析风险。

这不仅仅是个工具

Excalidraw 与 Markdown 的结合，表面看是提升了绘图效率，实则推动了一种更深层次的工程文化变革。

在过去，“文档”常常被视为开发完成后的补充动作，甚至是负担。而今天，随着“文档即代码”（Documentation as Code）理念的普及，越来越多团队意识到：高质量的技术文档本身就是系统设计的一部分。

当你能在写代码的同时随手画出调用链路，在写注释时顺手标注状态机转换，那些原本模糊的设计决策就会变得具体、可讨论、可验证。久而久之，团队的知识沉淀不再是散落各处的截图和笔记，而是一套不断演进的可视化资产库。

这正是 DevOps、SRE、Tech Lead 等角色越来越重视文档能力的原因——它不仅是传递信息的载体，更是提升系统可维护性的基础设施。

写在最后

技术工具总是在变，但有些原则始终成立：越贴近思维流动的工具，越能释放创造力；越易于协作和审查的流程，越能构建可靠系统。

Excalidraw 与 Markdown 的融合，正是这样一个顺应开发者心智模型的设计。它不追求炫酷的视觉效果，也不堆砌复杂功能，而是专注于一件事：让你想到什么，就能立刻表达出来。

在这个意义上，它不只是一个绘图插件，更像是现代开发者手中的一支数字钢笔——简单、直接、有力。