ApiCatcher 快速上手
ApiCatcher 在本地擷取、檢視和分析應用程式的 HTTP/HTTPS、WebSocket 流量。
本文涵蓋憑證安裝、流量過濾、請求歷史、匯出與 API 文件等日常抓包操作。重寫、指令碼、組合重放等進階能力見下方獨立文件。
進階文件：
目錄
- 基礎準備：憑證配置與除錯授權
- 流量過濾：精準定位除錯目標
- 抓包 Session 與歷史搜尋
- 尋找 Cookie
- 匯出：HAR、檔案與單筆請求
- 自動產生 API 文件
- 品質與效能排查：API 掃描 (API Scan)
1. 基礎準備：憑證配置與除錯授權
1.1 安裝並信任 CA 憑證（除錯 HTTPS 必備）
現代應用程式的資料交換大多走 HTTPS。預設不會擷取 HTTPS 流量：尚未安裝憑證時無法解密，就算抓到也看不到明文。要擷取並解密 HTTPS，必須先安裝並完全信任 CA 憑證。
ApiCatcher 提供兩種憑證方式：
- 使用 App 自動產生的 CA 憑證（大多數情況建議用這個）：依下方步驟安裝。
- 匯入自己的憑證（企業憑證）：若要使用企業自簽憑證，直接看 1.2。
使用預設 CA 憑證：
- 在 App 內點「安裝憑證」，系統會開啟瀏覽器下載描述檔。
- 進入 「設定」→「一般」→「VPN 與裝置管理」，安裝剛下載的 ApiCatcher 描述檔。
- 關鍵步驟：進入 「設定」→「一般」→「關於本機」→「憑證信任設定」，找到名稱以
ApiCatcher CA開頭的憑證，開啟完全信任。
常見排除
- 除錯時出現連線逾時或狀態碼異常：多半是第 3 步沒有完全信任憑證。
- 刪除 App 後重裝：舊憑證已失效，必須在系統設定刪除舊描述檔，再走一次上述流程。
1.2 企業憑證匯入（企業內網除錯）
部分內部應用只信任企業 CA。
- 用途：匯入企業提供的
.pem或.p12，並綁定內部測試網域（例如*.corp.internal），讓本地 TLS 握手能過。 - 注意：必須在停止抓包時匯入或修改，完成後重新啟動才會生效。
1.3 使用自簽憑證
沒有企業憑證、也不想用 ApiCatcher 產生的憑證時，可走企業憑證流程匯入自己的憑證。 詳見：使用自簽憑證
2. 流量過濾：精準定位除錯目標
系統底層和其他背景 App 會產生大量雜訊。建議先設過濾規則，讓視線停在正在除錯的專案。
- 黑名單：名單中的網域不會被記錄。白名單為空時，預設記錄黑名單以外的所有請求。
- 白名單：只要有任何規則，就只記錄白名單匹配的請求。
- 設定技巧：支援
*萬用字元。例如*.example-api.com可匹配該主網域下的測試子網域。
常見排除
- 看不到目標應用的請求：檢查是否開了白名單卻漏填網域，或網域被誤加進黑名單。
- 語法：用星號即可（如
*.api.com），這裡不支援正規表示式。
3. 抓包 Session 與歷史搜尋
黑白名單決定哪些流量會被記錄。記錄之後，在請求歷史頁用 Session 和搜尋條件定位已抓到的請求。
3.1 抓包 Session
一次 抓包 Session 對應一次 VPN 抓包週期，介面以開始時間（yyyy-MM-dd HH:mm:ss）標示，不能自訂名稱。
每次成功啟動 VPN 抓包會建立一條 Session。停止 VPN 時寫入結束時間與請求數；若本次沒有請求，該 Session 會被刪除。進行中的 Session 結束時間顯示為「正在抓包中」。
請求歷史頁的 Session 過濾器可限定某一次抓包，或選擇「全部」。選擇器會顯示時間範圍、抓包時長、請求數，以及本次抓到的 Host（最多 5 個）。依 Session 刪除會移除該次抓包下的請求紀錄。
3.2 過濾條件
請求歷史頁提供過濾列，可在「配置過濾條件」中選擇要顯示的條件，也可「重置過濾條件」。
| 條件 | 匹配方式 |
|---|---|
| Session | 選中某一次抓包，或全部 |
| Host | 精確匹配網域 |
| 應用 (UA) | 依 User-Agent 解析出的應用名稱精確匹配 |
| 方法 | GET / POST / PUT / DELETE / PATCH / OPTIONS / HEAD |
| 協定 | HTTP / HTTPS / WS / WSS |
| 類型 | 全部、HTML、JSON、XML、圖片、影片、音訊、Protobuf（依 Content-Type） |
| 狀態碼 | 1xx–5xx，以及「無回應」 |
| 時間 | 最近 15 分鐘、最近 1 小時、今天、最近 7 天、最近 30 天、自訂範圍 |
3.3 關鍵字搜尋
搜尋框預設匹配 URL（佔位文字為「搜索url...」）。關鍵字為不區分大小寫的子字串包含，不支援正規表示式，也不支援 AND / OR。
透過歷史頁「…」→「切換搜尋目標」選擇搜尋範圍：
| 搜尋目標 | 匹配範圍 |
|---|---|
| URL | 請求 URL |
| 請求頭 | 請求頭的名稱或值 |
| 回應頭 | 回應頭的名稱或值 |
| 請求 Body | 請求體文字 |
| 回應 Body | 回應體文字 |
搜尋 Body 時只處理文字類 Content-Type（HTML / XML / JSON / 純文字 / form-urlencoded / form-data），不讀取圖片、影片等二進位 Body。
4. 尋找 Cookie
「查找Cookie」用來取出某個 Host 最近一次請求裡攜帶的 Cookie（只看請求頭 Cookie，不看 Set-Cookie，也不會合併多筆請求）。
- 打開 歷史記錄。
- 右上角「…」→「查找Cookie」。
- 輸入 Host（必填，可從已抓到的 Host 列表選，也可手輸）。
- 可選 選擇Session，不選則在全部 Session 裡找。
- 點「搜索Cookie」。
找到則顯示「找到最近一次Cookie」及鍵值對；找不到則提示「未找到包含Cookie的請求」。
5. 匯出：HAR、檔案與單筆請求
5.1 匯出為 HAR
HAR 為 HAR 1.2 JSON，可用 Charles、Fiddler、Burp 等匯入。檔名類似 apicatcher-export-yyyyMMddHHmmss.har。
| 入口 | 匯出範圍 | 是否跟隨目前過濾 |
|---|---|---|
| 歷史頁「匯出為HAR」 | 目前過濾結果的全部請求（不只目前頁） | 是（Session、Host、時間、方法、類型、狀態碼、搜尋關鍵字等與列表一致） |
| 歷史頁多選後分享 / 匯出 | 僅選中的請求 | 否 |
| 請求收藏目錄匯出 HAR | 該收藏夾內的請求 | 否 |
介面會提示：「匯出請求總數為 N。您可透過修改過濾查詢條件過濾需要匯出的請求。」匯出過程中不要關閉頁面。
5.2 匯出圖片 / 影片 / 音訊
入口：歷史記錄 頁的檔案管理（資料夾圖示）。
- 三個分類：圖片、影片、音訊。
- 可依 Session、Host 縮小範圍。
- 帶
Range/Content-Range的分片會先合併再匯出。 - 單檔可單獨匯出；批次匯出會依 Host 分子目錄並打成 ZIP。
請求詳情裡也可對請求體 / 回應體點「匯出檔案」，依 Content-Type 存成暫存檔再分享。
5.3 匯出單筆請求
在請求詳情打開「匯出請求」，可匯出：
- Raw：原始 HTTP 請求 + 回應（
.txt） - cURL：可在終端機重放的指令（
.sh） - Markdown：Markdown 預覽（
.md）
6. 自動產生 API 文件
抓到符合條件的 HTTP/HTTPS 請求後，App 會在本地自動產生或更新介面文件，並依 Host 分組。同一介面多次抓包時，只追加尚未出現的欄位，不會覆蓋既有參數名。
6.1 產生範圍與合併規則
只處理有回應、且狀態碼不在 301–308 的 HTTP/HTTPS 請求。請求 Content-Type 為 JSON / XML / multipart/form-data / x-www-form-urlencoded，或回應為 JSON / XML 時才會建檔。圖片、影片、HTML、純文字等會略過。
被重寫規則或指令碼改過的請求不會寫入文件。介面唯一鍵是 方法 + Host + Path（例如 GET + api.example.com + /v1/user）。
合併規則：
- Query、Header、Body 欄位：只增不改既有欄位名。
- Body 範例：僅當這次回應 狀態碼為 200 時更新範例。
- 常見標準頭（如 Cookie、User-Agent）不會進文件參數；Authorization、Content-Type 以及自訂頭會保留。
6.2 匯出到 Postman / Apifox / Bruno
入口：
- Host 的 API 列表右上角匯出（匯出該 Host 下全部介面）。
- 單個 API 詳情頁匯出（僅該介面）。
- 設定 → API 收藏 → 匯出，只匯出收藏目錄裡的介面。
可選目標：
| 目標 | 方式 |
|---|---|
| 匯出到Postman | 填寫 Postman API Key → 載入並選擇 Workspace → 新建 Collection，或選既有 Collection |
| 匯出到Apifox | 填寫 Apifox API Key、專案 ID；可選目標目錄 ID（空則匯入根目錄） |
| 匯出到Bruno | 匯出含 bruno.json 與 .bru 的 ZIP，在 Bruno 裡 Open Collection |
Postman、Apifox 的逐步截圖見：
7. 品質與效能排查：API 掃描 (API Scan)
依本地擷取的流量紀錄，做非侵入式的 API 品質、安全與效能檢查。分析都在裝置本地完成。
7.1 內建掃描引擎
- 敏感資訊自查：檢測明文傳輸的手機號碼、身分證、信箱及雲端服務憑證（如 AWS Key、OpenAI API Key）。
- 異常堆疊洩漏：辨識回應主體中不慎回傳的 Java、Python 或 SQL 報錯呼叫堆疊。
- 高頻呼叫分析：依設定閾值（例如平均請求間隔小於特定毫秒），排查是否有死迴圈或不當邏輯造成的多餘呼叫。
- 耗時評估：聚合各介面的 p95、p99 延遲，協助定位後端瓶頸。
7.2 自訂品質檢測 (Custom Scan)
可撰寫 JS 指令碼做業務側的合規檢查。
- 回傳值規約：若請求符合預期，回傳
null；若不合規（回應體過大、缺少安全標頭等），回傳精簡描述（≤200 字元），系統會納入掃描報告。
常見排除
- 沒分析出結果：確認「掃描範圍 (Host/Session)」裡確實有 JSON/API 流量，而不是純靜態資源。單次掃描有筆數上限。