chrome.debugger

refresh date: 2026-09-25 robots: noindex

Описание

API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome. Используйте chrome.debugger, чтобы подключиться к одной или нескольким вкладкам и отслеживать сетевое взаимодействие, отлаживать JavaScript, изменять DOM и CSS и т. д. Используйте свойство Debuggee tabId, чтобы настраивать таргетинг на вкладки с помощью sendCommand и перенаправлять события по tabId из обратных вызовов onEvent.

Разрешения

debugger

Примечание о безопасности

Из соображений безопасности API chrome.debugger не предоставляет доступ ко всем доменам протокола инструментов разработчика Chrome. Доступны следующие домены: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Runtime, Storage, Target, Tracing, WebAudio и WebAuthn.

Манифест

Чтобы использовать этот API, необходимо объявить разрешение "debugger" в манифесте расширения.

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

Примеры

Чтобы попробовать этот API, установите пример API отладчика из репозитория chrome-extension-samples.

Типы

Debuggee

Идентификатор отлаживаемого процесса. Необходимо указать tabId, extensionId или targetId.

Свойства

  • extensionId

    строка необязательно

    Идентификатор расширения, которое вы хотите отладить. Прикрепить отладчик к фоновой странице расширения можно только при использовании параметра командной строки --silent-debugger-extension-api.

  • tabId

    number необязательный

    Идентификатор вкладки, которую вы хотите отладить.

  • targetId

    строка необязательно

    Непрозрачный идентификатор целевого объекта отладки.

DebuggerSession

Chrome 125 и более поздние версии

Идентификатор сеанса отладчика. Необходимо указать tabId, extensionId или targetId. Также можно указать необязательный параметр sessionId. Если для аргументов, отправленных из onEvent, указан sessionId, это означает, что событие происходит из сеанса дочернего протокола в рамках корневого сеанса отлаживаемого приложения. Если при передаче в sendCommand указан sessionId, то он будет относиться к дочернему сеансу протокола в рамках корневого сеанса отладки.

Свойства

  • extensionId

    строка необязательно

    Идентификатор расширения, которое вы хотите отладить. Прикрепить отладчик к фоновой странице расширения можно только при использовании параметра командной строки --silent-debugger-extension-api.

  • sessionId

    строка необязательно

    Непрозрачный идентификатор сеанса Chrome DevTools Protocol. Идентифицирует дочерний сеанс в корневом сеансе, который определяется с помощью tabId, extensionId или targetId.

  • tabId

    number необязательный

    Идентификатор вкладки, которую вы хотите отладить.

  • targetId

    строка необязательно

    Непрозрачный идентификатор целевого объекта отладки.

DetachReason

Chrome 44 и более поздние версии

Причина прекращения подключения.

Перечисление

"target_closed"

"canceled_by_user"

TargetInfo

Информация о целевом объекте отладки

Свойства

  • подключен

    Логическое значение

    Значение True, если отладчик уже подключен.

  • extensionId

    строка необязательно

    Идентификатор расширения, если тип равен background_page.

  • faviconUrl

    строка необязательно

    Целевой URL значка сайта.

  • id

    string

    Идентификатор цели.

  • tabId

    number необязательный

    Идентификатор вкладки, определенный, если type == "page".

  • название

    string

    Заголовок целевой страницы.

  • Тип таргетинга.

  • url

    string

    Целевой URL.

TargetInfoType

Chrome 44 и более поздние версии

Тип таргетинга.

Перечисление

"page"

"background_page"

"worker"

"other"

Методы

attach()

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

Подключает отладчик к указанной цели.

Параметры

  • Целевой объект отладки, к которому вы хотите подключиться.

  • requiredVersion

    string

    Требуемая версия протокола отладки ("0.1"). Подключиться к отладчику можно только в том случае, если основная версия совпадает, а промежуточная версия больше или равна. Список версий протокола можно найти здесь.

  • обратный вызов

    функция optional

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии

    Разрешается, когда операция прикрепления выполнена успешно или завершилась с ошибкой. Объект Promise распознается без значения. Если прикрепить файл не удастся, объект возвращает отказ.

    Обещания поддерживаются только в Manifest V3 и более поздних версиях. На других платформах необходимо использовать обратные вызовы.

detach()

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

Отсоединяет отладчик от указанной цели.

Параметры

  • Цель отладки, от которой нужно отсоединиться.

  • обратный вызов

    функция optional

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии

    Разрешается, когда операция отсоединения выполнена успешно или произошла ошибка. Объект Promise распознается без значения. Если отсоединить устройство не удастся, объект возвращает отказ.

    Обещания поддерживаются только в Manifest V3 и более поздних версиях. На других платформах необходимо использовать обратные вызовы.

getTargets()

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

Возвращает список доступных целей отладки.

Параметры

  • обратный вызов

    функция optional

    Параметр callback выглядит следующим образом: 

    (result: TargetInfo[]) => void

    • Результат

      TargetInfo[]

      Массив объектов TargetInfo, соответствующих доступным целевым объектам отладки.

Возвраты

  • Promise<TargetInfo[]>

    Chrome 96 и более поздние версии

    Обещания поддерживаются только в Manifest V3 и более поздних версиях. На других платформах необходимо использовать обратные вызовы.

sendCommand()

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

Отправляет указанную команду целевому объекту отладки.

Параметры

  • Целевое устройство для отладки, на которое нужно отправить команду.

  • method

    string

    Название метода. Должен быть одним из методов, определенных протоколом удаленной отладки.

  • commandParams

    объект необязательный

    Объект JSON с параметрами запроса. Этот объект должен соответствовать схеме параметров удаленной отладки для заданного метода.

  • обратный вызов

    функция optional

    Параметр callback выглядит следующим образом: 

    (result?: object) => void

    • Результат

      объект необязательный

      Объект JSON с ответом. Структура ответа зависит от названия метода и определяется атрибутом returns описания команды в протоколе удаленной отладки.

Возвраты

  • Promise<object | undefined>

    Chrome 96 и более поздние версии

    Тело ответа. Если при отправке сообщения произойдет ошибка, обещание будет отклонено.

    Обещания поддерживаются только в Manifest V3 и более поздних версиях. На других платформах необходимо использовать обратные вызовы.

События

onDetach

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

Активируется, когда браузер завершает сеанс отладки для вкладки. Это происходит, когда закрывается вкладка или для прикрепленной вкладки вызываются инструменты разработчика Chrome.

Параметры

onEvent

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

Активируется при каждом событии инструментации, связанном с проблемами целевого объекта отладки.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • method

      string

    • params

      объект необязательный