---
title: Bug Report 撰寫 SOP — 8 個欄位讓開發 30 秒看懂、不被退回
description: 一份不被退回的 bug report 該長什麼樣。Title / 重現步驟 / 預期 vs 實際 / 環境 / 影響 / 證據 / 優先級 / 相關連結，附完整範例與爛 vs 好對比。
category: manual
tags: [bug-report, 範本, 手動測試, 流程]
date: 2026-06-09
---

# Bug Report 撰寫 SOP — 8 個欄位讓開發 30 秒看懂、不被退回

被開發退回「無法重現」、「不是 bug」、「資訊不足」三次以上的 bug，那是你 report 寫得爛，不是開發不配合。一份好的 bug report **讓開發 30 秒讀懂 + 5 分鐘重現**。

## 一份 bug report 該有的 8 個欄位

| 欄位 | 必填 | 用途 |
|------|------|------|
| Title | ✓ | 一句話總結 |
| Steps to Reproduce | ✓ | 編號重現步驟 |
| Expected Result | ✓ | 應該怎樣 |
| Actual Result | ✓ | 實際怎樣 |
| Environment | ✓ | OS / Browser / Version / Build |
| Severity / Priority | ✓ | 影響範圍與優先級 |
| Attachments | ✓ | Screenshot / Video / Log / HAR |
| Related | — | 相關 PR / 之前的 bug / spec |

8 個寫好 → 開發 30 秒看完知道要做什麼。少一個就會被退回問。

## Title 怎麼寫

公式：`[模組] <行為>，<前提下> 應該 <預期> 但 <實際>`

**爛例子**：
- 「登入有問題」
- 「按鈕沒反應」
- 「畫面跑掉」

**好例子**：
- 「[Login] 使用者連續輸錯密碼 5 次後，第 6 次仍能正常嘗試（應被鎖定 15 分鐘）」
- 「[Checkout] iOS Safari 17 上，按『確認結帳』按鈕第二次點擊才有反應」
- 「[Profile] 上傳超過 5MB 的頭像時，前端無錯誤提示但後端 500」

寫到能在 stand-up 上唸出來別人就懂，title 就合格。

## Steps to Reproduce — 重點中的重點

**寫死，不要寫泛指**。

爛例子：

```
1. 進入購物車
2. 加入一些商品
3. 結帳
```

好例子：

```
1. 用瀏覽器開 https://staging.example.com
2. 用以下帳號登入：
   - email: qa-test-007@example.com
   - password: Test@123456
3. 進入「商品列表」/products/
4. 將「商品 A (id: sku-001)」加入購物車 × 2
5. 將「商品 B (id: sku-099)」加入購物車 × 1
6. 點右上「購物車（3）」
7. 點「前往結帳」
8. 選「信用卡」付款
9. 輸入測試卡號 4111 1111 1111 1111 / 12/30 / 123
10. 點「確認付款」
```

**標準**：把這份 steps 交給一個沒接觸過產品的人，他能跑出同樣結果。

### Steps 常見錯誤

1. **跳步驟** — 「然後就 fail 了」中間少了 3 步
2. **沒寫 test data** — 「輸入 email」沒寫哪個 email
3. **預設知識** — 「用 admin 進入後台」沒寫怎麼進
4. **多個 bug 寫一個 report** — 「另外順便提一下…」開新的
5. **寫概念而非操作** — 「驗證搜尋功能」要寫具體點什麼、輸入什麼

## Expected vs Actual — 一定要分開

**爛例子**：

```
結帳後沒有顯示成功頁面，反而跳出錯誤。
```

**好例子**：

```
Expected:
- 點「確認付款」後 → 跳轉到 /order/<id>/success
- 頁面顯示「訂單建立成功」+ 訂單編號
- 寄送確認 email 到 qa-test-007@example.com

Actual:
- 點「確認付款」後 → 停留在原頁面
- 跳出紅色錯誤訊息：「系統忙碌中，請稍後再試」
- 後端 log 顯示 500 InternalServerError
- 未收到確認 email
```

**寫法**：每個 expected 對應一個 actual，數量盡量一致。

## Environment — 越詳細越好

開發測自己機器跑不出來，就是因為環境不同。**至少要的**：

```
- OS: macOS 14.3 / Windows 11 22H2 / iOS 17.4
- Browser: Chrome 124.0.6367.78 / Safari 17.4
- App version: v2.4.1 (build 2024-06-09)
- Backend: staging-api-v3 (commit a1b2c3d)
- Network: WiFi / 4G / VPN
- Account: qa-test-007@example.com (paid plan / 台灣 / 已驗證)
- 時間: 2026-06-09 14:32 UTC+8
```

**Mobile bug 特別要附**：
- 裝置型號（iPhone 13 Pro / Pixel 8）
- 螢幕方向（直 / 橫）
- 是否有 dark mode
- 是否啟用 VPN

## Severity vs Priority

很多人搞混。

| 欄位 | 定義 | 例子 |
|------|------|------|
| **Severity** | 對使用者的傷害 | 資料遺失（critical）、UI 跑版（low） |
| **Priority** | 修復急迫度 | 影響營收（P0）、極少觸發（P3） |

**重要區別**：
- Severity critical 不一定 P0：例如「會掉資料但只有 1% 流量觸發，且有 workaround」可能 P1
- Severity low 也可能 P0：例如「首頁 logo 變形」但是公司 brand 大事

### 我的建議分類

```
Severity:
  S1 Critical   - 系統當機、資料遺失、安全漏洞
  S2 High       - 主要功能無法使用
  S3 Medium     - 次要功能異常、有 workaround
  S4 Low        - UI 小瑕疵、文案錯字

Priority:
  P0 Now        - 阻擋發版、需馬上修
  P1 This sprint
  P2 Next sprint
  P3 Backlog    - 修不修都行
```

## Attachments — 證據說話

不要只貼一張 screenshot。**完整的證據是**：

1. **Screenshot** — 整個畫面、含 URL、含時間 → 一張
2. **Video** — 重現過程 30 秒以內 → 一支（Loom、QuickTime、CleanShot）
3. **Console log** — 瀏覽器 DevTools → Console 全選複製
4. **Network log** — DevTools → Network export HAR
5. **Backend log**（如果你拿得到）→ 失敗時間區間的 log

**video 是金標準**。能用 video 解決 50% 的「無法重現」退回。

### 工具推薦

| 工具 | 用途 |
|------|------|
| Loom / CleanShot | 螢幕錄影 + 上傳分享連結 |
| Chrome DevTools → 三點 → More tools → Recorder | 直接錄成可重播的 recording |
| BrowserStack | 跨平台跨瀏覽器重現 |
| Sentry / LogRocket | 自動錄影 + session replay（要前端設定） |

## 完整範例（直接 copy 改）

```markdown
# [Checkout] iOS Safari 17 上連點「確認付款」會重複建立訂單

## Severity / Priority
S1 Critical / P0 — 影響使用者收費，每天可能發生

## Steps to Reproduce
1. iOS 17.4 Safari 開 https://staging.example.com
2. 登入 qa-test-007@example.com / Test@123456
3. 加入「商品 A (sku-001)」到購物車
4. 進入結帳頁
5. 選「信用卡」、輸入測試卡 4111 1111 1111 1111
6. 在「確認付款」按鈕**快速連點兩次**（< 1 秒間距）
7. 等待 5 秒

## Expected
- 第二次點擊應被忽略（按鈕應 disable 或顯示 loading）
- 只建立 1 筆訂單

## Actual
- 兩次點擊都被接受
- 建立 2 筆相同訂單（order #12345 + #12346）
- 信用卡被扣款兩次

## Environment
- OS: iOS 17.4
- Device: iPhone 13 Pro
- Browser: Safari 17.4
- App version: v2.4.1 (build #2026-06-09-001)
- Backend: staging-api-v3 (commit a1b2c3d)
- Account: qa-test-007@example.com
- 時間: 2026-06-09 14:32 UTC+8

## Attachments
- [影片重現](https://loom.com/share/xxx) (15 秒)
- [Network HAR export](attachments/network.har)
- [Console log](attachments/console.txt)
- Screenshot: `screenshot-2026-06-09.png`

## Related
- 類似 bug 於 2025 Q4：#3421（Android Chrome）
- 相關 spec：[結帳防重複點擊](https://confluence.example.com/checkout-double-click)
- 暫時 workaround：使用者刷新頁面、客服手動退款一筆
```

## 開發退回時常見原因 vs 解決

| 退回理由 | 真正原因 | 解決 |
|---------|---------|------|
| 「無法重現」 | Steps 太抽象 | 加 test data + 環境細節 + video |
| 「這是 spec」 | 沒對到 spec | 附 spec 連結 + 標明差異 |
| 「不是 bug」 | Expected 跟 dev 認知不同 | 拉 PM 三方確認 |
| 「資訊不足」 | 缺 console / network log | 補上 |
| 「我這邊 OK」 | 環境不同 | 詳列 OS / browser / build / account |

## 工具差異不大，內容結構不變

Jira / Linear / GitHub Issues / Notion — 工具決定樣式，**8 個欄位永遠都要寫**。

範本可以做成：

- Jira → Issue template
- GitHub → `.github/ISSUE_TEMPLATE/bug.yml`
- Notion → Database template

**一次設好、團隊終身受益**。

## 最後

Bug report 是 QA 對外的名片。寫得好的人，**開發看到你的 ticket 會優先處理**。寫得爛的人，再急的 bug 也被擱著。**前期多花 5 分鐘寫好，後期省的不只 50 分鐘**。