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 开发者工具协议网域的访问权限。可用的网域包括：Accessibility、Audits、CacheStorage、Console4、CSS、Database、Debugger、DOM、DOMDebugger、Audits、CacheStorage、Console、{30 和对事件{6{60{600、对事件进行监控、对事件进行监控、执行请求或执行事务）。将事件{6{60、将 DOMDOMSnapshotWebAudioWebAuthn

示例

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

类型

Debuggee

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

属性

  • extensionId

    字符串（可选）

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

  • tabId

    数字可选

    您要调试的标签页的 ID。

  • targetId

    字符串（可选）

    调试目标的不透明 ID。

DebuggerSession

待处理

调试程序会话标识符。必须指定 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

调试目标信息

属性

  • 已挂接

    boolean

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

  • extensionId

    字符串（可选）

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

  • faviconUrl

    字符串（可选）

    目标网站图标网址。

  • id

    string

    目标 ID。

  • tabId

    数字可选

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

  • title

    string

    目标网页标题。

  • 目标类型。

  • 网址

    string

    目标网址。

TargetInfoType

Chrome 44 及更高版本

目标类型。

枚举

"background_page"

"worker"

方法

attach()

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

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

参数

  • 目标

    调试对象

    要附加的调试目标。

  • requiredVersion

    string

    所需的调试协议版本（“0.1”）。只能连接到具有与主要版本匹配及更高或相等的次要版本的调试对象。您可以点击此处获取协议版本列表。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

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

detach()

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

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

参数

  • 目标

    调试对象

    您要与之分离的调试目标。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

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

getTargets()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (result: TargetInfo[])=>void

    • 结果

      TargetInfo[]

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

返回

  • Promise<TargetInfo[]>

    Chrome 96 及更高版本

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

sendCommand()

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

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

参数

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

  • method

    string

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

  • commandParams

    对象（可选）

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (result?: object)=>void

    • 结果

      对象（可选）

      JSON 对象。响应的结构因方法名称而异，并由远程调试协议中命令说明的“returns”属性定义。

返回

  • Promise<object|undefined>

    Chrome 96 及更高版本

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

活动

onDetach

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

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

参数

onEvent

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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