NetPeek 用户手册

NetPeek 是一款本地网络抓包与调试工具。所有流量分析都在本机完成,不上传服务器。本手册按核心功能分节,点顶部标签可跳转,文中蓝色按钮可直接打开对应功能。

① 抓包 ② 解密 HTTPS ③ 重写规则 ④ 专家语法 ⑤ 脚本 ⑥ 重放 ⑦ 常量 ⑧ 过滤 ⑨ MITM 主机 ⑩ 工具箱 ⑪ MCP 服务 ⑫ 规则分享 ⑬ 隐私与安全

1抓包

抓包是一切的起点:开启后 App 通过本机 VPN 隧道接管流量,把每个请求/响应记录下来供查看。

  1. 首页点大按钮开始抓包,首次会请求添加 VPN 配置,点允许。
  2. 正常使用其它 App,请求会实时出现在最近请求列表。
  3. 点任意一条进入请求详情:URL、请求/响应头、Body、状态码、耗时、TLS 信息一应俱全。
  4. 再次点大按钮停止抓包结束。

列表左滑单条请求有快捷操作:复制 cURL、加过滤、加 MITM、基于此请求新建重写、导出 HAR、收藏、删除。

HTTP 明文请求直接可读;HTTPS 需要先解密(见下一节),否则只能看到域名和加密字节。

2解密 HTTPS(安装证书)

要看到 HTTPS 的明文内容,需安装并信任 NetPeek 在本机生成的 CA 证书。这一步由你手动完成,iOS 会强制经过「设置」确认。

  1. 开始抓包后,在浏览器打开 http://127.0.0.1:8080 的证书安装页,下载描述文件。
  2. 前往设置 → 通用 → VPN 与设备管理,安装该描述文件。
  3. 再到设置 → 通用 → 关于本机 → 证书信任设置,为 NetPeek 证书打开「完全信任」。
  4. 回到需要解密的域名,把它加入 MITM 主机(见第 9 节)。
证书只用于本机解密调试,不会被上传。上游证书默认fail-open(容错放行,不因证书异常中断连接),便于调试配置不规范的服务端。

3重写规则(简单模式)

重写 = 不改代码就改包:加请求头、替换响应字段、Mock 接口、拦广告、重定向。一条规则 =「什么时候生效(条件)」+「做什么(动作)」。新手用简单模式,点几下即可。

  1. 从最近请求左滑选「新建重写」(自动预填域名/路径),或到重写列表点 +。
  2. 什么时候生效:选「所有请求」或加条件(域名包含 / 路径开头是 …)。
  3. 你想做什么:六张意图卡片任选其一。
  4. 改成什么:按意图填字段。下方实时显示一句人话摘要,确认无误点保存并启用。
意图用途
改 Header给请求/响应加、改、删一个头
改 Body把响应/请求正文里的一段文本替换掉
Mock 响应不发真实请求,直接返回自定义内容
拦截请求返回空响应 / 空 JSON / 空图片,常用于屏蔽广告埋点
重定向把请求跳到另一个 URL(如线上→测试)
本地文件用设备上的文件内容作为响应返回
新建一条重写 打开重写列表
多条件之间是「并且」。需要「或者」时,再建一条同样动作的规则即可。想做更复杂的组合(多动作、括号、正则),点编辑页右上角切到专家模式。

4重写规则 · 专家语法(DSL)

专家模式直接写规则语句,能力最全。动作里第一个符号(^ 替换、~ 删除、@ 开头的整体动作)决定「做什么」,后面 @req.*/@rsp.* 决定「对哪里」,引号里是值。

务必使用英文半角引号 ";中文全角引号 「」 会使规则静默失效。

条件对象

对象含义示例
@req.host请求域名@req.host CONTAINS "example.com"
@req.api请求路径@req.api BEGINSWITH "/api/v1"
@req.url完整链接@req.url MATCHES ".*\.jpg(\?.*)?$"
@req.query查询字符串@req.query CONTAINS "debug=1"
@req.method请求方法@req.method == "POST"
@req.port / @req.schema端口 / 协议@req.schema == "http"
@req.header["名"]请求头@req.header["Content-Type"] CONTAINS "json"
@req.bodyText请求正文@req.bodyText CONTAINS "vip"
@rsp.header["名"]响应头@rsp.header["Content-Type"] CONTAINS "json"
@rsp.bodyText响应正文@rsp.bodyText CONTAINS "false"
@rsp.status / @rsp.statusLine状态码 / 状态行@rsp.status == "404"

比较与逻辑

比较:== != > < >= <= CONTAINS BEGINSWITH ENDSWITH LIKE(通配 */?) MATCHES(正则,整体匹配) IN ANY/ALL/NONE。逻辑:&&(并且) ||(或者) !(取反),可用 () 分组。

执行动作

动作说明示例
^替换/插入^@req.header["X-Debug"] "1"
~删除~@req.header["Authorization"]
@mock直接返回自定义响应@mock "{\"ok\":true}"
@reject*返回空内容(空/空图/空对象/空数组)@reject-array
@redirect重定向(可带 @301…@308)@redirect 307 "https://test/x"
@map-local用本地文件当响应@map-local "/共享目录/mock.json"
@break中断请求@break

例给某接口加调试头并把响应字段改成 true

条件:@req.host CONTAINS "api.example.com" && @req.api BEGINSWITH "/feature"
动作1:^@req.header["X-Debug"] "1"
动作2:^@rsp.bodyText "\"enabled\":false" "\"enabled\":true"

5脚本

当规则不够用时,用 JavaScript 脚本对命中请求做更灵活的处理:读取/改写请求与响应、解压 gzip、按条件计算返回值等。脚本按 host 生效,和规则一样在隧道里运行。

  1. 脚本列表点 + 新建,填名称与作用域(host)。
  2. 在编辑器里写处理逻辑(提供 $utils 等辅助能力,如 gzip 解压)。
  3. 保存并启用,重新发起请求即可看到效果。
打开脚本列表 新建脚本

6重放

把一条抓到的请求保存下来,随时改改参数再发一遍,用于接口联调、压测复现。支持从请求详情一键生成。

  1. 在请求详情或左滑菜单选「加入重放」,或到重放列表点 +。
  2. 编辑方法、URL、头、Body,可设定时/循环。
  3. 点发送,查看返回;历史结果可回看。
打开重放列表 新建重放

7常量

把常用的值(如某段 Mock JSON、Token、测试地址)存成常量,规则里用 ${常量ID} 引用,改一处即可全局生效。

打开常量管理 新建常量
简单模式的 Mock 已自动帮你处理响应内容,通常无需手动建常量;常量更适合专家模式里跨多条规则复用。

8过滤(只看关心的)

抓包列表会很长。用过滤器把噪音去掉:

9MITM 主机名单

出于性能与稳定,NetPeek 只对你指定的域名做 HTTPS 解密(MITM),其余走透明转发。名单支持通配:

自有后端域名(控制面)始终强制直连、不解密、也绝不写入抓包库,属安全红线。

10工具箱

在设置 → 工具箱中,可使用编码转换、哈希与加解密、时间戳、UUID、JSON 格式化等常用开发小工具。写重写规则前,可用正则工具先验证匹配是否正确。

11MCP 服务

若你希望用电脑上的 AI 客户端协助分析本机抓包,可开启 NetPeek MCP 服务。入口在设置 → NetPeek MCP,默认关闭。

  1. 打开开关,生成并复制访问令牌(Token)。
  2. 在同一局域网(或 USB)的 AI 客户端中填写服务地址与 Token。
  3. 按客户端说明连接后,即可查询抓包、分析请求,或按需导入规则。
请勿把 Token 发给不可信的人,也不要在公共网络随意开启服务。不用时建议关闭服务或吊销 Token。

12规则分享与导入

把重写规则分享给同事,或导入他人发来的规则。使用前请先登录账号。

如何分享

  1. 打开重写规则,选中要分享的规则,点分享。
  2. 填写分享标题,设置最多可被领取的次数,以及有效天数。
  3. 确认后,复制分享口令(或系统分享),发给对方即可。
若选中了私密规则,系统会再次确认:对方导入后可以使用规则,但无法查看、编辑、再分享或导出其内容。

如何导入

  1. 复制对方发来的分享口令或链接。
  2. 打开 NetPeek;若检测到剪贴板中的分享内容,会提示你审阅并导入。
  3. 也可在重写规则页选择「输入分享码」,粘贴后审阅再领取。
审阅时仅展示标题、发布者、数量等基本信息;确认领取后才会下载规则内容。不能导入自己创建的分享。

管理与更新

13隐私与安全

验证改写是否生效:保存并启用规则后,请重新发起一次请求,再到最近请求详情中核对结果,不要只看改写前的旧记录。