Excalidraw issue提交规范说明

Excalidraw Issue 提交规范：从模糊反馈到高效协作

在开源项目中，最让人头疼的不是代码有多复杂，而是用户说“出问题了”却不说清楚到底发生了什么。

你有没有遇到过这样的 issue？标题是“不好用”，正文只有一句“导出图片糊了”，连浏览器都没提。开发者只能来回追问：“你用的是哪个版本？”“能录个屏吗？”“是所有图都糊，还是特定情况下？”——一轮沟通下来，半小时没了，问题还没开始查。

这正是 Excalidraw 这类活跃开源项目必须面对的现实：用户的参与度越高，无效信息的噪音就越大。而解决之道，并非限制反馈，而是建立一套轻量但有效的提交规范，让每一次上报都能成为推动项目前进的燃料，而不是消耗维护者精力的负担。

Excalidraw 作为一款主打手绘风格、支持实时协作的在线白板工具，已经被广泛用于技术架构设计、产品原型草图和会议视觉化记录。它的开源属性决定了其进化速度高度依赖社区贡献。而 GitHub 上的 issue 区，就是这场集体共创的主战场。

但很多人没意识到：写好一个 issue，本身就是一种技术能力。它要求你从“我觉得哪里不对劲”的使用者视角，切换到“别人如何复现并解决问题”的工程协作视角。

当你提交一个 bug 报告时，本质上是在为开发者节省时间；当你提出功能建议时，其实是在参与产品决策。因此，格式是否规范、信息是否完整，直接决定了你的声音会不会被听见。

目前 Excalidraw 在 GitHub 使用了结构化的 issue 模板（YAML 驱动），分为 Bug Report、Feature Request 和 Documentation 等类型。这些模板不是形式主义，而是经过长期实践沉淀下来的最小必要字段集合。我们不妨拆开看看，它们背后的设计逻辑是什么。

先看最常见的Bug 报告。

核心目标只有一个：让别人能在相同条件下看到你看到的问题。这意味着你需要提供足够的上下文，而不是猜测原因。

比如有人说“AI 生成功能没反应”，这几乎无法处理。但如果他说：

在 Chrome 126 上打开 excalidraw.com，点击 AI 图标输入 “draw a server cluster”，无任何响应，控制台报错TypeError: Cannot read property 'then' of undefined，截图如下👇

这就完全不同了。操作系统、浏览器版本、操作步骤、错误表现、附加日志一应俱全，开发者甚至不用回复就能开始排查。

Excalidraw 的 bug 模板明确要求填写以下几项：

• Describe the bug：用一句话讲清现象，不要掺杂推测
• Steps to reproduce：按数字编号列出操作流程，确保每一步都可执行
• Expected vs Actual behavior：对比“应该怎样”和“实际怎样”
• Screenshots / Videos：视觉类工具尤其依赖图像证据
• Environment：OS、Browser、Device、版本号等运行环境参数

其中最容易被忽略的是版本信息。Web 应用看似总是最新版，但实际上 CDN 缓存、本地 Service Worker 或私有部署可能导致用户滞留在旧版本。所以官方建议通过 URL 参数或 devtools 查看当前 commit hash。

更进一步，如果问题是偶发的，可以注明Reproduction Rate—— 是必现？偶尔出现？还是只发生过一次？这对判断是否为边界条件或竞态问题至关重要。

这些字段组合起来，实际上构成了一个微型的“故障诊断协议”。它不追求完美，但足以覆盖 90% 以上的常见问题场景。

再来看功能请求（Feature Request）。

很多人把这里当成许愿池，“希望支持 LaTeX”、“加个深色模式吧”。这类泛泛而谈的提议往往石沉大海，不是因为团队不重视，而是缺乏足够依据去评估优先级。

高质量的功能请求，应该像一份简短的产品需求文档（PRD），回答四个关键问题：

1. 现在有什么痛点？
2. 谁会用这个功能？
3. 他们怎么使用？
4. 为什么值得做？

为此，Excalidraw 的模板引导用户采用“问题驱动”的叙述方式：

### What problem does this feature solve? Briefly describe the problem or limitation you're facing.

这一栏强迫你退一步思考：如果没有这个功能，用户正在忍受什么？例如，“当前无法标注数学公式，导致学术团队不得不切换到其他工具完成示意图”。

接着是Example use case，鼓励以用户故事（User Story）的形式描述场景：

As a technical writer, I want to insert inline equations so that my diagrams can accurately represent algorithmic workflows.

这种表达方式能让开发团队快速共情，并判断该功能的影响范围。

还有一个常被忽视但非常聪明的设计：Can this be solved through a plugin?

Excalidraw 支持插件系统，许多个性化需求完全可以通过扩展实现，而不必进入核心代码库。这个问题提醒提交者先考虑解耦方案，避免核心功能膨胀。这也体现了开源项目的模块化哲学：不是所有好点子都要变成内置功能。

此外，模板还询问是否有替代方案、竞品参考等，帮助维护者横向评估设计合理性。如果你能附上一张手绘草图或 mockup，那就更好了——毕竟这是个画图工具，视觉表达本就是强项。

除了内容结构，整个 issue 流程的技术支撑也值得一提。

GitHub 的 issue 系统本身提供了强大的协作基础设施：

• 标签（Labels）：如bug,enhancement,needs reproduction,blocked,good first issue，实现自动化分类与过滤
• Reaction 赞同机制：👍 表情可用于社区投票，帮助识别高关注度问题
• 自动关联 PR：当 Pull Request 中包含fix #1234类似语句时，会自动链接并关闭对应 issue
• Project Board 集成：可将 issue 拖入看板，纳入迭代规划

配合.github/ISSUE_TEMPLATE/目录下的 YAML 模板，还能生成表单式界面，降低填写门槛。例如：

name: 🐛 Bug Report about: Create a report to help us improve title: '' labels: bug assignees: '' body: - type: textarea attributes: label: Describe the bug description: A clear and concise description of what the bug is. validations: required: true

这套配置不仅统一了输入格式，还可结合 GitHub Actions 实现自动化校验。比如检测是否缺少环境信息、是否重复提交等，进一步减少人工干预成本。

在一个典型的修复流程中，我们可以看到这套机制如何运转。

假设某用户发现：在 iPad Safari 上双指缩放后，元素拖动变得异常缓慢。他按照模板提交 issue，附上了录屏视频和设备信息（iPadOS 17.5, Safari, Excalidraw v0.15.0）。维护者查看后标记为needs reproduction，另一位用户回复确认复现成功并点了 👍。随后 issue 被标记为confirmed，加入下一 Milestone。

不久后，有贡献者分析出问题源于手势事件监听器未正确清理，提交 PR 修复。CI 自动运行测试通过后合并，发布预览版。原提交者验证无误，手动关闭 issue。

整个过程公开透明，所有讨论、变更、验证都在同一个 thread 内完成。这不仅是问题解决的过程，更是一次知识沉淀：未来任何人遇到类似性能问题，都可以搜索历史 issue 快速定位。

当然，规范也要讲究平衡。

太复杂的模板会劝退普通用户，尤其是移动端提交时，填一堆字段简直折磨。因此 Excalidraw 的设计很克制——字段不多，但每个都有明确用途。默认标签自动填充，减少操作负担；支持图片粘贴上传，适配移动场景；甚至未来可以考虑引入 Copilot Suggestions，根据描述智能推荐标签或相似 issue，防止重复提交。

另一个重要考量是国际化。目前模板以英文为主，对中文用户有一定门槛。社区完全可以贡献中文版模板（如bug_report_zh.yaml），让更多非英语母语者也能清晰表达。事实上，已有不少中文用户通过翻译辅助工具提交高质量 issue，说明需求真实存在。

同时，建议善用 GitHub Discussions 功能。对于尚不成熟的想法、不确定是否为 bug 的行为，或需要广泛征求意见的改进方向，先在 Discussions 中探讨，达成共识后再创建正式 issue，能有效避免 issue 区被碎片化讨论淹没。

最终我们要明白，一个好的 issue 规范，不是为了设卡，而是为了加速。

它把原本可能长达数轮的澄清对话，压缩成一次完整的初始表达；它让维护者从“客服”回归“开发者”角色；它让每个普通用户都有能力参与到产品的演进中来。

在 Excalidraw 的世界里，每一个清晰的复现步骤、每一句准确的行为描述、每一张用心的截图，都是对这个开源项目最实在的支持。

下次当你准备点击“New Issue”时，不妨多花三分钟：检查一下版本号、整理下操作流程、截个图。这不是繁琐的仪式，而是一种协作素养的体现。

正是这些细节，让 Excalidraw 不只是一个画画的工具，更成为一个真正由社区驱动、持续进化的协作生态。