browser.debugger

說明

chrome.debugger API 是 Chrome 遠端偵錯通訊協定的替代傳輸方式。使用 chrome.debugger 附加至一或多個分頁，檢測網路互動、偵錯 JavaScript、變更 DOM 和 CSS 等。使用 Debuggee 屬性 tabId 指定含有 sendCommand 的分頁，並透過 onEvent 回呼的 tabId 轉送事件。

權限

debugger

您必須在擴充功能的資訊清單中宣告 "debugger" 權限，才能使用這個 API。

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

企業政策限制

企業管理員可以使用 ExtensionSettings 政策的 runtime_blocked_hosts 欄位，禁止擴充功能存取特定主機，除非這些主機也列在 runtime_allowed_hosts 中。

如果目標網址或其中任何頁框的網址與 runtime_blocked_hosts 相符，呼叫 browser.debugger.attach() 會失敗，並顯示 "This page cannot be scripted due to an ExtensionsSettings policy." 錯誤。如果附加目標或其中的任何框架前往封鎖的主機，Chrome 會卸除偵錯工具。

概念和用途

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

目標

目標代表正在偵錯的項目，包括分頁、iframe 或 worker。每個目標都由 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 事件，找出與相同程序框架相關聯的新執行環境。

  • 按照附加至相關目標的步驟，找出程序外頁框。

連線至目標後，您可能需要連線至其他相關目標，包括程序外子項框架或相關聯的 worker。

自 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。不過，這並非遞迴，因此也需要呼叫 Target.setAutoAttach，B 才能將工作階段附加至 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 以上版本 Chrome 148 起為 browser.*

偵錯工具工作階段 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 以上版本 瀏覽器。*自 Chrome 148 起

連線終止原因。

列舉

"target_closed"

"canceled_by_user"

TargetInfo

偵錯目標資訊

屬性

  • 已連結

    布林值

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

  • extensionId

    字串 選填

    擴充功能 ID，在 type = 'background_page' 時定義。

  • faviconUrl

    字串 選填

    目標網站小圖示網址。

  • id

    字串

    目標 ID。

  • tabId

    數字 選填

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

  • title

    字串

    目標網頁標題。

  • 目標類型。

  • 網址

    字串

    目標網址。

TargetInfoType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

目標類型。

列舉

"page"

"background_page"

"worker"

"other"

方法

attach()

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

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

參數

  • 目標

    偵錯目標

    要附加的偵錯目標。

  • requiredVersion

    字串

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

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    附加作業成功或失敗後，系統會解析。Promise 會解析，但不會傳回值。如果附加失敗，系統會拒絕承諾。

detach()

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

從指定目標中斷連結偵錯工具。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    在卸離作業成功或失敗時解析。Promise 會解析，但不會傳回值。如果取消連結失敗，系統會拒絕承諾。

getTargets()

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

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

傳回

  • Promise<TargetInfo[]>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

sendCommand()

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

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

參數

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

  • 方法

    字串

    方法名稱。必須是遠端偵錯通訊協定定義的方法之一。

  • commandParams

    物件 選填

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

傳回

  • Promise<object | undefined>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    回應主體。如果張貼訊息時發生錯誤，系統會拒絕 Promise。

事件

onDetach

browser.debugger.onDetach.addListener(
  callback: function,
)

瀏覽器終止分頁的偵錯工作階段時觸發。當分頁關閉或 Chrome 開發人員工具針對附加分頁叫用時，就會發生這種情況。

參數

onEvent

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

每當偵錯目標發出檢測事件時，就會觸發。

參數

  • callback

    函式

    callback 參數看起來像這樣： 

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