当前位置：首页 > news >正文

Excalidraw贡献者入门：如何提交第一个PR？

news 2026/5/12 20:45:58

Excalidraw贡献者入门：如何提交第一个PR？

在现代软件开发中，可视化协作工具早已不再是可有可无的“锦上添花”，而是团队沟通的核心载体。尤其在远程办公常态化、敏捷迭代加速的背景下，一个轻量、灵活且富有表现力的白板工具，往往能决定一次技术讨论是高效推进还是陷入混乱。

Excalidraw 正是在这种需求下脱颖而出——它用极简的手绘风格打破了传统图表工具的冰冷感，又通过强大的可扩展性和实时协作能力支撑起严肃的工程设计场景。更关键的是，它是完全开源的。这意味着你不仅可以免费使用，还能真正参与它的进化过程。

如果你一直想踏入开源世界却不知从何开始，Excalidraw 可能就是那个最理想的起点：代码结构清晰、社区友好、文档完善，而且对新手 PR 的接受度非常高。本文不讲空泛的理念，而是带你一步步走完“从 fork 到合并”的完整路径，让你真正提交出人生第一个被接纳的 Pull Request。

从零开始：搭建开发环境与理解协作流程

很多人卡在第一步，并不是因为技术难，而是被流程绕晕了。别担心，我们跳过那些教科书式的定义，直接进入实战节奏。

假设你现在打开浏览器，访问 https://github.com/excalidraw/excalidraw，看到这个项目已经有超过 3 万个 star，但你心里想的是：“我能为它做点什么？”

答案是：先让代码在你本地跑起来。

第一步：Fork + 克隆

点击右上角的 “Fork” 按钮，将仓库复制到你的 GitHub 账号下。这是所有开源贡献的第一步——你不能直接往主仓库提交代码，但你可以拥有自己的副本。

接着，在终端执行：

git clone https://github.com/your-username/excalidraw.git cd excalidraw

别忘了添加上游仓库，这样后续才能同步最新改动：

git remote add upstream https://github.com/excalidraw/excalidraw.git

这一步看似简单，但非常重要。很多新人提交 PR 后发现冲突一堆，原因就是没及时拉取主分支更新。加了upstream，以后只需要运行：

git fetch upstream git rebase upstream/main

就能保持你的分支始终基于最新的代码基础。

第二步：安装依赖并启动

Excalidraw 使用 Vite 构建，所以整个启动流程非常快：

npm install npm run dev

几秒钟后，浏览器自动打开http://localhost:3000，你就拥有了一个和线上版本几乎一模一样的本地开发环境。试着画几个形状，导出 JSON 文件，甚至试试暗色模式切换——一切功能都可用。

这时候你可以停下来问自己一个问题：如果我想改点什么，比如修复某个按钮点击没反应的问题，或者加个新功能，该从哪下手？

答案藏在项目结构里。

理解项目架构：你在跟谁打交道？

打开项目根目录，你会看到类似这样的结构：

src/ ├── components/ # UI 组件（按钮、工具栏等） ├── elements/ # 图形元素逻辑（矩形、箭头、文本等） ├── packages/ # 核心库 @excalidraw/excalidraw ├── scenes/ # 示例场景数据 ├── utils/ # 工具函数 └── App.tsx # 主应用入口

整个应用是一个典型的 React + TypeScript 单页应用，但有几个关键技术选型值得特别注意：

Vite：构建速度极快，热更新几乎无延迟，极大提升开发体验。
Tailwind CSS：没有写一行原生 CSS，所有样式都通过 class 名组合完成，保证视觉一致性的同时避免样式污染。
Zustand：轻量级状态管理，比 Redux 更简洁，适合中小型应用的状态控制。
Canvas 渲染：图形绘制不依赖 SVG，而是基于原生 Canvas API，性能更好，尤其适合大量元素渲染。

举个例子，当你拖动一个矩形时，背后发生了什么？

鼠标事件被捕获；
当前元素坐标更新，写入 Zustand store；
Canvas 被重新绘制，反映最新位置；
撤销栈记录这次操作，支持 Ctrl+Z 回退。

所有这些状态都是可序列化的，所以你可以导出.excalidraw文件，发给同事，他打开就能看到完全相同的画面。

这也意味着，任何功能修改，本质上都是在调整“状态如何变化”以及“UI 如何响应”。

写你的第一行代码：一个小而完整的功能示例

现在我们来模拟一个真实场景：你想为 Excalidraw 添加一个“AI 生成图表”功能，用户输入一段文字描述，系统自动生成对应的流程图。

虽然这听起来像大功能，但我们只关注最小可行实现（MVP）：一个输入框 + 一个按钮 + 调用 AI 接口返回图形元素。

1. 创建组件

在src/components/下新建AIInput.tsx：

import React, { useState } from "react"; import { updateScene } from "@excalidraw/excalidraw"; const AIInput = ({ appId }: { appId: string }) => { const [prompt, setPrompt] = useState(""); const [loading, setLoading] = useState(false); const generateDiagram = async () => { if (!prompt.trim()) return; setLoading(true); try { const response = await fetch("/api/generate", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt }), }); const elements = await response.json(); updateScene({ elements }); // 插入生成的图形 } catch (err) { alert("生成失败，请检查网络或输入内容"); } finally { setLoading(false); } }; return ( <div className="flex gap-2 p-2 border-b bg-gray-50"> <input type="text" value={prompt} onChange={(e) => setPrompt(e.target.value)} placeholder="描述你想画的内容，例如：用户登录流程" className="flex-1 px-3 py-2 border rounded text-sm" disabled={loading} /> <button onClick={generateDiagram} disabled={loading} className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50" > {loading ? "生成中…" : "AI生成"} </button> </div> ); }; export default AIInput;

这段代码做了三件事：
- 提供输入界面；
- 发起请求到/api/generate（可以是本地代理或远程服务）；
- 收到结果后调用updateScene更新画布。

⚠️ 注意：updateScene是 Excalidraw 提供的官方 API，专门用于动态插入元素。不要手动修改 state，否则会破坏撤销机制。

2. 接入 AI 逻辑

我们再看后端部分。虽然 Excalidraw 主项目不含 AI 服务，但它允许插件化集成。我们可以把 AI 功能做成一个独立模块。

创建utils/ai/generateFromPrompt.ts：

import { ExcalidrawElement } from "@excalidraw/excalidraw/types/element/types"; const SYSTEM_PROMPT = ` 你是一个图表生成助手。根据用户描述生成 Excalidraw 兼容的 JSON 数组。 每个对象包含字段：type ("rectangle"|"diamond"|"arrow")、x、y、width、height、label。 只返回 JSON 数组，不要附加解释。 `; export async function generateElementsFromPrompt(prompt: string): Promise<ExcalidrawElement[]> { const response = await fetch("https://api.openai.com/v1/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${import.meta.env.VITE_OPENAI_KEY}` }, body: JSON.stringify({ model: "gpt-3.5-turbo", messages: [ { role: "system", content: SYSTEM_PROMPT }, { role: "user", content: prompt } ], temperature: 0.5, max_tokens: 1000 }) }); const data = await response.json(); try { const rawOutput = data.choices[0].message.content.trim(); const jsonText = rawOutput.replace(/^```json\n?|```$/g, ''); return JSON.parse(jsonText); } catch (err) { console.error("Failed to parse AI output:", err); return []; } }

这里的关键在于提示词工程（Prompt Engineering）。我们强制要求模型只输出纯 JSON 数组，避免多余文本导致解析失败。同时做了异常处理，防止非法输出让前端崩溃。

当然，API Key 不应该硬编码，而是通过.env文件注入：

VITE_OPENAI_KEY=sk-xxxxxxxxxxxxxx

Vite 会自动暴露以VITE_开头的变量到前端。

实际工作流：从想法到 PR 的全过程

现在我们把上面的功能整合进主应用。但这不是重点。真正的挑战在于：如何确保你的代码能被合并？

以下是我在多个开源项目中总结出的高效 PR 实践：

1. 先找 Issue，别重复造轮子

去 GitHub 的 Issues 页面搜索关键词，比如 “AI generation” 或 “natural language to diagram”。如果已有相关 issue，说明团队已经意识到这个需求，甚至可能有人正在做。

你可以回复：“我对这个功能感兴趣，是否可以由我来实现？”
维护者通常很乐意看到主动贡献者，只要没人认领，大概率会分配给你。

如果没有现成 issue，那就创建一个，标题如：

✨ Feature: Add AI-powered diagram generation from text prompt

然后简单描述设想，附上草图或 mockup 更好。

2. 分支命名要有意义

不要叫patch-1或new-feature这种模糊名字。建议格式：

feat/ai-diagram-generator fix/button-click-issue docs/update-contribution-guide

前缀用feat/、fix/、chore/等，符合 Conventional Commits 规范，有助于自动化生成 changelog。

3. 提交信息要清晰

每次 commit 都是一次沟通。别写 “update file” 或 “fix bug”，而是明确说明改了什么：

git commit -m "feat(ai): add AI input component with OpenAI integration"

这样别人 review 时一眼就知道变更意图。

4. PR 描述要完整

发起 Pull Request 时，填写模板内容至少包括：

动机：为什么要加这个功能？
实现方式：用了哪些技术？有没有替代方案？
测试情况：本地验证过哪些场景？
截图/录屏：UI 改动一定要有视觉反馈！

例如：

本次 PR 实现了通过自然语言生成图表的基础能力。用户可在侧边栏输入描述（如“画一个用户注册流程”），系统调用 GPT-3.5 解析并生成相应图形元素。
目前仅支持基本形状（矩形、菱形、箭头），后续可通过优化 prompt 扩展更多类型。
已测试多种输入场景，包括空输入、长文本、非指令性语句等，均有合理降级处理。

这样的 PR 几乎不会被拒。

常见问题与避坑指南

即使准备充分，你也可能会遇到这些问题：

❌ 分支落后太多，合并冲突严重

解决办法：定期同步主仓库。

git fetch upstream git rebase upstream/main

如果出现冲突，逐个文件解决后再继续 rebase。永远不要 merge upstream/main，那会产生多余的 merge commit。

❌ AI 输出格式不稳定

GPT 有时会返回 Markdown 代码块，有时多出解释文字。必须做清洗和校验：

function safeParseJSON(str: string) { try { return JSON.parse(str); } catch { // 尝试提取 ```json ... ``` 中的内容 const match = str.match(/```json\n?([\s\S]*?)\n?```/); if (match) { try { return JSON.parse(match[1]); } catch {} } return null; } }