之前写过《如何给开源项目提第一个 PR》，讲的是怎么贡献代码。但在提 PR 之前，大多数人先接触的是 Issue——报错了、功能不会用、想提需求，都要走 Issue。一个写得好的 Issue，作者愿意回；写得烂的，直接被忽略。这篇讲讲规矩。

提之前：先做三件事

第一，搜一遍。

把报错信息复制到该仓库的 Issue 搜索框里搜一遍。十个 Issue 里有六个是重复提问，作者看到重复标题血压直接拉满。搜到了已有的，就去那个下面补充信息，别开新的。

第二，看文档和 README。

读 README 时提到的 FAQ 和 Troubleshooting 章节，先翻一遍。因为没看文档提的 Issue，回复往往只有一个链接——指向你本该看的那页文档。

第三，确认版本。

很多"bug"其实是旧版本的问题。先升级到最新版复现一遍，还能复现再提。Issue 模板里通常有版本栏，如实填。

标题：把问题说进标题里

坏标题：“出 bug 了"“求助"“为什么不行”。这种标题作者看都不想点。

好标题的公式：+ 具体现象。比如：

  • “Windows 下 v2.3 启动时报 DLL 缺失”
  • “导入超过 1 万行的 CSV 时内存溢出”

标题里带上环境和现象，作者扫一眼就知道要不要点进来。

正文：复现步骤是灵魂

一个能让作者快速动手的 Issue 正文，包含这几块：

  1. 环境：操作系统、软件版本、相关依赖版本。
  2. 期望行为：你以为会发生什么。
  3. 实际行为：实际发生了什么，贴报错日志（用代码块，别截图贴大段文字）。
  4. 复现步骤：1234 列清楚，精确到点击。作者能照着复现，问题就解决了一半。
  5. 已尝试的排查：说明你不是伸手党，比如"我试过重装/换版本，现象依旧”。

记住：作者的时间是志愿的。你把信息给全，是对人家时间的尊重。

提问的语气

  • 用陈述句描述问题，别用质问句。“这个功能是不是根本没做？“不如"文档里提到支持 X，但我没找到入口，请问是在哪个版本？”
  • 别道德绑架。“这么明显的 bug 都不修吗”——人家不欠你的。
  • 英文项目就用英文写。机翻也行，态度到位比语法完美重要。

催更的边界

Issue 提完没人回，怎么办？

  • 一周内：别催。维护者可能在忙。
  • 两周后：可以礼貌 bump 一次，补充点新信息（比如"我在最新版复测了，问题还在”），比干催"有人看吗"有用。
  • 一个月没动静：考虑是不是项目本身不活跃了。看看最近 commit 时间，如果仓库已经半年没更新，这个 Issue 大概率石沉大海，换方案比死等强。
  • 永远别做的事：@ 作者私人账号催、在多个 Issue 里刷屏、用"不用我就换竞品"威胁。

需求类 Issue 单独说

报 bug 和提需求是两回事。提需求（feature request）时，讲清楚你的场景，而不是直接要功能。“我希望加个导出 PDF 的按钮"不如"我们团队每周要给客户发报告，现在只能截图，希望能直接导出 PDF”。讲场景，作者才能判断这个需求值不值得做、怎么做最合适。

收尾

Issue 关掉之后，如果是作者修好的，回一句感谢。举手之劳，但维护者真的会记得。开源社区是人情社会，你的每一次体面提问，都在给下一次攒信用。