从 0 到 1 提一个高质量 Issue：让维护者不用追问就能动手修

给开源项目提 Issue，是很多人第一次"参与开源"的动作。但我翻了一些项目的 Issue 列表后发现：大部分 Issue 不是被拒绝的，而是被忽略的——因为维护者读完不知道要做什么。

这篇写给"想提一个真正有用的 Issue"的人。核心只有一句：让维护者能在不追问你的情况下动手修。

一、先判断：这是 Issue，还是提问？

三种东西经常被混在一起，投错地方就注定石沉大海：

• Bug 报告：现有行为与文档/预期不符，能复现。
• 功能建议：现在没有的能力，且你能说清"谁在什么场景下需要"。
• 使用提问：文档里已有答案，或需要人来帮你调环境。

提问应该去讨论区/群；Issue 区留给前两类。判断标准很简单：如果你希望代码仓库因此发生改动，它就是 Issue。

二、四个必备部分

我现在的习惯是固定四段，缺一段就会被打回：

1. 背景与问题

不要写"希望增加 X 功能"。要写清：谁、在什么场景、遇到什么阻碍、造成什么后果。

反例：建议增加导出 PDF 功能
正例：学生会做完活动方案后，需要把 HTML 方案发给老师审批，但老师在手机上打不开本地 HTML，只能截图发，导致排版全乱、预算表看不清。每次都要人工重做一版 Word。

差别在于：后者给出了受影响的角色、具体动作、以及损失的量化感受。维护者能据此判断优先级。

2. 现状核实

这一段最容易被省略，但它决定了你的 Issue 是不是在"重复提问"。

做法是先自己查一遍，然后写清你查到了什么：

• 现有文档/README 里有没有相关说明？在哪一节？
• 有没有已存在的配置项或变通做法？
• 有没有历史 Issue/PR 讨论过？

写法示例：README 的「快速部署」一节覆盖了启动方式，但没有提到字体与文件编码要求；搜索 Issue 列表未发现同类问题。

这一段的价值：如果确实已存在，维护者只需回你一句链接，双方都省时间；如果不存证，维护者要替你查一遍。

3. 方案建议

不需要你写代码，但要给可执行的选项，而不是把设计难题原样丢回去。

好的建议通常长这样：分点、每条说清"改哪里、怎么改、代价是什么"。例如：

1. 导出前检查环境是否具备所需字体，缺失时明确提示而不是静默产出乱码；
2. 生成的文件显式使用 UTF-8 编码并在文件内声明；
3. 文档补一节「依赖与编码要求」，附排查三步。

注意第 3 条：把文档改进也算作一种方案。很多问题的最优解就是补一句说明。

4. 收益与影响面

一句话说清"修好之后谁会受益、风险多大"。维护者做取舍时看的就是这个。

示例：可减少"生成成功但打不开"这类反馈；改动集中在导出函数与文档，风险低。

三、让 Issue 可复现的三件证据

如果是 Bug，除了上面四段，还要给证据：

• 环境：系统/版本/依赖版本，最好有一段自检命令的输出；
• 最小复现步骤：编号步骤，能让人照着走一遍；
• 期望 vs 实际：分开写，别混在一句里。

我见过最省事的一种写法：把自检脚本的输出直接贴进 Issue。维护者不用问"你环境是什么"，直接看报告就能定位。

四、三个让 Issue 被忽略的坏习惯

1. 只贴截图：截图看不出复现路径，也没法搜索。文字 + 关键截图才是完整信息。
2. 一次提五个问题：一个 Issue 只讲一件事。混在一起会导致"部分修好"，然后这个 Issue 永远挂着。
3. 不带结论的"我觉得不好用"：主观评价对维护者没有信息量。改成"我在做 X 时，步骤 Y 让我多做了 Z 次操作"，就有了可改进的对象。

五、提完之后

• 别催。多数开源维护者是业余时间维护，一周内没回应很正常。
• 如果有人回复让你补信息，尽量一次给全——来回三轮的成本，往往比修 bug 本身还高。
• 如果自己后来找到了解法，回到 Issue 里补一句"已用 X 绕过"，对后来搜到这个问题的人是很大的帮助。

小结

一个高质量 Issue 的本质，是替维护者完成一半的工作：界定问题、排除重复、给出选项、附上证据。做到这四点，你的 Issue 大概率会被认真对待——不是因为礼貌，而是因为它降低了对方的成本。

这也是我衡量"参与开源"的标准：不是提了多少个 Issue，而是有多少个被真正解决。