技术英语 / 系统课时

写出可复现的 Bug 报告

写出可复现的 Bug 报告

Bug 报告的目标不是证明“这里有问题”,而是让维护者用最少追问重新看到同一个问题。写作时应固定复现步骤、实际结果、预期结果、环境和必要证据,并删除与复现无关的背景。

学习目标

  • 用稳定的英文结构组织可复现 Bug 报告
  • 区分 Actual Result、Expected Result 与主观判断
  • 只保留影响复现的环境信息和日志证据

先让维护者能够重现

一份有效的报告首先回答:维护者从什么状态开始,依次做什么,在哪一步观察到异常。步骤应使用具体动作,而不是模糊描述,例如用 Run npm test、Open Settings、Click Save,不要写 Try the feature。

复现步骤最好满足两个条件:每一步都可以独立执行;删掉其中一步后,问题就可能无法稳定出现。这样可以避免把调查过程、猜测和无关操作一起塞进 Steps to Reproduce。

下面是一份可以直接套用的最小结构:

text
Title: Saving an empty display name returns a 500 error

Environment:
- App version: 3.4.1
- Node.js: 22.12.0
- OS: Ubuntu 24.04

Steps to Reproduce:
1. Start the application with the default configuration.
2. Open Profile Settings.
3. Clear the Display Name field.
4. Click Save.

Actual Result:
The request fails with HTTP 500, and the page shows "Internal Server Error".

Expected Result:
The form should reject the empty value and show a validation message without sending a failing request.

Relevant Log:
ValidationError: displayName must not be empty

这里的标题直接描述触发条件和可见故障;步骤只记录复现动作;Actual Result 写实际观察;Expected Result 写系统应有的行为。维护者不需要先理解提交者的推测,就能开始验证。

分开写实际结果与预期结果

Actual Result 必须描述发生了什么。适合使用可观察事实,例如 The process exits with code 1.、The API returns HTTP 500.。不要写 The API behaves incorrectly.,因为 incorrectly 没有提供可验证信息。

Expected Result 则说明正确行为应该是什么。如果预期来自明确的接口契约、产品规则或文档,可以直接写结果;如果预期只是自己的推断,应降低语气,例如 I expected the request to return HTTP 400 because the field is required.,避免把尚未确认的行为写成既定规范。

环境信息只写影响复现的部分

环境信息不是软件清单。版本、操作系统、运行时、浏览器、数据库或部署方式只有在可能改变行为时才值得记录。例如前端兼容问题通常需要浏览器版本,SQL 方言问题通常需要数据库版本,而纯文案错误通常不需要 CPU 型号。

如果问题只在某个版本出现,应把对照条件写清楚,例如 Reproducible in 3.4.1, not reproducible in 3.3.8.。这种信息比笼统写 It worked before. 更有诊断价值。

日志同样只截取必要范围。优先保留错误类型、关键调用位置、状态码和与失败直接相关的上下文;删除访问令牌、密码、Cookie、用户隐私数据以及数百行无关日志。

删除猜测和无关背景

Bug 报告可以包含假设,但不要让假设取代事实。This may be related to the new validation middleware. 是合理补充,而 The new middleware broke validation. 在没有证据时会过早锁定根因。

可以按一个简单顺序自检:维护者能否按步骤复现;Actual 与 Expected 是否可以直接比较;环境是否足以解释差异;日志是否支持现象而没有泄露敏感信息。满足这四点后,一份短报告通常比带有大量调查笔记的长报告更容易被处理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

写出可复现的 Bug 报告

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通