编写Bug报告的核心，是把一次缺陷观察转成可复现、可判断、可交接的记录：标题写清“在什么条件下出现什么异常”，正文按环境、前置条件、复现步骤、预期结果、实际结果、证据、影响范围逐项填写，提交人先自检，评审人再核对信息完整性与可复现性。本文给出可直接套用的字段清单、从发现到提交的操作步骤、角色分工、改写示例和提交前自检表，严重程度与优先级的判定不在本文展开。
要点总览（TL;DR）
- Bug报告的核心是把一次缺陷观察转成可复现、可判断、可交接的记录，标题写清条件、对象与异常现象，正文按环境、前置条件、复现步骤、预期结果、实际结果、证据、影响范围逐项填写。
- 复现步骤要编号并最小化到去掉任何一步都无法复现；预期结果与实际结果成对书写，逐点对应，避免让开发自行比对。
- 提交前先做最小复现确认、现场采集环境与证据、按模板填写并自检，再检索已有缺陷避免重复提交。
- 提交人负责事实信息，评审人核对完整性与可复现性，开发反馈复现结论与补充需求；退回意见要具体到字段。
- 用首次提交通过率、追问次数、重复缺陷占比、提交到开始定位的时长等指标，发现字段填写中的薄弱环节。
一份合格的Bug报告先写清哪些字段
Bug报告的字段设计围绕一个目标：让没有到过现场的开发人员，仅凭记录就能还原缺陷发生的条件并看到异常。字段不必多，但每一项都要回答一个具体问题，写到能被他人独立使用的颗粒度。
| 字段 | 回答的问题 | 合格颗粒度 |
|---|---|---|
| 标题 | 在什么条件下、哪个对象、出现什么异常 | 一句话包含条件、对象、现象，不写“有问题”“不正常”这类无信息词 |
| 环境与版本 | 缺陷发生在哪套软硬件与数据条件下 | 操作系统与版本、浏览器或客户端版本、被测系统版本、账号角色、相关配置项 |
| 前置条件 | 复现前需要先具备什么状态 | 数据准备、权限、开关配置、依赖服务状态，能直接照做 |
| 复现步骤 | 按什么顺序操作可以再次看到异常 | 编号步骤，每步一个动作，已最小化到去掉任何一步都无法复现 |
| 预期结果 | 按需求或常识应该发生什么 | 写具体结果或引用需求条目，不写“应该正常” |
| 实际结果 | 实际观察到了什么 | 描述现象、报错文案、异常数值，与预期逐点对应 |
| 证据 | 用什么材料证明现象存在 | 关键日志片段、截图、录屏，标注时间点与操作位置 |
| 影响范围与频率 | 影响哪些用户、功能、数据，出现概率多大 | 说明受影响的功能路径与用户群体，频率写“必现”“偶现（约几次出现一次）” |
标题：条件加对象加异常现象
标题是评审人和开发最先读到的内容，应独立成句说明问题。例如“在弱网环境下提交订单页，点击支付按钮后页面停留在加载状态且无错误提示”，比“支付有问题”多提供了触发条件、操作对象和可观察现象。标题里不写原因推测，原因留给开发定位后补充。
环境、步骤与结果的写法
环境信息按“能影响复现”的原则取舍：与界面渲染相关的缺陷记录浏览器与分辨率，与接口相关的缺陷记录服务版本与请求参数，与数据相关的缺陷记录账号与数据集。复现步骤遵循最小化原则，先按完整路径复现一次，再逐步删减无关操作，直到删掉任何一步都无法复现为止。预期结果与实际结果要成对书写，同一操作点上的差异逐条对应，避免预期写一段、实际写另一段，让读者自行比对。
证据与影响范围的取舍
证据以“能支撑结论的最小材料”为准：一条包含错误码和时间戳的日志，往往比整份日志文件更有用；截图要圈出异常位置；录屏适合描述多步交互后的异常。影响范围写清受影响的功能、用户角色和数据，频率用可观察的表述记录。证据不足时，在报告中注明已尝试的采集方式，便于开发判断下一步需要什么材料。
从发现缺陷到提交报告的操作步骤
报告质量在很大程度上取决于提交前的动作顺序。按下面的步骤执行，每一步都有明确的输入和输出，可以减少提交后的往返沟通。
第一步：做最小复现确认
输入是一次异常观察，做法是回到初始状态重新操作一遍，确认现象可重复，并尝试删减操作步骤找到最短路径。输出是一组确认可复现的最简步骤和出现频率。若无法复现，仍可提交，但要在报告中说明尝试过的条件和次数，把“疑似”“偶现”作为事实记录，不写成确定结论。
第二步：收集环境、版本与证据
在复现现场立即采集，避免环境变化后信息失真。输入是最简复现步骤，做法是记录设备、系统、版本、账号角色与配置，同时截取关键界面、保存相关日志片段、必要时录屏。输出是一组与步骤对应的证据材料，每份材料标注采集时间和对应步骤编号。
第三步：按模板填写并自检
输入是步骤、环境与证据，做法是按字段清单逐项填写，填写完成后对照自检表检查：标题是否包含条件与现象、步骤是否可被他人照做、预期与实际是否成对、证据是否指向具体步骤。输出是一份可提交的完整报告。自检发现缺项时，回到现场补齐，不带着空白字段提交。
第四步：提交后响应补充请求
提交后开发可能要求补充日志、特定环境下的复现结果或更精确的时间点。提交人应在约定时间内回应，补充内容直接追加到原报告中并注明补充时间，保持记录连续。若补充信息改变了原有判断，同步更新实际结果与影响范围，避免报告前后矛盾。
第五步：检索重复缺陷并合并
提交前先用标题关键词、报错文案、功能模块检索已有缺陷，确认是否已有相同问题。存在重复时，把新发现的复现条件、环境差异和证据补充到原记录中，并注明关联关系；确属同一根因但表现不同的，保留独立记录并互相引用。合并处理能减少开发重复排查，也让影响范围的统计更准确。
提交人、评审人与开发在报告中的分工
Bug报告在流转中经过三类角色，每个角色承担不同的交付物。分工清晰时，信息缺口在提交环节就被补上，而不是在开发接手后反复追问。
| 角色 | 主要职责 | 交付物 |
|---|---|---|
| 提交人 | 记录事实：环境、步骤、预期与实际、证据、影响范围与频率 | 一份字段完整、可复现的缺陷记录及配套证据 |
| 评审人 | 核对信息完整性与可复现性，判断是否达到可处理标准 | 通过、退回补充或合并重复的处理意见 |
| 开发 | 接收报告，确认能否复现，反馈定位结论与所需补充信息 | 复现结论、补充信息请求、原因分析与修复说明 |
提交人与评审人的交接
提交人对报告中的事实性信息负责，包括现象描述、步骤顺序和证据真实性；评审人不改写事实，只检查信息是否足以支撑处理，例如步骤能否被独立执行、预期结果是否有依据、证据是否对应到具体步骤。评审通过的标准是“开发无需追问即可开始定位”，达不到这一标准的报告退回补充。
开发的反馈与退回机制
开发接收报告后，先按步骤复现并给出结论：能复现的进入定位，不能复现的说明已尝试的环境与操作，并列出需要提交人补充的信息，例如特定账号数据、更完整的日志或录屏。退回补充时，退回原因要具体到字段，例如“复现步骤第3步缺少前置数据说明”，避免笼统要求“再补充一下”。补充完成后由评审人复核，形成闭环。
在缺陷记录需要跨角色流转的团队中，可以把上述字段和状态交接放到统一的工作项中管理。ONES Project 适配缺陷管理等研发场景，支持一键提交 Bug 至对应的项目或迭代，记录和跟踪缺陷修复情况，并可统计缺陷状态分布；ONES TestCase 支持将未通过的用例快速创建缺陷任务，使缺陷在测试与研发团队间流转。字段如何配置、状态如何流转，按团队实际流程约定即可。
示例：一条模糊描述如何改写成可复现报告
下面用一个演示情景说明改写方法，场景为虚构，仅用于展示字段填写差异。
原始描述的问题
原始描述为：“导出报表功能有问题，导出的文件打不开。”这条记录缺少触发条件、操作路径、文件类型、环境版本和报错信息，开发无法判断是前端下载、后端生成还是文件格式的问题，只能先追问再排查。
改写后的标题与复现步骤
改写后的标题：“在Chrome浏览器下导出超过1万行的订单报表，下载的xlsx文件用Excel打开提示文件损坏”。复现步骤：
- 使用具备报表导出权限的测试账号登录测试环境；
- 进入订单报表页，筛选时间范围为最近三个月，确认结果行数超过1万行；
- 点击“导出”，等待下载完成；
- 用Excel打开下载的xlsx文件，观察提示信息。
证据与预期实际结果的补全
预期结果：文件正常打开并显示与页面一致的1万行以上数据。实际结果：Excel提示“文件已损坏，无法打开”，文件大小约2MB，同一账号导出5000行以内的报表可正常打开。证据：下载文件、Excel报错截图、导出接口返回状态码与耗时日志片段。影响范围：所有需要导出大数据的运营人员，当前测试环境必现。
改写前后的处理差异
改写前，开发需要先确认浏览器、文件类型和数据量，再尝试复现，沟通轮次多且容易在错误方向上排查。改写后，开发可以直接按步骤复现，从“小数据量正常、大数据量失败”这一差异切入，判断问题出在文件生成或分片逻辑，定位起点明确。报告的价值体现在这里：把观察转成可执行的信息。
提交前的完成检查与常见退回原因
提交前用下面的清单逐项核对，全部通过再提交。清单同时可作为评审人的核对依据。
| 检查项 | 通过标准 | 阻断项 |
|---|---|---|
| 可复现性 | 他人按步骤可复现，或已说明无法复现的条件与次数 | 步骤缺失关键动作，无法照做 |
| 信息完整性 | 环境、版本、前置条件、预期、实际、影响范围均有内容 | 关键字段空白或只写“同上”“正常情况” |
| 证据充分性 | 证据对应到具体步骤，能支撑现象描述 | 仅有文字描述，无日志、截图或录屏 |
| 标题准确性 | 包含条件、对象与异常现象 | 标题只有“有问题”“报错”等无信息表述 |
| 重复检查 | 已检索并关联已有缺陷 | 与已有记录重复且未合并 |
常见退回原因与修正方式
退回集中在几类情况：复现步骤写成结果描述而非操作序列，修正为按动作编号；预期结果写成“应该正常”，修正为引用需求条目或写出具体结果；证据与步骤脱节，修正为标注每份材料对应的步骤编号；影响范围只写“影响使用”，修正为写明受影响功能、角色和数据。退回意见应指向具体字段，提交人按字段补充后重新提交。
质量改进的可观察指标
团队可以用几个可观察的指标判断报告质量是否在改善：报告首次提交的通过率、开发因信息不足发起的追问次数、重复缺陷占比、从提交到开发开始定位的平均时长。这些指标按周期统计，用于发现字段填写中的薄弱环节，例如追问集中在环境信息，就调整模板中的环境字段提示。指标本身不替代对单份报告的判断，只作为改进依据。
常见问题
缺陷无法稳定复现时，Bug报告还要提交吗？
可以提交，但要把“无法稳定复现”作为事实写清楚。记录尝试过的环境、操作路径和次数，说明现象出现的频率，例如偶现几次出现一次，并附上已采集到的日志或截图。这样开发能判断是否需要特定数据或环境才能复现，而不是把疑似问题当成确定结论处理。
Bug报告里的严重程度和优先级应该由谁填写？
严重程度与优先级的判定属于缺陷分级环节，本篇不展开判定规则。在报告流转中，提交人可以提供影响范围与频率等事实信息，作为分级判断的输入；具体等级由团队约定的分级责任人在评审或分级环节确定，避免提交人凭主观感受直接定级造成偏差。
提交后发现信息写错了，应该修改原报告还是重新提交一条？
优先在原报告中修改并注明修改时间，保持记录连续，避免同一缺陷出现多条记录。如果补充信息改变了原有判断，同步更新实际结果与影响范围。只有确认是另一个独立问题时，才新建记录并互相引用关联关系。
团队用ONES管理缺陷时，Bug报告字段和状态流转怎么落地？
ONES Project 适配缺陷管理等研发场景，支持一键提交 Bug 至对应的项目或迭代，记录和跟踪缺陷修复情况，并可统计缺陷状态分布；ONES TestCase 支持将未通过的用例快速创建缺陷任务，使缺陷在测试与研发团队间流转。字段如何配置、状态如何流转，按团队实际流程约定即可，本篇不展开具体配置步骤。
评审人退回报告时，怎样提意见才能减少往返次数？
退回意见指向具体字段，例如“复现步骤第3步缺少前置数据说明”“预期结果未引用需求条目”，并说明需要补充到什么程度。笼统要求“再补充一下”会让提交人反复猜测。提交人按字段补齐后由评审人复核，形成一次闭环，而不是多轮来回。
