缺陷报告
维护者打开你的报告时，手里还有几十个同样的任务。报告的价值取决于它能省下多少轮来回追问。
信噪比
用户比贡献者多几个数量级，贡献者又比维护者多一个数量级。这不是礼貌问题，是注意力分配问题：维护者的时间被严重超订，只能优先处理信息完整的报告。
一份能让维护者直接复现的报告，几乎一定会被处理；一份需要三轮追问才能确定版本和入口的报告，很容易沉底。写报告花的十分钟，通常能省掉双方几小时。
必备字段
| 字段 | 写什么 | 反例 |
|---|---|---|
| 环境 | 系统、版本、相关配置 | 「最新版」 |
| 期望 | 具体应该发生什么 | 「应该能用」 |
| 实际 | 报错原文、截图、退出码 | 「报错了」 |
| 复现 | 入口、角色、数据、点击顺序 | 「点按钮」 |
| 已尝试 | 排除过的原因和结果 | 留空 |
期望和实际要分开写，不要用「不正常」概括。复现步骤具体到「以管理员登录后打开 /settings，点击 Submit」，比「点击按钮」有用一个量级。
# 一次把环境信息给全
uname -a
node --version
npm ls --depth=0最小复现
最小复现是最有价值的附件。去掉无关依赖、配置和步骤，直到剩下的每一步都必要。
收集过程常常让你自己找到原因，因为每一次删除都在缩小假设空间。如果删到某一步问题消失，你就知道触发条件在哪。
**环境** macOS 15.2 / node 22.11.0 / pnpm 9.12
**期望** 导出结果包含空列
**实际** 空列被丢弃，行长度不一致
**复现** 导入附件 csv，执行 export，检查第 3 行
**已尝试** 换编码、升级到 main、关闭插件不要只贴一屏终端输出。日志里真正有用的往往只有两三行，剩下的会让维护者自己去找。
搜索、跟进与披露
- 先搜 open 和 closed issue，重复就补充到原帖
- 用
.github/ISSUE_TEMPLATE/bug_report.yml的字段自查 gh issue list --search "关键词"在终端里搜gh issue create按模板开单，字段不会漏- 等两周再礼貌跟进，不要每天 ping
- 维护者多是志愿者，时区和你不同
- 安全漏洞走私下渠道，先读
SECURITY.md - 常见披露窗口是 90 天，具体以项目政策为准
- 贴日志前删掉 token、邮箱、内部主机名
me too 评论对定位问题没有贡献，只是给维护者增加未读。想推动进展，补充你的环境、版本和复现差异。
如果项目用 Git 管理，用 git bisect 找到引入问题的提交，能把一份报告直接变成修复线索，这比任何催促都有效。
从报告到修复
维护者判断优先级的第一件事是能否复现。附带失败测试的报告比任何描述都强，因为它把复现步骤固化成了可执行文件。
- 能写测试就写，测试名说明期望行为
- 提供
git bisect结果，指明引入问题的提交 - 说明影响范围：多少用户、有没有临时绕过方案
- 愿意自己提 PR 时，先在 issue 里说一声
- 注明是回归还是一直存在，附上出错前后的版本
- 用公开的最小仓库演示，不要依赖私有服务
报告里不必揣测修复方案。把现象和约束讲清，维护者更清楚哪种改法符合项目方向；猜错方向反而增加一轮解释成本。
复现环境尽量贴近项目支持的组合。用系统 Python 跑出的问题，可能在项目固定的虚拟环境里不存在，先按文档搭一遍再下结论。
报告之外
问题修好之后回帖说明版本和验证结果，让后来人知道这个结论适用到哪。只留一句「已修复」，别人还得自己试。
- 帮忙把重复 issue 合并到主帖
- 把临时绕过方案写进项目文档
- 补充平台差异，方便维护者判断范围
- 参与 triage 是熟悉项目的好方式
贡献不只有代码。一条准确的复现记录，可能比一个匆忙的补丁更有价值。