Beschreibung
Die chrome.debugger
API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome. Verwenden Sie chrome.debugger
, um Elemente an einen oder mehrere Tabs anzuhängen, um Netzwerkinteraktionen zu instrumentieren, JavaScript-Fehler zu beheben, DOM und CSS zu ändern und vieles mehr. Verwende die Debuggee
-Property tabId
, um ein Targeting auf Tabs mit sendCommand
vorzunehmen und Ereignisse nach tabId
aus onEvent
-Callbacks weiterzuleiten.
Berechtigungen
debugger
Du musst die Berechtigung „"debugger"
“ im Manifest deiner Erweiterung deklarieren, um diese API verwenden zu können.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Konzepte und Nutzung
Nach dem Anhängen können Sie über die chrome.debugger
API Befehle für das Chrome DevTools Protocol (CDP) an ein bestimmtes Ziel senden. Eine ausführliche Erläuterung der CDP ist in dieser Dokumentation nicht möglich. Weitere Informationen zu CDP finden Sie in der offiziellen CDP-Dokumentation.
Ziele
Ziele stellen etwas dar, das gerade debuggt wird – beispielsweise ein Tab, ein iFrame oder ein Worker. Jedes Ziel wird durch eine UUID identifiziert und einem zugehörigen Typ zugeordnet (z. B. iframe
, shared_worker
usw.).
Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben. Beispielsweise erhalten dieselben Prozess-iFrames kein eindeutiges Ziel, sondern werden stattdessen als unterschiedliche Kontexte dargestellt, auf die von einem einzigen Ziel aus zugegriffen werden kann.
Eingeschränkte Domains
Aus Sicherheitsgründen bietet die chrome.debugger
API nicht auf alle Protokolldomains für Chrome-Entwicklertools Zugriff. Folgende Domains stehen zur Verfügung: Accessibility,
Audits, CacheStorage,
Console,
CSS, Database, Debugger,
DOMDebugger, DOMSnapshot,
DOMSnapshot,
DOM,{/30,{/3,WebAudioWebAuthn
Mit Frames arbeiten
Es gibt keine 1:1-Zuordnung von Frames zu Zielen. Innerhalb eines einzelnen Tabs können mehrere gleiche Prozessframes dasselbe Ziel gemeinsam haben, aber einen anderen Ausführungskontext verwenden. Andererseits kann ein neues Ziel für einen Out-of-Process-iFrame erstellt werden.
Um sie an alle Frames anzuhängen, müssen Sie jeden Frametyp separat behandeln:
Warten Sie auf das Ereignis
Runtime.executionContextCreated
, um neue Ausführungskontexte zu identifizieren, die mit denselben Prozessframes verknüpft sind.Führen Sie die Schritte zum Anhängen an zugehörige Ziele aus, um Out-of-Process-Frames zu identifizieren.
An zugehörige Ziele anhängen
Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, möchten Sie möglicherweise eine Verbindung zu weiteren zugehörigen Zielen wie untergeordneten Frames außerhalb des Prozesses oder zugehörigen Workern herstellen.
Ab Chrome 125 unterstützt die chrome.debugger
API flache Sitzungen. Auf diese Weise können Sie Ihrer Haupt-Debugger-Sitzung zusätzliche Ziele als untergeordnete Ziele hinzufügen und ihnen Nachrichten senden, ohne dass ein weiterer Aufruf von chrome.debugger.attach
erforderlich ist. Stattdessen können Sie beim Aufrufen von chrome.debugger.sendCommand
ein sessionId
-Attribut hinzufügen, um das untergeordnete Ziel zu identifizieren, an das Sie einen Befehl senden möchten.
Fügen Sie zum automatischen Anhängen an untergeordnete Frames außerhalb des Prozesses zuerst einen Listener für das Ereignis Target.attachedToTarget
hinzu:
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");
}
});
Aktivieren Sie dann das automatische Anhängen. Senden Sie dazu den Befehl Target.setAutoAttach
und setzen Sie die Option flatten
auf true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Beispiele
Wenn Sie diese API testen möchten, installieren Sie das Debugger-API-Beispiel aus dem Repository chrome-extension-sample.
Typen
Debuggee
Kennung der zu debuggenden Komponente. Es muss entweder eine tabId, eine Erweiterungs-ID oder eine Ziel-ID angegeben werden
Attribute
-
extensionId
String optional
Die ID der Erweiterung, für die Sie ein Debugging ausführen möchten. Anhängen an eine Hintergrundseite einer Erweiterung sind nur möglich, wenn die
--silent-debugger-extension-api
-Befehlszeile verwendet wird. -
tabId
Nummer optional
Die ID des Tabs, auf dem Sie Fehler beheben möchten.
-
targetId
String optional
Die intransparente ID des Fehlerbehebungsziels.
DebuggerSession
Debugger-Sitzungs-ID. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden. Außerdem kann eine optionale sessionId angegeben werden. Wenn „sessionId“ für Argumente angegeben ist, die von onEvent
gesendet werden, bedeutet dies, dass das Ereignis aus einer untergeordneten Protokollsitzung in der Root-Sitzung der zu debuggenden Komponente stammt. Wenn bei der Übergabe an sendCommand
„sessionId“ angegeben ist, wird eine untergeordnete Protokollsitzung innerhalb der Stammsitzung der zu debuggenden Komponente angesprochen.
Attribute
-
extensionId
String optional
Die ID der Erweiterung, für die Sie ein Debugging ausführen möchten. Anhängen an eine Hintergrundseite einer Erweiterung sind nur möglich, wenn die
--silent-debugger-extension-api
-Befehlszeile verwendet wird. -
sessionId
String optional
Die intransparente ID der Sitzung im Chrome-Entwicklertools-Protokoll. Kennzeichnet eine untergeordnete Sitzung innerhalb der Stammsitzung, die durch tabId, ExtensionsId oder targetId identifiziert wird.
-
tabId
Nummer optional
Die ID des Tabs, auf dem Sie Fehler beheben möchten.
-
targetId
String optional
Die intransparente ID des Fehlerbehebungsziels.
DetachReason
Grund für Beendigung der Verbindung.
Enum
"target_closed"
"canceled_by_user"
TargetInfo
Informationen zum Fehlerbehebungsziel
Attribute
-
Hinzugefügt
boolean
True, wenn Debugger bereits angehängt ist.
-
extensionId
String optional
Die Erweiterungs-ID, definiert, wenn type = 'background_page'.
-
faviconUrl
String optional
Favicon-URL des Ziels.
-
id
String
Ziel-ID.
-
tabId
Nummer optional
Die Tab-ID, definiert bei Typ == 'page'.
-
Titel
String
Titel der Zielseite.
-
Typ
Zieltyp.
-
url
String
Ziel-URL
TargetInfoType
Zieltyp.
Enum
"background_page"
Methoden
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Fügt Debugger an das angegebene Ziel an.
Parameter
-
Debugging-Ziel, das Sie anhängen möchten.
-
requiredVersion
String
Erforderliche Version des Debugging-Protokolls („0.1“). Einer kann nur an die zu debuggende Komponente mit übereinstimmender Hauptversion und größerer oder gleicher Nebenversion angehängt werden. Eine Liste der Protokollversionen finden Sie hier.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Trennt den Debugger vom angegebenen Ziel.
Parameter
-
Debugging-Ziel, von dem Sie die Verbindung trennen möchten.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Gibt die Liste der verfügbaren Fehlerbehebungsziele zurück.
Parameter
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: TargetInfo[]) => void
-
Ergebnis
Array von TargetInfo-Objekten, die den verfügbaren Fehlerbehebungszielen entsprechen.
-
Rückgabe
-
Promise<TargetInfo[]>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Sendet den angegebenen Befehl an das Debugging-Ziel.
Parameter
-
Ziel
Das Debugging-Ziel, an das Sie den Befehl senden möchten.
-
method
String
Name der Methode. Dies sollte eine der im Remote-Debugging-Protokoll definierten Methoden sein.
-
commandParams
Objekt optional
JSON-Objekt mit Anfrageparametern Dieses Objekt muss dem Remote-Debugging-Parameterschema für die angegebene Methode entsprechen.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result?: object) => void
-
Ergebnis
Objekt optional
JSON-Objekt mit der Antwort. Die Struktur der Antwort hängt vom Methodennamen ab und wird durch das "returns"-Attribut der Befehlsbeschreibung im Remote-Debugging-Protokoll definiert.
-
Rückgabe
-
Promise<object | undefined>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
Veranstaltungen
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Wird ausgelöst, wenn der Browser die Debugging-Sitzung für den Tab beendet Das passiert, wenn der Tab entweder geschlossen oder die Chrome-Entwicklertools für den angehängten Tab aufgerufen werden.
Parameter
-
callback
Funktion
Der Parameter
callback
sieht so aus:(source: Debuggee, reason: DetachReason) => void
-
source
-
reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Wird ausgelöst, wenn das Instrumentierungsereignis mit dem Zielfehler behoben wird.
Parameter
-
callback
Funktion
Der Parameter
callback
sieht so aus:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
String
-
params
Objekt optional
-