我以前提技术问题时，最常犯的错误是：把完整上下文省略掉，只留下“大佬帮看下，报错了”。

后来发现，很多问题没人回，并不是社区冷漠，也不是项目维护者不愿意帮忙，而是对方根本没法复现、没法判断你做过什么、也不知道你期望的结果是什么。

这篇文章整理一套我现在更推荐的 GitHub Issue / 开源项目提问模板。它不保证每次都有人秒回，但能明显降低沟通成本，也更容易让别人愿意继续看下去。

一、先判断：这个问题适合发 Issue 吗？

发 Issue 前，先做一个简单判断：

• 像 Bug：同样的步骤稳定复现，结果明显不符合文档或预期。
• 像使用问题：自己配置、环境、理解可能有偏差，需要确认用法。
• 像需求建议：当前没有这个能力，希望项目支持。
• 像本地环境问题：只在自己机器出现，换环境可能消失。

如果只是学习某个概念，优先看文档、搜索历史 Issue 或去讨论区；如果已经能描述出复现路径，再发 Issue 通常更合适。

二、一个好 Issue 的核心：让别人“少猜一点”

维护者最怕的不是问题复杂，而是信息碎片化：

• 不知道你用的什么版本；
• 不知道你在哪个系统跑；
• 不知道你执行了哪条命令；
• 不知道完整报错从哪里开始；
• 不知道你期望它本来应该怎样。

所以，一个好的提问并不是写得越长越好，而是把关键变量摆清楚。

三、我常用的 Issue 模板

下面这份模板可以直接复制后按需删改：

## 问题描述
一句话说明遇到的问题：我在执行 xxx 时，出现了 xxx 错误。

## 运行环境
- 操作系统：macOS / Windows / Ubuntu ...
- 语言或运行时版本：Python 3.x / Node.js x.x / Java x.x ...
- 项目版本：v1.x.x / main 分支某个 commit
- 安装方式：pip / npm / Docker / 源码编译 ...

## 复现步骤
1. 执行 ...
2. 修改 ...
3. 运行 ...
4. 出现 ...

## 预期结果
我期望看到什么结果。

## 实际结果
实际发生了什么，包含关键报错。

## 最小复现
提供一个最小代码片段、仓库链接，或说明为什么暂时无法最小化。

## 我已经尝试过
- 查过文档的某个章节
- 搜过历史 Issue：#xxx / 关键词 xxx
- 尝试升级/降级到某版本
- 尝试清理缓存/重装依赖

## 其他补充
日志、截图、配置片段等。注意隐藏 token、密码、真实手机号等敏感信息。

四、最小复现：不是“把整个项目丢上来”

很多人以为“我给你仓库了”就是复现，其实维护者打开一个几十万行的业务项目，成本仍然很高。

更好的做法是做一个最小复现：

• 只保留触发问题必须的文件；
• 删除公司业务、真实数据、私有接口；
• 提供一条能跑起来的命令；
• 如果依赖 Docker，就写清楚启动方式；
• 如果问题和配置有关，只给必要配置项，并脱敏。

一个小技巧：当你尝试做最小复现时，经常会在删代码的过程中自己找到问题。这不是浪费时间，反而是非常有效的排障过程。

五、报错信息怎么贴更友好？

不要只截最后一行，也不要把几千行日志原样糊上去。比较推荐：

• 保留从“第一处异常”到调用栈结束的部分；
• 用代码块包起来，避免格式乱掉；
• 如果日志很长，放到 Gist、Pastebin 或仓库里的文本文件；
• 明确说明“完整日志在这里，正文只贴关键片段”。

另外，截图适合展示界面错位、按钮状态、图表异常；但终端报错、配置文件、代码片段，尽量用文本，别人才能复制搜索。

六、提问时最容易扣分的 5 件事

1. 标题太空：“求助”“出错了”“不能用”都不利于搜索。
2. 没有版本：不同版本的行为可能完全不同。
3. 隐藏关键步骤：只说结果，不说怎么到这一步。
4. 催促式表达：“急急急”“为什么还不修”容易让人反感。
5. 泄露敏感信息：日志里的 token、cookie、内网地址、真实用户数据要先处理。

七、标题可以这样写

一个好标题最好包含：动作、对象、异常现象、环境关键词。

例如：

• 不推荐：运行失败
• 更好：Windows 11 下使用 npm install 后启动报 Cannot find module
• 不推荐：接口有问题
• 更好：调用 /api/upload 上传 20MB 文件时返回 413，但文档写的是支持 50MB

标题写清楚，后面遇到同样问题的人也更容易搜到，这对开源项目和提问者都是加分项。

八、维护者回复后，最好这样跟进

收到回复后，不要只回“还是不行”。可以补充：

• 我按你的建议执行了哪几步；
• 现在的结果和之前有什么变化；
• 新日志或新截图；
• 如果已经解决，说明最终原因和解决方法。

最后这个“解决方法回填”非常重要。它会让这个 Issue 从一次求助，变成一份可搜索的经验记录。

九、我的个人习惯：发之前做 3 分钟自检

我现在发 Issue 前会快速看一遍：

• 标题里有没有关键词？
• 别人能不能照着步骤复现？
• 版本、环境、命令是否写清楚？
• 敏感信息有没有删掉？
• 我是否已经搜索过历史问题？

这 3 分钟通常能省掉后面来回沟通的 30 分钟。

结语

高质量提问不是“姿态低”，也不是“写小作文”，而是尊重对方时间，也帮助自己更快定位问题。

如果你经常参与开源、在公司内部提技术单、或者给同事描述线上问题，这套结构都可以复用：环境、步骤、预期、实际、最小复现、已尝试。

你在 GitHub 或技术社区提问时，遇到过哪些“信息不够导致来回拉扯”的场景？欢迎分享一个你觉得最有用的提问细节。