chrome.debugger

說明

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 或 worker。每個目標都會以 UUID 識別，並具有相關聯的類型 (例如 iframe、shared_worker 等)。

在目標中，可能會有多個執行情境，例如同一個程序的 iframe 不會取得單一目標，而是會以不同的情境表示，可從單一目標存取。

受限網域

基於安全考量，chrome.debugger API 不會提供存取所有 Chrome DevTools 通訊協定網域的權限。可用的網域如下：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 事件，找出與相同處理程序影格相關的新執行階段。

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

連線至目標後，您可能會想要連線至其他相關目標，包括子進程式外框或相關 worker。

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

接著，請傳送 Target.setAutoAttach 指令，並將 flatten 選項設為 true，啟用自動附加功能：

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 存放區安裝偵錯工具 API 範例。

類型

Debuggee

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

屬性

  • extensionId

    string 選填

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

  • tabId

    號碼 選填

    您要偵錯的分頁 ID。

  • targetId

    string 選填

    偵錯目標的不易解讀 ID。

DebuggerSession

Chrome 125 以上版本

偵錯工具工作階段 ID。必須指定 tabId、extensionId 或 targetId 其中一個。此外，您也可以提供選用的 sessionId。如果您為從 onEvent 傳送的引數指定 sessionId，表示該事件來自根偵錯對象工作階段中的子通訊協定工作階段。如果在傳遞至 sendCommand 時指定 sessionId，則會將目標設為根偵錯對象工作階段中的子通訊協定工作階段。

屬性

  • extensionId

    string 選填

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

  • sessionId

    string 選填

    Chrome 開發人員工具通訊協定工作階段的不明 ID。在以 tabId、extensionId 或 targetId 識別的根工作階段中，識別子工作階段。

  • tabId

    號碼 選填

    您要偵錯的分頁 ID。

  • targetId

    string 選填

    偵錯目標的不易解讀 ID。

DetachReason

Chrome 44 以上版本

連線終止原因。

列舉

"target_closed"

"canceled_by_user"

TargetInfo

偵錯目標資訊

屬性

  • 已連結

    布林值

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

  • extensionId

    string 選填

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

  • faviconUrl

    string 選填

    目標網站小圖示網址。

  • id

    字串

    目標 ID。

  • tabId

    號碼 選填

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

  • title

    字串

    目標網頁標題。

  • 目標類型。

  • 網址

    字串

    目標網址。

TargetInfoType

Chrome 44 以上版本

目標類型。

列舉

"page"

"background_page"

"worker"

"other"

方法

attach()

Promise 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

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

參數

  • 目標

    Debuggee

    您要附加的偵錯目標。

  • requiredVersion

    字串

    所需的偵錯通訊協定版本 (0.1)。只能附加與主要版本相符的偵錯對象，次要版本必須大於或等於主要版本。您可以前往這裡查看協定版本清單。

  • callback

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

detach()

Promise 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

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

參數

  • 目標

    Debuggee

    您要從中分離的偵錯目標。

  • callback

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
)

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

參數

  • callback

    函式 選填

    callback 參數如下所示： 

    (result: TargetInfo[]) => void

    • 結果

      TargetInfo[]

      與可用的偵錯目標相對應的 TargetInfo 物件陣列。

傳回

  • Promise<TargetInfo[]>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

sendCommand()

Promise 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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

參數

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

  • method

    字串

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

  • commandParams

    物件 選填

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

  • callback

    函式 選填

    callback 參數如下所示： 

    (result?: object) => void

    • 結果

      物件 選填

      含有回應的 JSON 物件。回應的結構會因方法名稱而異，並由遠端偵錯通訊協定中指令說明的「returns」屬性定義。

傳回

  • Promise<object | undefined>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onDetach

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

瀏覽器終止分頁的偵錯工作階段時觸發。發生這種情況時，系統會關閉分頁，或為已連結的分頁叫用 Chrome 開發人員工具。

參數

onEvent

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

只要偵錯目標發出檢測事件，就會觸發此事件。

參數

  • callback

    函式

    callback 參數如下所示： 

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