如何口述一份别人能够复现的错误报告

“它又坏了”是一份诚实的报告，但也很难据此修复问题。等你打开问题跟踪系统时，具体是哪个页面、哪个按钮、出现了什么结果，可能已经记不清了。口述错误报告可以趁记忆犹新保留这些细节，但前提是先为叙述安排好结构。

下面是一套简短的流程，帮助你把观察到的故障整理成别人能够复现的报告。无论你是在测试个人项目、提交工作中的问题，还是协助维护开源工具，都可以使用。准确的命令仍需手动输入，最终报告也仍需检查。语音适合描述发生了什么，而不是编造证据。

从故障现象说起，而不是先下诊断

当标题直接宣告一种猜测时，错误报告就容易偏离重点：“数据库缓存坏了。”你可能是对的，但调查问题的人首先需要知道你观察到了什么。更好的标题会说明操作和结果：“保存草稿后，设置中选定的语言被清除。”即使不接受你对原因的猜测，别人也能测试这个现象。

口述时也遵循同样的原则。先用一句话说明你想完成的任务，再用一句话说明软件实际做了什么。不要先讲一大段这周的经历，也不要猜测哪个子系统出了问题。如果问题时有时无，就明确说明。如果在你的电脑上每次都会发生，也要说明，但不要断言所有人都会遇到。

GitHub 的创建议题指南介绍了如何填写清晰的标题和正文，并指出仓库可能提供议题模板。有模板就使用模板。下面的口述结构能帮助你在填写模板字段之前收集事实，而不是让你忽略项目自己的要求。

五项口述笔记

先打开一份私密的空白草稿，不要直接在公开的问题跟踪系统中提交。将光标放入编辑器，口述五个简短字段，每个字段另起一行。初稿应该像目击者的陈述，而不是润色过的发布说明：

1. 背景：你原本想做什么？说出页面、功能或操作。
2. 步骤：哪些操作导致了故障？按顺序编号。
3. 预期：你合理地预期会出现什么结果？
4. 实际：屏幕上发生了什么？只有核对后才引用简短的错误信息。
5. 范围：问题何时发生、出现在哪种环境中，你能否重复复现？

下面是可复制粘贴的模板。将每个方括号替换为你观察到的细节。如果某个字段的信息未知，就写“未检查”，不要填入看似合理的答案。

标题：[操作]导致[观察到的结果]
背景：我想在[功能/页面]中完成[目标]。
复现步骤：
1. [准确的初始状态]
2. [第一个操作]
3. [下一个操作]
预期：[本应发生的情况]
实际：[发生的情况，包括已核对的错误信息]
频率：[一次 / 偶尔 / 在这台设备上每次尝试都会发生]
环境：[应用版本、操作系统，以及相关时的浏览器]
证据：[如有帮助，附上安全的截图或已脱敏的日志]

不要把方括号念出来，就指望它们自动变成结构化内容。先在编辑器中输入各项标题，再逐项口述。如果你在 macOS 或 Windows 上使用 Talkpad 这样的桌面语音键盘，就把光标放在私密草稿里，每次只口述一个字段。这样在发布前更容易停下来查看和修改每一部分。

复现一次，然后讲述每次点击

记忆会把一连串操作压缩成概述。“我改了一个设置，页面就崩溃了”可能漏掉刷新页面、切换账户或尚未保存的表单。如果安全可行，就在受影响的应用旁边打开草稿，重复这套操作。每做一步都暂停，记录自己做了什么。不要为了把描述写得更好，反复触发会删除数据或扣款的错误。

步骤要具体：“打开设置，选择西班牙语，点击保存，重新打开设置。”不要写“进入平时用的偏好设置，然后照常操作”。如果应用中有多个“保存”按钮，就指出具体面板。如果问题只在重新加载后出现，就写明重新加载。没看过你屏幕的同事也应该能照着步骤操作，而不必发消息询问漏掉了哪次点击。

过程可以口述，但容易出错的字符串要用键盘输入。语音识别模型可能把软件包名称变成普通词语、改变参数的大小写，或者漏掉减号。应用中的堆栈跟踪或错误信息应核对后粘贴，而不是念出来。像 1.4.12 这样的精确版本号也一样。对于风险较低但仍需仔细检查的词语，请参阅我们的名称和技术术语指南。

区分预期结果和实际结果

这一步能让报告真正有用。“表单失败了”几乎没有给调查者提供信息。“点击保存后，出现了确认提示，但重新打开设置时，语言又变回了英语”则描述了可观察到的差异。预期结果也可以同样直白：“重新打开设置时，保存的语言应该仍是西班牙语。”

不要把修复建议偷偷塞进“预期”字段。“应用应该使用另一种缓存”是实现建议，不是用户可见的预期。可以把任何假设放在末尾明确标注的备注中，并保留不确定性。同事可能会发现原因其实是接口响应、过期的客户端状态，或完全不同的问题。

语音识别一旦听错否定词，报告的意思就可能完全颠倒。比较“对话框没有关闭”和“对话框关闭了”。提交前，在屏幕上重新读一遍这些句子。正因如此，我们的优先检查风险点的校对方法会把否定词、数字和名称放在文风修改之前。

补充环境信息，但不要写成详尽的取证档案

通常，最精简而有用的环境信息包括应用版本、操作系统、问题发生在浏览器中时所用的浏览器，以及复现问题所需的功能设置。只有确实测试过，才说明能否在全新会话或另一台设备上复现。如果时间戳或网络状况会影响结果，就记录下来；否则只会增加噪声。

附上截图前先检查。用户名、电子邮件地址、令牌、客户记录和聊天预览可能藏在角落里。裁剪到相关区域，或用可信赖的编辑器模糊处理敏感信息。日志也需要同样检查。如果问题跟踪系统是公开的，就应假定附件也会公开。对于工作场所政策方面的问题，在向任何工具口述机密材料前，请查看我们的语音输入隐私检查清单。

Talkpad 可以把口述草稿输入光标所在的应用，但它不会核实截图是否安全，也不会验证堆栈跟踪是否正确。这些需要你自己检查。如果公司政策限制使用语音处理事故数据，就遵守政策，手动输入敏感部分。

提交前分两轮修改

第一轮检查可复现性。从列出的初始状态开始，严格按照步骤操作。故障出现了吗？预期和实际结果是否有区别，而且表述清楚？是否漏掉了登录步骤或会影响结果的设置？如果无法再次复现，就修改“频率”字段以反映这一点，而不是掩盖不确定性。

第二轮检查风险。对照来源核对版本字符串和错误信息。删除正文和附件中的密钥。用可观察的事实替代猜测，或者明确标注为假设。如果引言拖慢了进入操作步骤的速度，就缩短它。如果初稿是一整段口述内容，而不是清晰的字段，可以使用我们的口述草稿编辑工具指南。

有用的报告不必很长。有些错误只需三个步骤和两句话；另一些则需要一个受控示例。不要凑篇幅。目标是让别人能够复现行为，并理解你为什么预期得到不同的结果。如果你说不清初始状态，就在发布前多调查一下。

常见问题

我可以用语音输入撰写错误报告吗？

可以。先在私密草稿中口述背景、复现步骤，以及预期行为与实际行为。分享之前，手动输入并核对准确的命令、错误信息、网址和版本号。

错误报告应该包含什么？

包括清晰的标题、初始背景、按顺序排列的步骤、预期结果、实际结果、相关环境，以及需要时可安全分享的证据。如果仓库提供议题模板，请遵循模板。

无法复现的错误该如何报告？

说明它只发生过一次还是间歇出现，记录你观察到的现象和已知环境，并说明哪些尝试未能复现。不要靠猜测补齐未知步骤。

我应该在公开议题中附上日志吗？

只有在检查过密钥和个人信息之后才能附上。删除或遮盖敏感数据，只分享有助于说明故障的最小片段。遵守团队的事故处理和隐私规定。

免费下载 Talkpad – 免费方案每周可使用 2,500 个词。