用 CDP 做一次网络观察:Chrome 扩展的会话与清理
网页点击后有没有发出请求,不能只看 Console 中的一条日志。Chrome 扩展可以用 chrome.debugger 建立 CDP 会话,短时间观察指定标签页的网络事件。这个例子只收集响应路径、状态和类型,不读取 Cookie、请求头或响应正文;先让一条完整会话跑通,再看其他命令属于哪一层能力。
会话从用户动作开始
扩展的 manifest 声明 debugger 权限,由用户点击图标后调用 attach,再启用 Network。事件从全局 onEvent 分发,需要同时确认 tabId 和 sessionId。结束时先停止接收自己的事件,再 detach;用户取消或浏览器主动断开,则走 onDetach 清理。Promise 形式 API 与子会话的版本边界见 Chrome debugger 文档。
根 target 不等于整个标签页的所有执行位置。同进程 frame 可以有多个 execution context,跨进程 frame/worker 又可能成为子 target。示例只观察根会话,不据此宣布覆盖全部 iframe 请求。
在本机加载示例
- 从配套源码保存 copy 目录的三个文件,在 chrome://extensions 打开开发者模式,加载该目录。
- 打开自己控制的 HTTP 测试页面,再从扩展管理页打开 service worker 控制台。
- 点击扩展图标,徽标 ON 表示已开始;在五秒内操作测试页发出请求。响应摘要显示在 worker 控制台。
- 五秒后自动结束,再次点击也可提前停止。确认调试提示消失,并检查随后请求不再被这次会话记录。
示例不主动刷新页面,也不补采样之前的请求。受限页面、企业策略或已有调试会话可能使 attach 失败;应该按错误排查,不能当成页面没有请求。
调用方式
下面保留真正决定会话的片段,完整实现还负责事件过滤、失败清理和迟到连接。
const target = { tabId };
await chrome.debugger.attach(target, '1.3');
try {
await chrome.debugger.sendCommand(target, 'Network.enable');
// 由 onEvent 接收当前会话的 Network.responseReceived。
} finally {
// 实际观察结束或启动失败时执行,不是启用后立刻结束。
await chrome.debugger.detach(target);
}
这里的 try/finally 表达资源归属,省略了观察窗口。完整示例在 attach 前注册监听,启用失败后移除监听并释放已取得的连接;如果用户在 attach 完成前停止,迟到的成功连接也会被释放。完整代码见网络观察源码与回归弹窗。
从事件中保留最小结果
Network.responseReceived 中的 requestId 用于关联同一请求的后续事件,response 给出这次响应的信息。示例只接收 HTTP(S) URL,保留 origin/pathname、状态与资源类型,去掉查询和片段;data URL 的内嵌内容不会作为路径输出。路径本身仍可能带业务信息,所以应使用自己的测试页。其他请求阶段、加载失败和响应正文读取是不同事件与命令,见 Network 协议定义。
只在 responseReceived 时立即请求完整正文,可能遇到内容尚未完成或已不可用的问题。需要正文的调试器应按 requestId 跟踪 loadingFinished/失败,再处理编码、大小、生命周期与权限;本例没有实现正文采集。
它开放的是受限 DevTools 能力
为了安全,chrome.debugger 并不开放全部 CDP domain。Chrome 官方文档 单独列了扩展可以访问的 domain,包括 Accessibility、Audits、CacheStorage、Console、CSS、Database、Debugger、DOM、DOMDebugger、DOMSnapshot、Emulation、Fetch、IO、Input、Inspector、Log、Network、Overlay、Page、Performance、Profiler、Runtime、Storage、Target、Tracing、WebAudio、WebAuthn 等。
这些 domain 覆盖输入、运行时、DOM、CSS、网络、页面、环境模拟、性能追踪和存储缓存。
本节按调试能力列出 CDP 命令示例,只保留关键调用形状,省略 attach、detach、callback 返回值读取和错误处理;完整调用方式见正文的「调用方式」一节。
输入和用户动作
Input.* 负责模拟键盘、鼠标、触摸等输入。典型关键词是:真实快捷键、复制、粘贴、鼠标、拖拽、触摸、canvas、复杂编辑器、虚拟表格、非标准选区。
这类能力和普通脚本派发事件的差别很大。普通脚本通常会写:
element.dispatchEvent(new KeyboardEvent('keydown', { key: 'c', metaKey: true }));
或者:
document.execCommand('copy');
这类操作仍然停在页面脚本层。根据 MDN 对 Event.isTrusted 的说明,通过 dispatchEvent() 派发的事件会被标记为非可信事件。复杂 Web 应用完全可以不把这类合成事件当成真实用户输入。
CDP 的 Input.dispatchKeyEvent 走的是浏览器调试层的输入命令。它支持 modifiers,其中 Meta/Command 是 4,Ctrl 是 2;也支持随键盘事件发送编辑命令,例如 copy、selectAll 这一类和编辑器相关的命令。
迁移到 debugger 后,写法变成向浏览器输入层发送命令:
chrome.debugger.sendCommand({ tabId }, 'Input.dispatchKeyEvent', {
type: 'rawKeyDown',
key: 'c',
code: 'KeyC',
windowsVirtualKeyCode: 67,
modifiers: 4,
commands: ['copy'],
});
页面运行时
Runtime.*、Console.*、Debugger.* 负责页面 JavaScript 运行时、Console、断点和执行上下文。
这类能力适合处理:
- 要在页面上下文里执行一段表达式。
- 要读取复杂框架运行态。
- 要监听 Console 输出或异常。
- 要判断一个跨 iframe / worker 的执行上下文在哪里。
普通 chrome.scripting.executeScript 也能往页面注入脚本,但 CDP 的运行时能力更接近 DevTools Console。能力越接近 DevTools,越要注意边界:不能拿它去读取和任务无关的敏感数据,也不要把它当成绕过页面正常权限和产品边界的工具。
普通扩展 API 更像「注入一段函数到页面」:
chrome.scripting.executeScript({
target: { tabId },
func: () => window.location.href,
});
CDP 的 Runtime.evaluate 更像 DevTools Console 里的表达式执行:
chrome.debugger.sendCommand({ tabId }, 'Runtime.evaluate', {
expression: 'window.location.href',
returnByValue: true,
});
DOM、CSS 和布局
DOM.*、CSS.*、DOMSnapshot.*、Overlay.* 对应 DevTools Elements 面板附近的能力。它们适合用来检查 DOM 树、样式规则、节点快照、布局盒模型、元素高亮和渲染定位。
如果只是 document.querySelector() 能解决的问题,没有必要升级到 debugger。但如果问题发生在 Shadow DOM、复杂 iframe、虚拟渲染、样式来源难以定位,或者要复用 DevTools 的节点高亮和快照能力,CDP 可以作为候选方案。
普通脚本通常直接读 DOM:
chrome.scripting.executeScript({
target: { tabId },
func: () => document.querySelector('.submit')?.getBoundingClientRect(),
});
CDP 可以先拿 DOM 树,再用 node id 继续查询样式、盒模型或高亮节点:
chrome.debugger.sendCommand({ tabId }, 'DOM.getDocument', { depth: 1 });
chrome.debugger.sendCommand({ tabId }, 'DOM.querySelector', {
nodeId: documentNodeId,
selector: '.submit',
});
chrome.debugger.sendCommand({ tabId }, 'DOM.getBoxModel', { nodeId });
网络和接口
Network.*、Fetch.*、IO.* 对应网络观察、请求拦截、响应读取和流式内容处理。
它们适合处理:
- 观察页面实际发出的请求。
- 查看 headers、status、response、preflight、缓存状态。
- 在调试工具里对接口做 mock 或拦截。
- 下载或读取 DevTools 网络层看到的内容。
Chrome Extension 本身也有 declarativeNetRequest、webRequest 等网络相关 API。选择时要看需求目标:如果是长期、稳定、面向发布的网络规则,优先考虑标准扩展 API;如果是内部调试、临时观测、需要贴近 DevTools 的 Network 视角,CDP 更直接。
这部分能力很强,使用边界也要更严。不要长期监听无关站点,不要采集用户敏感流量,不要把内部调试工具做成默认后台监控。
普通扩展能力更适合声明式规则或稳定拦截:
chrome.declarativeNetRequest.updateDynamicRules({
addRules: [rule],
removeRuleIds: [rule.id],
});
CDP 更接近 DevTools Network。它可以打开网络观测,再从 chrome.debugger.onEvent 里接收网络事件:
chrome.debugger.sendCommand({ tabId }, 'Network.enable');
chrome.debugger.onEvent.addListener((source, method, params) => {
if (source.tabId !== tabId || source.sessionId || method !== 'Network.responseReceived') {
return;
}
console.log(params.response.url, params.response.status);
});
页面控制、target 和 frame
Page.*、Target.* 负责页面导航、reload、生命周期、frame tree、截图、PDF、target 管理等能力。
Chrome debugger 文档 提到,一个 tab 里可能有多个 execution context,跨进程 iframe 还可能成为新的 target。Chrome 125 以后,chrome.debugger 支持 flat sessions,可以在同一个调试会话里定位子 target。
因此,如果问题发生在 iframe、worker、跨域嵌套页面里,不能只问「attach 了 tab 吗」,还要问「命令发给了哪个 target / session」。
普通标签页控制一般用 chrome.tabs:
chrome.tabs.reload(tabId);
在需要跟踪页面生命周期或 target 状态的调试任务中,可以用 CDP 的 Page.* 重载页面、捕获截图:
chrome.debugger.sendCommand({ tabId }, 'Page.reload', { ignoreCache: true });
chrome.debugger.sendCommand({ tabId }, 'Page.captureScreenshot', {
format: 'png',
fromSurface: true,
});
环境模拟
Emulation.* 和部分 Network.* 能模拟 viewport、设备特征、触摸能力、UA、地理位置、时区、语言、网络条件等。
这类能力适合排查「只有某个 WebView / 移动设备 / 特定语言 / 特定网络环境才复现」的问题。它和普通响应式调试不同,因为它能更接近 DevTools 设备模拟层,影响范围也不止 CSS 宽度。
普通页面调试经常只改视口宽度:
window.resizeTo(390, 844);
CDP 可以把设备指标、触摸能力、时区和网络条件放在同一套自动化里:
chrome.debugger.sendCommand({ tabId }, 'Emulation.setDeviceMetricsOverride', {
width: 390,
height: 844,
deviceScaleFactor: 3,
mobile: true,
});
chrome.debugger.sendCommand({ tabId }, 'Emulation.setTimezoneOverride', {
timezoneId: 'Asia/Shanghai',
});
存储、缓存和性能
Storage.*、CacheStorage.*、Performance.*、Profiler.*、Tracing.* 可以用于缓存、存储、性能指标、CPU profile、trace 等调试任务。
这里要区分两种需求:
- 如果只是给本地开发页写一段明确的
localStorage,普通chrome.scripting.executeScript更合适。 - 如果要理解页面缓存、Service Worker、CacheStorage、运行性能和 trace,CDP 才更接近问题发生的位置。
普通 localStorage 写入不需要上 CDP:
chrome.scripting.executeScript({
target: { tabId },
func: (value) => localStorage.setItem('i18n-demo/i18n', value),
args: [cacheValue],
});
CDP 更适合处理缓存和性能视角的问题:
chrome.debugger.sendCommand({ tabId }, 'Performance.enable');
chrome.debugger.sendCommand({ tabId }, 'Performance.getMetrics');
chrome.debugger.sendCommand({ tabId }, 'Storage.clearDataForOrigin', {
origin: 'http://localhost:8012',
storageTypes: 'cache_storage,indexeddb',
});
实际验证范围
2026-11-02,在独立 Chromium 156.0.8078.4 配置中加载这份扩展,通过 service worker 程序化调用同一个观察模块:真实页面 Fetch 的响应可见,查询字符串被去除,stop 后的新响应不再进入记录。七个本地测试另覆盖过滤、启动失败、主动断开、迟到连接,以及工具栏连续点击的会话互斥。这次没有操作工具栏鼠标点击,也没有验证商店安装、跨 target 或登录页面,原始摘要见浏览器验证记录弹窗。
结束会话也是功能的一部分
长期保留 debugger 会话会扩大观察范围,也会影响扩展 worker 生命周期。Chrome 118 起活动调试会话可以保持 worker 活跃,但仍应监听意外断开,见 service worker 生命周期。这个示例将窗口固定为五秒、输出上限为 100 条,展示的是短时诊断,跨 target、长期采集与内容持久化需要单独设计。
网络观察源码与回归
工作区提供 manifest、worker、会话管理与无依赖测试。在源码包根目录运行 pnpm test。测试覆盖根会话过滤、启动失败、主动断开和 attach 迟到后的释放;真实浏览器验证范围另行记录。
CDP 观察模块的真实浏览器验证
{
"browser": "156.0.8078.4",
"page": "127.0.0.1 的隔离 HTTP 页面",
"observed": [
{
"url": "http://fixture.local/data",
"status": 200,
"type": "Fetch"
}
],
"checks": [
"真实扩展 service worker 使用 chrome.debugger",
"attach + Network.enable",
"页面真实 Fetch 响应可见",
"查询字符串被去除",
"stop 后新响应不再进入记录"
],
"scope": "程序化调用同一 observer 模块;没有验证工具栏鼠标点击、商店安装、跨 target 或用户登录页面"
}