ApiCatcher 快速上手
ApiCatcher 在本地捕获、查看和分析应用的 HTTP/HTTPS、WebSocket 流量。
本文覆盖证书安装、流量过滤、请求历史、导出与 API 文档等日常抓包操作。重写、脚本、组合重放等进阶能力见下方独立文档。
进阶文档：
目录
- 基础准备：证书配置与调试授权
- 流量过滤：精准定位调试目标
- 抓包 Session 与历史搜索
- 查找 Cookie
- 导出：HAR、文件与单条请求
- 自动生成 API 文档
- 质量与性能排查：API 扫描 (API Scan)
1. 基础准备：证书配置与调试授权
1.1 安装并信任 CA 证书（调试 HTTPS 必备）
现代应用的数据交互普遍基于 HTTPS 协议加密。默认情况下，App 不会捕获 HTTPS 流量：尚未安装证书时无法解密加密内容，即使捕获也看不到明文，没有实际调试价值。因此，当您需要捕获并解密 HTTPS 流量时，必须先安装并信任 CA 证书。
ApiCatcher 提供了两种证书配置方式：
- 使用系统默认生成的 CA 证书（推荐绝大多数场景）：跟随下方的引导，安装由 ApiCatcher 自动为您生成的专属 CA 证书。
- 导入您自己的证书（企业证书）：如果您需要使用企业自签发证书，可直接跳过此部分，阅读 1.2 企业证书导入 章节。
使用系统默认 CA 证书的操作步骤：
- 在 App 内点击“安装证书”，系统会跳转浏览器下载配置描述文件。
- 进入系统 「设置」 -> 「通用」 -> 「VPN与设备管理」，安装刚下载的 ApiCatcher 描述文件。
- 关键步骤：进入 「设置」 -> 「通用」 -> 「关于本机」 -> 「证书信任设置」，找到
ApiCatcher CA开头的证书，打开开关启用完全信任。
💡 常见排障指南：
- 调试时抓到“连接超时”或者状态码异常：通常是因为第3步没有“完全信任”证书。
- 删除了 App 重新安装：旧的调试证书已经失效，必须去系统设置中删除旧的描述文件，重新走一遍上述流程。
1.2 企业证书导入（企业内网调试场景）
在企业内部开发测试时，部分内部应用可能会配置特定的证书信任策略（仅信任企业内部 CA）。
- 用途：导入企业提供的
.pem或.p12证书，并与内部测试域名（如*.corp.internal）绑定，用于在本地调试时完成合法的 TLS 握手。 - 注意：必须在停止抓包的状态下导入或修改配置，完成后重新启动方可生效。
1.3 使用自签证书
对于个人开发者，如果没有企业证书，也不想使用 ApiCatcher 提供的证书，您可以借助 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 流量记录，而非纯静态资源。为保障体验，单次扫描存在条数上限限制。