给开源项目提一个“高质量 Issue”的方法：从文档坏链排查说起（1029-acct2）

一、为什么很多 Issue 石沉大海

“这个功能坏了”“文档打不开”这类描述，维护者无法复现也无法定位，只能来回追问。高质量的 Issue 应当让对方一眼就能判断：问题在哪、怎么复现、期望是什么。

二、案例：文档坏链

我在某仓库的 README 里发现一个指向知识库的链接返回 404。排查步骤：

1. 复制链接在浏览器打开，确认返回码为 404；
2. 在仓库里定位该链接所在的文件与行号（grep -rn）；
3. 对照目录里实际存在的文件名，发现路径写错；
4. 给出正确的路径建议。

三、一个好 Issue 的结构

1. 标题：一句话说清“哪个文件/哪个页面的什么问题”；
2. 复现：给出链接、操作步骤、实际结果与期望结果；
3. 定位：文件路径 + 行号，附最小相关代码/配置片段；
4. 建议：给出可直接采纳的修改方案，降低维护成本。

四、避免重复与噪音

提交前先搜索已有 Issue，确认没被报过；同一文件的多处坏链合并成一个 Issue，不要拆成一堆碎片。

五、小结

提 Issue 的价值在于帮项目变好，积分只是附带。真实问题、清晰复现、可执行建议，三者齐了，被快速合并的概率会高很多。