chrome.debugger

说明

chrome.debugger API 可作为 Chrome 远程调试协议的替代传输方式。使用 chrome.debugger 附加到一个或多个标签页，以检测网络互动、调试 JavaScript、更改 DOM 和 CSS 等。使用 Debuggee 属性 tabId 以 sendCommand 为目标标签页，并通过 onEvent 回调中的 tabId 路由事件。

权限

debugger

您必须在扩展程序的清单中声明 "debugger" 权限，才能使用此 API。

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

概念和用法

附加后，chrome.debugger API 可让您向指定目标发送 Chrome DevTools Protocol (CDP) 命令。深入说明 CDP 超出了本文档的范围，如需详细了解 CDP，请参阅 CDP 官方文档。

目标

目标表示正在调试的对象，可以包括标签页、iframe 或 worker。每个目标都由 UUID 标识，并具有关联的类型（例如 iframe、shared_worker 等）。

在一个目标中，可能存在多个执行上下文，例如，同一进程 iframe 不会获得唯一的目标，而是表示为可从单个目标访问的不同上下文。

受限网域

出于安全考虑，chrome.debugger API 不提供对所有 Chrome DevTools 协议网域的访问权限。可用的网域包括：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。

使用帧

帧与目标之间不存在一对一的映射关系。在单个标签页中，多个相同进程的框架可能共享同一目标，但使用不同的执行上下文。另一方面，可能会为进程外 iframe 创建新目标。

如需附加到所有帧，您需要分别处理每种类型的帧：

  • 监听 Runtime.executionContextCreated 事件，以识别与同一进程框架关联的新执行上下文。

  • 按照附加到相关目标中的步骤操作，以识别进程外帧。

连接到目标后，您可能需要连接到更多相关目标，包括进程外子框架或关联的工作人员。

从 Chrome 125 开始，chrome.debugger API 支持扁平会话。这样一来，您就可以将其他目标作为子级添加到主调试器会话，并向它们发送消息，而无需再次调用 chrome.debugger.attach。不过，您可以在调用 chrome.debugger.sendCommand 时添加 sessionId 属性，以标识要向哪个子目标发送命令。

如需自动附加到进程外子框架，请先为 Target.attachedToTarget 事件添加监听器：

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

然后，通过发送 Target.setAutoAttach 命令并将 flatten 选项设置为 true 来启用自动附加：

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

自动附加仅附加到目标知道的帧，这些帧仅限于与其关联的帧的直接子帧。例如，如果框架层次结构为 A -> B -> C（其中所有框架均为跨源），则针对与 A 关联的目标调用 Target.setAutoAttach 会导致会话也附加到 B。不过，这并非递归调用，因此还需要为 B 调用 Target.setAutoAttach，才能将该会话附加到 C。

示例

如需试用此 API，请从 chrome-extension-samples 代码库中安装 debugger API 示例。

类型

Debuggee

调试对象标识符。必须指定 tabId、extensionId 或 targetId

属性

  • extensionId

    字符串（选填）

    您要调试的扩展程序的 ID。只有在使用 --silent-debugger-extension-api 命令行开关时，才能附加到扩展程序后台页面。

  • tabId

    number 可选

    您要调试的标签页的 ID。

  • targetId

    字符串（选填）

    调试目标的不透明 ID。

DebuggerSession

Chrome 125 及更高版本

调试器会话标识符。必须指定 tabId、extensionId 或 targetId 中的一个。此外，还可以提供可选的 sessionId。如果为从 onEvent 发送的实参指定了 sessionId，则表示相应事件来自根调试对象会话中的子协议会话。如果传递给 sendCommand 时指定了 sessionId，则它会以根调试会话中的子协议会话为目标。

属性

  • extensionId

    字符串（选填）

    您要调试的扩展程序的 ID。只有在使用 --silent-debugger-extension-api 命令行开关时，才能附加到扩展程序后台页面。

  • sessionId

    字符串（选填）

    Chrome DevTools Protocol 会话的不透明 ID。用于标识由 tabId、extensionId 或 targetId 标识的根会话中的子会话。

  • tabId

    number 可选

    您要调试的标签页的 ID。

  • targetId

    字符串（选填）

    调试目标的不透明 ID。

DetachReason

Chrome 44 及更高版本

连接终止原因。

枚举

"target_closed"

"canceled_by_user"

TargetInfo

调试目标信息

属性

  • 已挂接

    布尔值

    如果调试器已附加，则为 True。

  • extensionId

    字符串（选填）

    扩展程序 ID，如果 type = 'background_page'，则定义该 ID。

  • faviconUrl

    字符串（选填）

    目标网站图标网址。

  • id

    字符串

    目标 ID。

  • tabId

    number 可选

    标签页 ID，如果 type == 'page'，则定义该 ID。

  • title

    字符串

    目标网页标题。

  • 目标类型。

  • 网址

    字符串

    目标网址。

TargetInfoType

Chrome 44 及更高版本

目标类型。

枚举

“page”

"background_page"

“worker”

“其他”

方法

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

将调试器附加到指定的目标。

参数

  • 要附加到的调试目标。

  • requiredVersion

    字符串

    必需的调试协议版本（“0.1”）。只能附加到主要版本匹配且次要版本大于或等于的调试对象。点击此处可查看协议版本列表。

返回

  • Promise<void>

    Chrome 96 及更高版本

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

将调试器与指定目标分离。

参数

返回

  • Promise<void>

    Chrome 96 及更高版本

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

返回可用调试目标的列表。

返回

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

将指定命令发送到调试目标。

参数

  • 您要向其发送命令的调试目标。

  • method

    字符串

    方法名称。应该是 远程调试协议定义的方法之一。

  • commandParams

    对象（可选）

    包含请求参数的 JSON 对象。此对象必须符合给定方法的远程调试参数方案。

返回

  • Promise<object | undefined>

    Chrome 96 及更高版本

事件

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

当浏览器终止标签页的调试会话时触发。当标签页正在关闭或 Chrome 开发者工具正在为附加的标签页调用时，会发生这种情况。

参数

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

每当调试目标问题检测事件时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (source: DebuggerSession, method: string, params?: object) => void