說明
chrome.debugger API 可做為 Chrome 遠端偵錯通訊協定的替代傳輸方式。使用 chrome.debugger 附加至一或多個分頁，即可監控網路互動、偵錯 JavaScript、變動 DOM 和 CSS 等。使用 Debuggee 屬性 tabId，以 sendCommand 為目標分頁，並透過 onEvent 回呼的 tabId 轉送事件。
權限
debugger如要使用這個 API，必須在擴充功能的資訊清單中聲明 "debugger" 權限。
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
企業政策限制
在企業裝置上，部分政策可能會限制擴充功能在附加時使用全有或全無模型附加偵錯工具 (browser.debugger.attach())：
- 主機限制：如果企業政策
ExtensionSettings為擴充功能設定封鎖的主機 (runtime_blocked_hosts)，則所有目標都會封鎖browser.debugger.attach()，並顯示"Host access is restricted by policy."錯誤 (即使個別來源位於runtime_allowed_hosts中)。 - 螢幕截圖和資料遺失防護政策：如果企業政策
DisableScreenshots禁止擷取螢幕截圖，或資料遺失防護 (DLP) 規則適用於目標，browser.debugger.attach()會失敗並顯示錯誤訊息"Screenshot capture is restricted by policy."。
概念與用途
附加後，您可以使用 browser.debugger API 將 Chrome 開發人員工具通訊協定 (CDP) 指令傳送至指定目標。本文件不會深入說明 CDP，如要進一步瞭解 CDP，請參閱官方 CDP 說明文件。
目標
目標代表要偵錯的項目，包括分頁、iframe 或背景工作。每個目標都會以 UUID 識別，並有相關聯的類型 (例如 iframe、shared_worker 等)。
目標內可能有多個執行環境，例如相同程序 iFrame 不會取得專屬目標，而是以可從單一目標存取的多個不同環境表示。
受限網域
基於安全考量，browser.debugger API 不會提供所有 Chrome 開發人員工具通訊協定網域的存取權。可用網域包括：Accessibility、
Audits、CacheStorage、Console、
CSS、Database、Debugger、DOM、
DOMDebugger、DOMSnapshot、
Emulation、Fetch、IO、Input、
Inspector、Log、Network、Overlay、
Page、Performance、
Runtime、Storage、Target、Tracing、
WebAudio 和 WebAuthn。
使用影格
影格與目標之間並非一對一對應。在單一分頁中，多個相同程序影格可能會共用同一個目標，但使用不同的執行環境。另一方面，系統可能會為程序外 iframe 建立新目標。
如要附加至所有影格，您必須分別處理每種影格：
監聽
Runtime.executionContextCreated事件，找出與相同程序框架相關聯的新執行環境。按照步驟附加至相關目標，找出程序外影格。
附加至相關目標
連線至目標後，您可能想連線至其他相關目標，包括程序外子項影格或相關聯的工作人員。
自 Chrome 125 起，browser.debugger API 支援扁平工作階段。這樣您就能將其他目標新增為主要偵錯工作階段的子項，並傳送訊息給這些目標，不必再呼叫 browser.debugger.attach。不過，您可以在呼叫 browser.debugger.sendCommand 時新增 sessionId 屬性，識別要傳送指令的子項目標。
如要自動附加至程序外子影格，請先為 Target.attachedToTarget 事件新增接聽程式：
browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
}
});
接著，將 flatten 選項設為 true，然後傳送 Target.setAutoAttach 指令，啟用「自動附加」：
await browser.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 存放區安裝偵錯工具 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」
「canceled_by_user」
TargetInfo
偵錯目標資訊
屬性
-
已連結
布林值
如果已附加偵錯工具，則為 True。
-
extensionId
字串 選填
擴充功能 ID (如果 type = 'background_page'，則為已定義)。
-
faviconUrl
字串 選填
目標網站小圖示網址。
-
id
字串
目標 ID。
-
tabId
數字 選填
分頁 ID，如果 type == 'page'，則會定義這個 ID。
-
title
字串
目標網頁標題。
-
目標類型。
-
網址
字串
目標網址。
TargetInfoType
目標類型。
列舉
「page」
「background_page」
「worker」
「other」
方法
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
): Promise<void>
將偵錯工具附加至指定目標。
參數
-
目標
要附加的偵錯目標。
-
requiredVersion
字串
需要偵錯通訊協定版本「0.1」。您只能附加至主要版本相符，且子版本大於或等於的偵錯目標。如要查看通訊協定版本清單，請按這裡。
傳回
-
Promise<void>
Chrome 96 以上版本附加作業成功或失敗時，系統會解析這個項目。這個 Promise 會解析，但不含任何值。如果附加失敗，承諾就會遭到拒絕。
參數
-
目標
要中斷連結的偵錯目標。
傳回
-
Promise<void>
Chrome 96 以上版本在卸離作業成功或失敗時解析。這個 Promise 會解析，但不含任何值。如果卸離失敗，承諾就會遭到拒絕。
傳回
-
Promise<TargetInfo[]>
Chrome 96 以上版本
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
): Promise<object | undefined>
將指定指令傳送至偵錯目標。
參數
-
要傳送指令的偵錯目標。
-
方法
字串
方法名稱。應為遠端偵錯通訊協定定義的方法之一。
-
commandParams
物件 選填
含有要求參數的 JSON 物件。這個物件必須符合指定方法的遠端偵錯參數架構。
傳回
-
Promise<object | undefined>
Chrome 96 以上版本回應主體。如果在發布訊息時發生錯誤，系統會拒絕 Promise。
事件
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
瀏覽器終止分頁的偵錯工作階段時觸發。當分頁關閉或為附加的分頁叫用 Chrome 開發人員工具時，就會發生這種情況。
參數
-
callback
函式
callback參數看起來像這樣：(source: Debuggee, reason: DetachReason) => void
-
來源
-
原因
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
每當偵錯目標發生問題時，就會觸發插碼事件。
參數
-
callback
函式
callback參數看起來像這樣：(source: DebuggerSession, method: string, params?: object) => void
-
方法
字串
-
params
物件 選填