chrome.debugger

refresh date: 2026-09-25 robots: noindex

Descripción

La API de chrome.debugger funciona como un transporte alternativo para el protocolo de depuración remota de Chrome. Usa chrome.debugger para adjuntar una o más pestañas para instrumentar la interacción de la red, depurar JavaScript, mutar el DOM y CSS, y mucho más. Usa la propiedad Debuggee tabId para segmentar pestañas con sendCommand y enrutar eventos por tabId desde devoluciones de llamada de onEvent.

Permisos

debugger

Nota de seguridad

Por motivos de seguridad, la API de chrome.debugger no proporciona acceso a todos los dominios del protocolo de Herramientas para desarrolladores de Chrome. Los dominios disponibles son: 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 y WebAuthn

Manifiesto

Debes declarar el permiso "debugger" en el manifiesto de tu extensión para usar esta API.

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

Ejemplos

Para probar esta API, instala el ejemplo de la API de depurador del repositorio chrome-extension-samples.

Tipos

Debuggee

Es el identificador del programa que se depura. Se debe especificar tabId, extensionId o targetId.

Propiedades

  • extensionId

    cadena opcional

    Es el ID de la extensión que deseas depurar. Solo es posible adjuntar la página de segundo plano de una extensión cuando se usa el parámetro de conmutación de línea de comandos --silent-debugger-extension-api.

  • tabId

    número opcional

    Es el ID de la pestaña que deseas depurar.

  • targetId

    cadena opcional

    Es el ID opaco del destino de depuración.

DebuggerSession

Chrome 125 y versiones posteriores

Es el identificador de la sesión del depurador. Se debe especificar uno de los valores tabId, extensionId o targetId. Además, se puede proporcionar un sessionId opcional. Si se especifica sessionId para los argumentos enviados desde onEvent, significa que el evento proviene de una sesión de protocolo secundaria dentro de la sesión raíz del depurador. Si se especifica sessionId cuando se pasa a sendCommand, se segmenta para una sesión de protocolo secundaria dentro de la sesión raíz del depurado.

Propiedades

  • extensionId

    cadena opcional

    Es el ID de la extensión que deseas depurar. Solo es posible adjuntar la página de segundo plano de una extensión cuando se usa el parámetro de conmutación de línea de comandos --silent-debugger-extension-api.

  • sessionId

    cadena opcional

    Es el ID opaco de la sesión del Protocolo de Herramientas para desarrolladores de Chrome. Identifica una sesión secundaria dentro de la sesión raíz identificada por tabId, extensionId o targetId.

  • tabId

    número opcional

    Es el ID de la pestaña que deseas depurar.

  • targetId

    cadena opcional

    Es el ID opaco del destino de depuración.

DetachReason

Chrome 44 y versiones posteriores

Es el motivo de la finalización de la conexión.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Información del destino de depuración

Propiedades

  • se conecte el disco

    booleano

    Es verdadero si el depurador ya está adjunto.

  • extensionId

    cadena opcional

    Es el ID de la extensión, que se define si type = "background_page".

  • faviconUrl

    cadena opcional

    Es la URL del ícono de página de destino.

  • id

    string

    Es el ID del objetivo.

  • tabId

    número opcional

    Es el ID de la pestaña, que se define si el tipo es "page".

  • título

    string

    Es el título de la página de destino.

  • Es el tipo de objetivo.

  • url

    string

    Es la URL de destino.

TargetInfoType

Chrome 44 y versiones posteriores

Es el tipo de objetivo.

Enum

"page"

"background_page"

"worker"

"other"

Métodos

attach()

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

Adjunta el depurador al destino determinado.

Parámetros

  • objetivo

    Debuggee

    Es el destino de depuración al que deseas adjuntar el depurador.

  • requiredVersion

    string

    Versión del protocolo de depuración requerida ("0.1"). Solo se puede adjuntar al depurador con una versión principal coincidente y una versión secundaria mayor o igual. Puedes obtener la lista de versiones del protocolo aquí.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

    Se resuelve una vez que la operación de adjuntar se completa correctamente o falla. La promesa se resuelve sin ningún valor. Si la vinculación falla, se rechazará la promesa.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

detach()

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

Desvincula el depurador del destino determinado.

Parámetros

  • objetivo

    Debuggee

    Es el destino de depuración del que deseas desconectarte.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

    Se resuelve una vez que la operación de separación se completa correctamente o falla. La promesa se resuelve sin ningún valor. Si falla la separación, se rechazará la promesa.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

Devuelve la lista de destinos de depuración disponibles.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: TargetInfo[]) => void

    • resultado

      TargetInfo[]

      Es un array de objetos TargetInfo que corresponden a los destinos de depuración disponibles.

Muestra

  • Promise<TargetInfo[]>

    Chrome 96 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

sendCommand()

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

Envía el comando determinado al destino de depuración.

Parámetros

  • objetivo

    DebuggerSession

    Es el destino de depuración al que deseas enviar el comando.

  • método

    string

    Nombre del método. Debe ser uno de los métodos definidos por el protocolo de depuración remota.

  • commandParams

    objeto opcional

    Objeto JSON con parámetros de la solicitud. Este objeto debe cumplir con el esquema de parámetros de depuración remota para el método determinado.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result?: object) => void

    • resultado

      objeto opcional

      Objeto JSON con la respuesta. La estructura de la respuesta varía según el nombre del método y se define por el atributo "returns" de la descripción del comando en el protocolo de depuración remota.

Muestra

  • Promise<object | undefined>

    Chrome 96 y versiones posteriores

    Cuerpo de la respuesta. Si se produce un error al publicar el mensaje, se rechazará la promesa.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onDetach

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

Se activa cuando el navegador finaliza la sesión de depuración de la pestaña. Esto sucede cuando se cierra la pestaña o se invoca a Herramientas para desarrolladores de Chrome para la pestaña adjunta.

Parámetros

onEvent

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

Se activa cada vez que se produce un evento de instrumentación de problemas del destino de depuración.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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