browser.debugger

說明

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、Profiler、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");
  }
});

接著，傳送 Target.setAutoAttach 指令並將 flatten 選項設為 true，即可啟用「自動附加」：

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 存放區安裝 debugger API 範例。

類型

Debuggee

偵錯目標 ID。必須指定 tabId、extensionId 或 targetId

屬性

  • extensionId

    字串 選填

    您要偵錯的擴充功能 ID。只有在使用 --silent-debugger-extension-api 指令列切換時，才能附加至擴充功能背景頁面。

  • tabId

    數字 選填

    要偵錯的分頁 ID。

  • targetId

    字串 選填

    偵錯目標的不透明 ID。

DebuggerSession

Chrome 125 以上版本

偵錯工具工作階段 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

Chrome 44 以上版本

連線終止原因。

列舉

「target_closed」

「canceled_by_user」

TargetInfo

偵錯目標資訊

屬性

  • 已連結

    布林值

    如果已附加偵錯工具，則為 True。

  • extensionId

    字串 選填

    擴充功能 ID (如果 type = 'background_page'，則為必要欄位)。

  • faviconUrl

    字串 選填

    目標網站小圖示網址。

  • id

    字串

    目標 ID。

  • tabId

    數字 選填

    分頁 ID，如果 type == 'page'，則為已定義。

  • title

    字串

    目標網頁標題。

  • 目標類型。

  • 網址

    字串

    目標網址。

TargetInfoType

Chrome 44 以上版本

目標類型。

列舉

「page」

「background_page」

「worker」

「other」

方法

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

將偵錯工具附加至指定目標。

參數

  • 目標

    Debuggee

    要附加的偵錯目標。

  • requiredVersion

    字串

    必要偵錯通訊協定版本 (「0.1」)。您只能附加至主要版本相符，且子版本大於或等於的偵錯目標。如要查看通訊協定版本清單，請按這裡。

傳回

  • Promise<void>

    Chrome 96 以上版本

    附加作業成功或失敗時，系統會解析這個物件。Promise 會解析，但不含任何值。如果附加失敗，系統會拒絕 Promise。

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

從指定目標中分離偵錯工具。

參數

  • 目標

    Debuggee

    要中斷連結的偵錯目標。

傳回

  • Promise<void>

    Chrome 96 以上版本

    在卸離作業成功或失敗時解析。Promise 會解析，但不含任何值。如果卸離失敗，承諾就會遭到拒絕。

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

傳回可用的偵錯目標清單。

傳回

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

將指定指令傳送至偵錯目標。

參數

  • 要將指令傳送至的偵錯目標。

  • 方法

    字串

    方法名稱。應為遠端偵錯通訊協定定義的方法之一。

  • commandParams

    object 選填

    含有要求參數的 JSON 物件。這個物件必須符合指定方法的遠端偵錯參數架構。

傳回

  • Promise<object | undefined>

    Chrome 96 以上版本

    回應主體。如果發布訊息時發生錯誤，系統會拒絕 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