說明
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 開發人員工具通訊協定 (CDP) 指令傳送至指定目標。本說明文件無法深入說明 CDP 的運作方式。如要進一步瞭解 CDP,請參閱官方 CDP 文件。
目標
目標代表正在偵錯的項目,包括分頁、iframe 或工作站。每個目標都能透過 UUID 識別,且具有相關聯的類型 (例如 iframe
、shared_worker
等)。
目標內可能有多個執行結構定義,例如相同的程序 iframe 不會取得不重複目標,而是表示為可從單一目標存取的不同結構定義。
受限網域
基於安全考量,chrome.debugger
API 不會提供所有 Chrome 開發人員工具通訊協定網域的存取權。可用的網域如下:Accessibility、Audits、CacheStorage、Console、CSS、資料庫、Debugger、DOM、DOMDebuggerWebAudioWebAuthn
使用框架
沒有任何影格與目標的對應。在單一分頁中,多個相同的程序框架可能會共用相同的目標,但使用不同的執行內容。另一方面,系統可能會為非程序的 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");
}
});
接著,傳送 flatten
選項設為 true
的 Target.setAutoAttach
指令,藉此啟用自動附加功能:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
示例
如要試用這個 API,請從 chrome-extension-samples 存放區安裝偵錯工具 API 範例。
類型
Debuggee
偵錯目標 ID。必須指定 tabId、extensionId 或 targetId
屬性
-
extensionId
字串 選用
要偵錯的擴充功能 ID。只有在使用
--silent-debugger-extension-api
指令列切換按鈕時,才能附加至擴充功能背景頁面。 -
tabId
數字 選填
要偵錯的分頁 ID。
-
targetId
字串 選用
偵錯目標的不透明 ID。
DebuggerSession
偵錯工具工作階段 ID。必須指定 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"
TargetInfo
偵錯目標資訊
屬性
-
已連結
boolean
如果已附加偵錯工具,則為 true。
-
extensionId
字串 選用
擴充功能 ID,在類型為「background_page」時定義。
-
faviconUrl
字串 選用
目標網站小圖示網址。
-
id
字串
目標 ID。
-
tabId
數字 選填
分頁 ID,在 type == 'page' 時定義。
-
title
字串
目標網頁標題。
-
目標類型。
-
網址
字串
目標網址。
TargetInfoType
目標類型。
列舉
"background_page"
方法
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
將偵錯工具附加至指定目標。
參數
-
目標
對要附加的目標偵錯。
-
requiredVersion
字串
必填的偵錯通訊協定版本 (「0.1」)。一個只能附加至與主要版本相符的偵錯目標版本,且子版本大於或等於子版本。您可以在這裡取得通訊協定版本清單。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
參數
-
目標
針對要卸離的目標進行偵錯。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
傳回可用的偵錯目標清單。
參數
-
回呼
函式選用
callback
參數如下所示:(result: TargetInfo[]) => void
-
結果
與可用偵錯目標相對應的 TargetInfo 物件陣列。
-
傳回
-
Promise<TargetInfo[]>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
將指定的指令傳送至偵錯目標。
參數
-
針對要傳送指令的目標偵錯。
-
method
字串
方法名稱。這必須是遠端偵錯通訊協定定義的其中一種方法。
-
commandParams
物件選用
包含要求參數的 JSON 物件。這個物件必須符合指定方法的遠端偵錯參數配置。
-
回呼
函式選用
callback
參數如下所示:(result?: object) => void
-
結果
物件選用
內含回應的 JSON 物件。回應結構因方法名稱而異,且是由遠端偵錯通訊協定中指令說明的「returns」屬性所定義。
-
傳回
-
Promise<object | undefined>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
瀏覽器終止分頁偵錯工作階段時觸發。當該分頁正在關閉,或正在為附加的分頁叫用 Chrome 開發人員工具時,就會發生這個問題。
參數
-
回呼
功能
callback
參數如下所示:(source: Debuggee, reason: DetachReason) => void
-
來源
-
原因
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
每當目標問題檢測事件進行偵錯時就會觸發。
參數
-
回呼
功能
callback
參數如下所示:(source: DebuggerSession, method: string, params?: object) => void
-
method
字串
-
params
物件選用