agent-browser 网络拦截完全手册：请求 Mock、HAR 录制与调试技巧
【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/GitHub_Trending/agen/agent-browser
agent-browser 是一款面向 AI Agent 的浏览器自动化命令行工具，内置完整的网络拦截能力：你可以用network route拦截并 Mock 请求、用network requests过滤排查异常流量、用network har一键录制标准 HAR 文件。本文面向新手，带你快速掌握这套"抓包 + Mock + 调试"的组合拳。
一、agent-browser 网络命令速览 🧭
网络相关功能集中在network子命令下，核心能力一览：
| 命令 | 作用 |
|---|---|
network route <url> | 拦截匹配 URL 的请求 |
network route <url> --abort | 直接阻断请求 |
network route <url> --body <json> | 返回 Mock 的响应体 |
network unroute [url] | 移除单条或全部路由 |
network requests | 查看已跟踪的请求日志 |
network request <requestId> | 查看单个请求/响应详情 |
network har start / stop | 开始 / 停止 HAR 录制 |
完整命令参考见 skill-data/core/references/commands.md，官方文档在 docs/src/app/network/page.mdx。
二、请求拦截三步走：从阻断到 Mock
1. 拦截要在导航前生效：先"空启动"浏览器
路由（route）是在匹配请求发出之前生效的。如果希望首次页面加载就被拦截，正确的姿势是先不带 URL 启动浏览器，此时浏览器停留在about:blank，路由就有时间注册好：
agent-browser open agent-browser network route "**/analytics/**" --abort agent-browser network route "**/api/users" --body '{"users":[]}' agent-browser navigate https://app.example.com这一技巧对"拦截首屏请求"非常关键，详见 skill-data/core/references/commands.md 中的 Pre-navigation setup 章节。
2. 按 URL 拦截：阻断、Mock、放行三种模式
- 阻断：加
--abort，匹配的请求直接失败。适合屏蔽统计埋点（如**/analytics/**）、广告脚本等干扰流量。 - Mock 响应：加
--body '<json>'，请求不会真正发出去，而是直接返回你提供的 JSON。测试"用户列表为空"这类边界场景时，一行命令就能伪造接口数据。 - 恢复原状：用
network unroute移除指定路由；不带参数则清空全部路由。
3. 按资源类型拦截：更精准的"外科手术"
--resource-type支持script、image、font、xhr、fetch等类型，可逗号分隔：
agent-browser network route "*" --resource-type script --abort这样只拦截脚本，不影响其他资源——是排查 JS 报错、验证服务端渲染（SSR）产物的常用手段。
三、快速定位异常请求：network requests 过滤技巧
跑完一段自动化后，可以用请求日志快速排查：
agent-browser network requests # 全部请求 agent-browser network requests --filter api # 按 URL 子串过滤 agent-browser network requests --type xhr,fetch # 只看接口请求 agent-browser network requests --status 2xx # 按状态码/状态族过滤拿到requestId后，用network request <requestId>查看完整的请求头、响应头和响应体。排查 4xx/5xx 报错时，这套"先过滤、再看详情"的流程能大幅减少翻日志的时间。
⚠️ 安全提示：响应体属于不可信内容，注意防范页面内嵌的提示注入（prompt injection），相关边界说明见 skill-data/core/references/trust-boundaries.md。
四、HAR 录制：一键导出完整流量档案
HAR（HTTP Archive）是通用的浏览器流量格式，可导入 Chrome DevTools 等工具回放分析。agent-browser 的录制流程极其简单：
agent-browser network har start # ...正常操作：open、click 等... agent-browser network har stop ./trace.har--content 三档，按需选择嵌入内容
| 参数 | 行为 |
|---|---|
--content text（默认） | 嵌入文本类响应体（JSON、HTML、JS、表单等），单体贴体上限 2 MB |
--content all | 嵌入所有响应体，二进制内容以 base64 编码 |
--content none | 只记录大小与 MIME 类型，不记录响应体 |
默认的text模式在浏览器仍缓存响应体时捕获内容，因此即使页面发生跳转，已加载接口的响应体也不会丢失——这对跨页调试非常友好。
🔒 重要：HAR 文件可能包含敏感信息
HAR 中会记录请求头、响应头、Cookie、POST 数据甚至 Bearer Token。若页面使用了 Cookie 或 API Key 认证，请把 HAR 文件当密级文件对待，分享前务必脱敏（该要求同样写在 skill-data/core/references/trust-boundaries.md 中）。
五、实用调试技巧清单 💡
SSR / 无 JS 调试：拦截全部脚本后打开页面，即可验证"不开 JS 时页面长什么样"。用
batch一次执行多条命令更高效：agent-browser batch \ '["open"]' \ '["network","route","*","--abort","--resource-type","script"]' \ '["navigate","http://localhost:3000"]' \ '["snapshot","-i"]'占位资源测试：用空 body 占位图片与字体，加速页面加载、简化视觉测试：
agent-browser network route '*' --resource-type image,font --body ''AI Agent 场景接入 MCP：启动 MCP 服务时用
--tools core,network即可让 AI 客户端获得网络路由、请求检查、HAR 等工具，配置细节见 docs/src/app/network/page.mdx 与 skill-data/core/references/commands.md。配合调试命令：网络问题往往伴随控制台报错，用
console、errors查看日志，用inspect直接打开 DevTools 深入排查，完整命令见 docs/src/app/debugging/page.mdx。底层实现：路由、额外请求头、离线模式等能力基于 CDP 协议实现，源码位于 cli/src/native/network.rs，进阶读者可以顺着它了解底层机制。
六、常见场景速查表
| 场景 | 推荐做法 |
|---|---|
| 屏蔽埋点/广告请求 | network route "**/analytics/**" --abort |
| 伪造接口返回测试空态 | network route "**/api/users" --body '{"users":[]}' |
| 验证 SSR 首屏 | 空启动 + 拦截script+navigate |
| 复现线上流量问题 | har start→ 操作 →har stop trace.har |
| 只查接口报错 | network requests --type xhr,fetch --status 4xx,5xx |
写在最后
agent-browser 的网络拦截能力把"抓包、Mock、回放"三件事压缩进了一组简洁的命令行里：路由拦截管"改"，请求日志管"查"，HAR 录制管"存"。掌握本文的三步走流程与过滤技巧，无论日常调试还是 AI Agent 自动化测试，都能事半功倍。更多细节可参阅 docs/src/app/network/page.mdx。
【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/GitHub_Trending/agen/agent-browser
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
