chrome.debugger

說明

chrome.debugger API 可做為 Chrome 遠端偵錯通訊協定的替代傳輸方式。使用 chrome.debugger 附加至一或多個分頁，即可監控網路互動、偵錯 JavaScript、變更 DOM 和 CSS 等。使用 Debuggee 屬性 tabId 以 sendCommand 定位選項卡，並透過 tabId 從 onEvent 回調路由事件。

權限

debugger

若要使用此 API，您必須在擴充功能的清單中聲明 "debugger" 權限。

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

企業政策限制

在企業設備上，某些策略可以限制擴充功能在附加偵錯器時使用全有或全無的模型（chrome.debugger.attach()）：

  • 主機限制：如果企業政策 ExtensionSettings 為擴充功能設定遭封鎖的主機 (runtime_blocked_hosts)，則所有目標都會封鎖 chrome.debugger.attach()，並顯示 "Host access is restricted by policy." 錯誤 (即使個別來源位於 runtime_allowed_hosts 中也一樣)。
  • 螢幕截圖和資料遺失防護政策：如果企業政策 DisableScreenshots 禁止擷取螢幕截圖，或資料遺失防護 (DLP) 規則適用於目標，chrome.debugger.attach() 會失敗並顯示錯誤 "Screenshot capture is restricted by policy."。

概念和用途

附加後，chrome.debugger API 可讓您將 Chrome 開發人員工具通訊協定 (CDP) 指令傳送至指定目標。本說明文件不會深入說明 CDP，如要進一步瞭解 CDP，請參閱官方 CDP 說明文件。

目標

目標代表要偵錯的項目，包括分頁、iframe 或背景工作人員。每個目標都由 UUID 識別，並具有相關聯的類型 (例如 iframe、shared_worker 等)。

在目標中，可能有多個執行環境，例如，如果 iframe 屬於相同程序，就不會取得專屬目標，而是以不同環境表示，可從單一目標存取。

受限網域

基於安全性考量，chrome.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 開始，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 }]
});

自動附加功能僅附加到目標已知的幀，而目標已知的幀僅限於與其關聯的幀的直接子幀。例如，對於幀層次結構 A -> B -> C（其中所有幀都是跨域的），對與 A 關聯的目標呼叫 Target.setAutoAttach 將導致會話也附加到 B。然而，這不是遞歸的，所以還需要呼叫 Target.setAutoAttach 才能讓 B 將會話附加到 C。

範例

若要嘗試此 API，請從 chrome-extension-samples 儲存庫安裝 debugger API 範例。

類型

Debuggee

偵錯物件標識符。必須指定 tabId、extensionId 或 targetId 中的一項。

屬性

  • extensionId

    字串 選填

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

  • tabId

    數字 選填

    您要偵錯的標籤頁的 ID。

  • targetId

    字串 選填

    調試目標的不透明 ID。

DebuggerSession

Chrome 125+

偵錯器會話標識符。tabId、extensionId 或 targetId 中必須指定一個。此外，還可以提供可選的 sessionId。如果從 onEvent 發送的參數指定了 sessionId，則表示該事件來自根偵錯會話中的子協定會話。如果在傳遞給 sendCommand 時指定了 sessionId，則它將指向根調試會話中的子協定會話。

屬性

  • extensionId

    字串 選填

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

  • sessionId

    字串 選填

    Chrome DevTools 協定工作階段的不透明 ID。識別由 tabId、extensionId 或 targetId 所識別的根會話中的子會話。

  • tabId

    數字 選填

    您要偵錯的標籤頁的 ID。

  • targetId

    字串 選填

    調試目標的不透明 ID。

DetachReason

Chrome 44 以上版本

連線終止原因。

列舉

"target_closed"

"用戶取消"

TargetInfo

偵錯目標資訊

屬性

  • 已連結

    布林值

    如果偵錯器已附加，則為真。

  • extensionId

    字串 選填

    如果 type = 'background_page'，則定義擴充 ID。

  • faviconUrl

    字串 選填

    目標網站圖示 URL。

  • id

    字串

    目標 ID。

  • tabId

    數字 選填

    標籤頁 ID，定義於 type == 'page' 時。

  • title

    字串

    目標頁面標題。

  • 目標類型。

  • 網址

    字串

    目標網址。

TargetInfoType

Chrome 44 以上版本

目標類型。

列舉

"頁"

"background_page"

"worker"

"其他"

方法

attach()

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

將偵錯器附加到指定目標。

參數

  • 目標

    調試器

    您要附加到的偵錯目標。

  • requiredVersion

    字串

    需要調試協議版本（“0.1”）。只有主版本號符合且次版本號大於或等於被偵錯系統的程式才能附加到被偵錯系統。協定版本清單可在此處取得 。

傳回

  • Promise<void>

    Chrome 96 以上版本

    一旦附加操作成功或失敗，結果就會解析。Promise 會解析，但不含任何值。如果附加失敗，則 Promise 將被拒絕。

detach()

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

從指定目標中分離偵錯器。

參數

  • 目標

    調試器

    要從中分離的調試目標。

傳回

  • 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 DevTools 時，就會發生這種情況。

參數

onEvent

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

每當偵錯目標發生問題時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

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