chrome.debugger

refresh date: 2026-09-25 robots: noindex

Descrição

A API chrome.debugger serve como um transporte alternativo para o protocolo de depuração remota do Chrome. Use chrome.debugger para anexar a uma ou mais guias para instrumentar a interação de rede, depurar JavaScript, modificar o DOM e o CSS e muito mais. Use a propriedade tabId de Debuggee para segmentar guias com sendCommand e rotear eventos por tabId de callbacks onEvent.

Permissões

debugger

Observação de segurança

Por motivos de segurança, a API chrome.debugger não oferece acesso a todos os domínios do Chrome DevTools Protocol. Os domínios disponíveis são: Acessibilidade, Auditorias, CacheStorage, Console, CSS, Banco de dados, Depurador, DOM, DOMDebugger, DOMSnapshot, Emulação, Busca, E/S, Entrada, Inspetor, Registro, Rede, Sobreposição, Página, Desempenho, Ambiente de execução, Armazenamento, Destino, Rastreamento, WebAudio e WebAuthn.

Manifesto

É necessário declarar a permissão "debugger" no manifesto da extensão para usar essa API.

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

Exemplos

Para testar essa API, instale o exemplo da API debugger do repositório chrome-extension-samples.

Tipos

Debuggee

Identificador do depurado. É preciso especificar tabId, extensionId ou targetId

Propriedades

  • extensionId

    string opcional

    O ID da extensão que você quer depurar. A anexação a uma página de segundo plano de extensão só é possível quando a chave de linha de comando --silent-debugger-extension-api é usada.

  • tabId

    número optional

    O ID da guia que você quer depurar.

  • targetId

    string opcional

    O ID opaco do destino de depuração.

DebuggerSession

Chrome 125+

Identificador de sessão do depurador. É preciso especificar tabId, extensionId ou targetId. Além disso, é possível fornecer um sessionId opcional. Se sessionId for especificado para argumentos enviados de onEvent, isso significa que o evento vem de uma sessão de protocolo filho dentro da sessão de depuração raiz. Se sessionId for especificado quando transmitido para sendCommand, ele vai segmentar uma sessão de protocolo filho dentro da sessão de depuração raiz.

Propriedades

  • extensionId

    string opcional

    O ID da extensão que você quer depurar. A anexação a uma página de segundo plano de extensão só é possível quando a chave de linha de comando --silent-debugger-extension-api é usada.

  • sessionId

    string opcional

    O ID opaco da sessão do Chrome DevTools Protocol. Identifica uma sessão filha na sessão raiz identificada por tabId, extensionId ou targetId.

  • tabId

    número optional

    O ID da guia que você quer depurar.

  • targetId

    string opcional

    O ID opaco do destino de depuração.

DetachReason

Chrome 44+

Motivo do encerramento da conexão.

Enumeração

"target_closed"

"canceled_by_user"

TargetInfo

Informações de destino de depuração

Propriedades

  • sempre que o disco for anexado

    booleano

    Verdadeiro se o depurador já estiver anexado.

  • extensionId

    string opcional

    O ID da extensão, definido se type = "background_page".

  • faviconUrl

    string opcional

    URL do favicon de destino.

  • ID

    string

    ID de destino.

  • tabId

    número optional

    O ID da guia, definido se type == 'page'.

  • título

    string

    Título da página de destino.

  • Tipo de destino.

  • url

    string

    URL de destino.

TargetInfoType

Chrome 44+

Tipo de destino.

Enumeração

"page"

"background_page"

"worker"

"other"

Métodos

attach()

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

Anexa o depurador ao destino especificado.

Parâmetros

  • destino

    Depurado

    Destino de depuração ao qual você quer se conectar.

  • requiredVersion

    string

    Versão do protocolo de depuração necessária ("0.1"). Só é possível se conectar ao depurado com a versão principal correspondente e a versão secundária maior ou igual. A lista de versões do protocolo pode ser encontrada aqui.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou mais recente

    É resolvido quando a operação de anexação é concluída ou falha. A promessa é resolvida sem valor. Se a anexação falhar, a promessa será rejeitada.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

detach()

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

Desconecta o depurador do destino especificado.

Parâmetros

  • destino

    Depurado

    Destino de depuração do qual você quer se desconectar.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou mais recente

    É resolvido quando a operação de desvinculação é concluída ou falha. A promessa é resolvida sem valor. Se a remoção falhar, a promessa será rejeitada.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getTargets()

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

Retorna a lista de destinos de depuração disponíveis.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (result: TargetInfo[]) => void

    • resultado

      TargetInfo[]

      Matriz de objetos TargetInfo correspondentes aos destinos de depuração disponíveis.

Retorna

  • Promise<TargetInfo[]>

    Chrome 96 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

sendCommand()

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

Envia o comando fornecido ao destino de depuração.

Parâmetros

  • destino

    DebuggerSession

    Destino de depuração para o qual você quer enviar o comando.

  • método

    string

    Nome do método. Precisa ser um dos métodos definidos pelo protocolo de depuração remota.

  • commandParams

    objeto optional

    Objeto JSON com parâmetros de solicitação. Esse objeto precisa estar em conformidade com o esquema de parâmetros de depuração remota para o método fornecido.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (result?: object) => void

    • resultado

      objeto optional

      Objeto JSON com a resposta. A estrutura da resposta varia de acordo com o nome do método e é definida pelo atributo "returns" da descrição do comando no protocolo de depuração remota.

Retorna

  • Promise<object | undefined>

    Chrome 96 ou mais recente

    Corpo da resposta. Se ocorrer um erro ao postar a mensagem, a promessa será rejeitada.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onDetach

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

Disparado quando o navegador encerra a sessão de depuração da guia. Isso acontece quando a guia está sendo fechada ou o Chrome DevTools está sendo invocado para a guia anexada.

Parâmetros

onEvent

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

Disparado sempre que o destino de depuração emite um evento de instrumentação.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

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