chrome.debugger

说明

chrome.debugger API 可用作 Chrome 远程调试协议的替代传输服务。使用 chrome.debugger 附加到一个或多个标签页，以便对网络交互进行插桩、调试 JavaScript、转变 DOM 和 CSS 等。使用 Debuggee 属性 tabId 可定位具有 sendCommand 的标签页，并通过 tabId 从 onEvent 回调对事件进行路由。

权限

debugger

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

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

概念和用法

附加后，您可以通过 chrome.debugger API 发送 Chrome 开发者工具协议 (CDP) 命令发送到指定目标。深入解释 CDP 不在讨论范围内 如需详细了解 CDP，请参阅 官方 CDP 文档。

目标

目标表示正在调试的内容，可能包括标签页、 iframe 或 worker。每个目标都由 UUID 进行标识，并且具有 类型（例如 iframe、shared_worker 等）。

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

受限网域

出于安全考虑，chrome.debugger API 不提供对所有 Chrome 开发者工具的访问权限 协议域。可用的网域包括：无障碍、 Audits、CacheStorage、Console、 CSS、Database、Debugger、DOM、 DOMDebugger、DOMSnapshot、 模拟、提取、IO、输入、 Inspector、Log、Network、Overlay、 页面、性能、性能分析器、 运行时、存储、目标、跟踪、 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 }]
});

示例

若要试用此 API，请安装 chrome-extension-samples 中的调试程序 API 示例 存储库

类型

Debuggee

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

属性

• extensionId

  字符串（可选）

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

• tabId

  编号（选填）

  您要调试的标签页的 ID。

• targetId

  字符串（可选）

  调试目标的不透明 ID。

DebuggerSession

Chrome 125 及更高版本

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

属性

• extensionId

  字符串（可选）

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

• sessionId

  字符串（可选）

  Chrome 开发者工具协议会话的不透明 ID。识别根会话中的子会话，由 tabId、extensionId 或 targetId 标识。

• tabId

  编号（选填）

  您要调试的标签页的 ID。

• targetId

  字符串（可选）

  调试目标的不透明 ID。

DetachReason

Chrome 44 及更高版本

连接终止原因。

枚举

"target_closed"

"canceled_by_user"

TargetInfo

调试目标信息

属性

• 已挂接

  布尔值

  如果已连接调试程序，则为 true。

• extensionId

  字符串（可选）

  扩展程序 ID，在 type = 'background_page' 时定义。

• faviconUrl

  字符串（可选）

  目标网站图标网址。

• id

  字符串

  目标 ID。

• tabId

  编号（选填）

  标签页 ID，在类型 ==“page”时定义。

• 标题

  字符串

  目标页面标题。

• 类型

  TargetInfoType

  定位类型。

• 网址

  字符串

  目标网址。

TargetInfoType

Chrome 44 及更高版本

定位类型。

枚举

“页面”

"background_page"

"worker"

“其他”

方法

attach()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

将调试程序连接到给定目标。

参数

• 目标

  调试对象

  要附加的调试目标。

• requiredVersion

  字符串

  所需的调试协议版本（“0.1”）。一个只能连接到具有匹配主要版本和更高或更低版本的次要版本的调试对象。协议版本列表可在此处获取。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

detach()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

将调试程序与给定目标分离。

参数

• 目标

  调试对象

  您要从中分离的调试目标。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getTargets()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.debugger.getTargets(
  callback?: function,
)

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (result: TargetInfo[]) => void

  • 结果

    TargetInfo[]

    与可用调试目标对应的 TargetInfo 对象数组。

返回

• Promise&lt;TargetInfo[]&gt;

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

sendCommand()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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

参数

• 目标

  DebuggerSession

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

• method

  字符串

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

• commandParams

  对象（可选）

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

• callback

  函数（可选）

  callback 参数如下所示：

  (result?: object) => void

  • 结果

    对象（可选）

    JSON 对象。响应的结构因方法名称而异，并由“返回值”属性。

返回

• Promise&lt;object |未定义>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onDetach

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (source: Debuggee, reason: DetachReason) => void

  • 来源

    调试对象

  • reason

    DetachReason

onEvent

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

每当调试目标问题插桩事件时触发。

参数

• callback

  函数

  callback 参数如下所示：

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

  • 来源

    DebuggerSession

  • method

    字符串

  • params

    对象（可选）