说明
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
调试程序会话标识符。必须指定 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
连接终止原因。
枚举
"target_closed"
"canceled_by_user"
TargetInfo
调试目标信息
属性
-
已挂接
布尔值
如果已连接调试程序,则为 true。
-
extensionId
字符串(可选)
扩展程序 ID,在 type = 'background_page' 时定义。
-
faviconUrl
字符串(可选)
目标网站图标网址。
-
id
字符串
目标 ID。
-
tabId
编号(选填)
标签页 ID,在类型 ==“page”时定义。
-
标题
字符串
目标页面标题。
-
定位类型。
-
网址
字符串
目标网址。
TargetInfoType
定位类型。
枚举
“页面”
"background_page"
"worker"
“其他”
方法
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
将调试程序连接到给定目标。
参数
-
目标
要附加的调试目标。
-
requiredVersion
字符串
所需的调试协议版本(“0.1”)。一个只能连接到具有匹配主要版本和更高或更低版本的次要版本的调试对象。协议版本列表可在此处获取。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
将调试程序与给定目标分离。
参数
-
目标
您要从中分离的调试目标。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
返回可用调试目标的列表。
参数
-
callback
函数(可选)
callback
参数如下所示:(result: TargetInfo[]) => void
-
结果
与可用调试目标对应的 TargetInfo 对象数组。
-
返回
-
Promise<TargetInfo[]>
Chrome 96 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
将给定的命令发送到调试目标。
参数
-
您要向其发送命令的调试目标。
-
method
字符串
方法名称。应该是远程调试协议定义的方法之一。
-
commandParams
对象(可选)
包含请求参数的 JSON 对象。此对象必须符合给定方法的远程调试参数架构。
-
callback
函数(可选)
callback
参数如下所示:(result?: object) => void
-
结果
对象(可选)
JSON 对象。响应的结构因方法名称而异,并由“返回值”属性。
-
返回
-
Promise<object |未定义>
Chrome 96 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
事件
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
浏览器终止标签页的调试会话时触发。关闭标签页或为附加的标签页调用 Chrome 开发者工具时会出现这种情况。
参数
-
callback
函数
callback
参数如下所示:(source: Debuggee, reason: DetachReason) => void
-
来源
-
reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
每当调试目标问题插桩事件时触发。
参数
-
callback
函数
callback
参数如下所示:(source: DebuggerSession, method: string, params?: object) => void
-
method
字符串
-
params
对象(可选)