chrome.debugger

說明

chrome.debugger API 可做為 Chrome 遠端偵錯通訊協定的替代傳輸方式。使用 chrome.debugger 附加至一或多個分頁，以檢測網路互動、對 JavaScript 進行偵錯、變更 DOM 和 CSS 等。使用 Debuggee 屬性 tabId 指定含有 sendCommand 的分頁，以及 tabId 從 onEvent 回呼的路徑事件。

權限

debugger

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

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

概念和用法

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

目標

目標代表正在進行偵錯的項目，可能包括分頁標籤 iframe 或工作站。每個目標都以 UUID 識別，並具有 類型 (例如 iframe、shared_worker 等)。

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

受限制的網域

基於安全考量，chrome.debugger API 不提供所有 Chrome 開發人員工具的存取權 通訊協定網域。可用的網域如下：無障礙、 Audits、CacheStorage、Console、 CSS、資料庫、Debugger、DOM、 DOMDebugger、DOMSnapshot、 模擬、擷取、IO、輸入 檢查工具、記錄、網路、重疊、 頁面、效能、Profiler， 執行階段、儲存空間、目標、追蹤、 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 }]
});

範例

如要試用這個 API，請安裝 chrome-extension-samples 提供的偵錯工具 API 範例 Cloud Storage 也提供目錄同步處理功能

類型

Debuggee

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

屬性

• extensionId

  string optional

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

• tabId

  編號 選填

  要偵錯的分頁 ID。

• targetId

  string optional

  偵錯目標的不透明 ID。

DebuggerSession

Chrome 125 以上版本

Debugger 工作階段 ID。必須指定 TabId、extensionId 或 targetId。此外，也可以視需要提供 sessionId。如果已為 onEvent 傳送的引數指定 sessionId，表示該事件來自根偵錯目標工作階段的子通訊協定工作階段。如果在傳遞至 sendCommand 時指定了 sessionId，就會指定根偵錯目標工作階段中的子通訊協定工作階段。

屬性

• extensionId

  string optional

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

• sessionId

  string optional

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

• tabId

  編號 選填

  要偵錯的分頁 ID。

• targetId

  string optional

  偵錯目標的不透明 ID。

DetachReason

Chrome 44 以上版本

連線終止原因。

列舉

"target_closed"

"canceled_by_user"

TargetInfo

偵錯目標資訊

屬性

• 已連結

  布林值

  如果已附加偵錯工具，則為「是」。

• extensionId

  string optional

  擴充功能 ID，若 type = 'background_page' 則定義。

• faviconUrl

  string optional

  目標網站小圖示網址。

• id

  字串

  目標 ID。

• tabId

  編號 選填

  分頁 ID，若 type == 'page' 則定義。

• title

  字串

  目標頁面標題。

• 類型

  TargetInfoType

  目標類型。

• 網址

  字串

  目標網址。

TargetInfoType

Chrome 44 以上版本

目標類型。

列舉

"網頁"

"background_page"

"worker"

「其他」

方法

attach()

Promise

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

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

參數

• 目標

  偵錯目標

  要附加的偵錯目標。

• requiredVersion

  字串

  需要偵錯通訊協定版本 (「0.1」)。其中一個只能附加至主要版本相符且大於或等於子版本的偵錯目標。您可以在這裡取得通訊協定版本的清單。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 96 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

detach()

Promise

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

將偵錯工具從指定目標卸離。

參數

• 目標

  偵錯目標

  從您要卸離的偵錯目標。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 96 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getTargets()

Promise

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

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

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (result: TargetInfo[]) => void

  • 結果

    TargetInfo[]

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

傳回

• Promise&lt;TargetInfo[]&gt;

  Chrome 96 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

sendCommand()

Promise

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

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

參數

• 目標

  DebuggerSession

  對要傳送指令的目標進行偵錯。

• method

  字串

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

• commandParams

  物件 optional

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (result?: object) => void

  • 結果

    物件 optional

    含有回應的 JSON 物件。回應結構會因方法名稱而異，且由「returns」定義。

傳回

• Promise&lt;object |未定義>

  Chrome 96 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onDetach

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  (source: Debuggee, reason: DetachReason) => void

  • 來源

    偵錯目標

  • 原因

    DetachReason

onEvent

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

對目標問題檢測事件偵錯時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • 來源

    DebuggerSession

  • method

    字串

  • 參數

    物件 optional