本文目录导读：
- 第一步：提交前的“三问自查” (避免浪费他人时间)
- 第二步：撰写高质量 Issue 的“黄金结构”
- 第三步：新手容易忽略的“加分项”
- 常见错误 (千万不要做)
- 一个完整的“优秀 Issue”模板 (可直接套用)
提交高质量的 Issue 报告是参与开源社区或软件开发的重要技能，一个好的 Issue 能让开发者快速理解并解决问题，从而节省双方的时间，以下是一套适合新手的操作指南，核心思路是 “像写给开发者的一封清晰、可复现的求助信”。
第一步：提交前的“三问自查” (避免浪费他人时间)
在写报告之前,请先确认以下几点：
- 这个问题是否已知或被解决？
- 搜索项目 Issue 列表：使用关键词（如错误信息、功能描述）搜索项目的 GitHub Issues 或 Gitee Issues,看是否有人提过类似问题。
- 查看 Wiki/Troubleshooting/FAQ：项目文档中通常有常见问题解答。
- 这是否真的是一个 Bug？
确认不是自己的环境配置错误（比如版本不兼容、忘记安装依赖）。
- 问题是否稳定复现？
尝试重启软件、清空缓存、重新安装后，问题是否依然存在？无法复现的问题很难定位。
如果以上都确认过,就可以开始写报告了。
第二步：撰写高质量 Issue 的“黄金结构”
一个标准的 Issue 报告应该包含以下 6 个核心部分：
标题 (Title) —— 清晰且具体
- 优秀示例：
[Windows 10] 软件在导出 PDF 时崩溃，报错 “内存不足” - 糟糕示例：
软件崩溃了、求助、无法使用 - 原则：用
[系统/平台] + 问题发生步骤 + 核心现象的格式,让开发者一眼就知道问题所在。
描述 (Description) —— 说清楚“发生了什么 vs 应该发生什么”
- 问题现象：简洁描述你遇到了什么。
- 预期行为：你认为正常情况应该是什么。
- 实际行为：实际发生了什么（崩溃、报错、白屏、结果不对等）。
- 如果怀疑是功能请求，则先说明“需求背景”和“期望的新功能”。
重现步骤 (Steps to Reproduce) —— 最重要的部分
这是开发者能复现问题的唯一依据，请以 “1、2、3” 的列表形式,写清楚每一步具体操作。
- 优秀示例：
- 打开软件，版本 3.2.1。
- 点击菜单“文件” -> “导入数据”。
- 选择文件
test.csv（内容中无特殊符号）。 - 点击“开始导入”，等待 5 秒。
- 软件闪退,无任何提示。
- 糟糕示例：
“我点击导入就崩了” （没有具体文件、路径、操作序列）。
环境信息 (Environment) —— 提供“现场照片”
不同环境可能导致不同结果,请提供：
- 操作系统：Windows 10 21H2 / macOS 12.3 / Ubuntu 22.04
- 软件版本：
v4.5.2或 Git Commit ID - 依赖/运行环境：Python 3.11、Node.js 20、Java 17、Docker 版本等
- 硬件信息：如果是性能或图形问题，提供 CPU、显卡、内存等。
日志与截图 (Logs & Screenshots) —— 提供“证据”
- 错误日志：复制粘贴报错的完整文本（不要只截取“）。建议放在代码块中（用三个反引号 ``` 包裹）,避免格式混乱。
- 截图/录屏：如果涉及界面布局、颜色、弹窗位置,一张图胜过千言万语。
- 核心文件：如果是配置文件或数据文件导致的问题，可以脱敏后提供,或给出模拟文件。
尝试过的解决方案 (Tried Solutions)
列出你已经尝试过的操作（例如重启、重装、修改了某个配置）,这样开发者知道哪些方向不需要再试。
第三步：新手容易忽略的“加分项”
- 使用 Markdown 格式化：GitHub/Gitee 都支持 Markdown，合理使用标题（#）、列表（-）、加粗、
代码、代码块,会让你的报告更专业。 - 遵守社区模板：很多项目会提供 Issue 模板（Bug Report 或 Feature Request 模板）。请使用模板,它会引导你填写所有必要信息。
- 态度礼貌，保持耐心：用 “请”、“谢谢” 等礼貌用语，开发者是义务劳动，抱怨或命令的语气会降低被回复的概率。“你好，我在使用过程中遇到了一个奇怪的问题，希望能得到帮助，谢谢！”
- 不要重复提 Issue：如果你确认这是一个新 Bug，提交一个就好，不要因为无人回复就连续提交多个相同 Issue。
- 及时互动：提交后，开发者可能会回复要求更多信息，请及时补充，避免 Issue 被关闭。
常见错误 (千万不要做)
- 甩一个截图就完事：没有描述、步骤，只有一张“错误弹窗”的截图。
- 在 Issue 里询问无关问题：帮我看一下我的代码哪里错了”，这不是该 Issue 的目的。
- 标题写得太笼统：如“求解决”、“救命”,没人知道你要解决什么。
- 指责或要求立即修复：这Bug很严重，你们必须今晚修好”。
一个完整的“优秀 Issue”模板 (可直接套用)
### 描述 当我尝试导入一个包含中文列名的 `.xlsx` 文件时，软件卡死且无响应，之前测试过只有英文列名的文件，导入正常。 - **预期行为**: 能正常导入包含中文字符的 Excel 文件。 - **实际行为**: 导入进度条卡在 50%，然后软件失去响应，任务管理器显示“未响应”。 ### 重现步骤 1. 打开软件 v2.5.0。 2. 点击“数据” -> “导入” -> “从Excel导入”。 3. 选择文件 `中文测试.xlsx` （内容见附件）。 4. 点击“确定”，等待 10 秒。 ### 环境信息 - 操作系统: Windows 11 专业版 22H2 - 软件版本: v2.5.0 (安装包是官网下载的 msi) - Python 版本: 3.12 (如有依赖) ### 日志与截图 服务器日志 (最后几行):
2023-10-01 15:30:00 ERROR [DataImport] UnicodeDecodeError: 'charmap' codec can't decode byte 0xce in position 32: character maps to
截图: [软件卡死的界面截图]
### 尝试过的解决方案
1. 重启软件和电脑 -> 问题依旧。
2. 将 Excel 文件另存为 `.csv` (UTF-8) 格式 -> 可以正常导入。
3. 卸载并重新安装软件 v2.4.0 -> 该版本也有相同问题。
### 附件
- `中文测试.xlsx` (脱敏处理后的测试文件)
谢谢！高质量 Issue = + 可复现步骤 + 完整环境 + 相关证据 + 礼貌态度，按照这个思路写，你很快就能成为一名优秀的“社区贡献者”,而不仅仅是一个提问者。
