chrome.debugger

refresh date: 2026-09-25 robots: noindex

Описание

API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome. Используйте chrome.debugger, чтобы подключиться к одной или нескольким вкладкам и отслеживать сетевое взаимодействие, отлаживать JavaScript, изменять DOM и CSS и выполнять другие действия. Используйте свойство tabId Debuggee, чтобы настроить таргетинг на вкладки с помощью 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

    Строка (необязательно)

    Идентификатор расширения, заданный, если type = '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>

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

Параметры

  • target

    Debuggee

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

  • requiredVersion

    string

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

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

    function необязательно

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

    () => void

Возвраты

  • Promise<void>

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

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

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

detach()

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

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

Параметры

  • target

    Debuggee

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

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

    function необязательно

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

    () => void

Возвраты

  • Promise<void>

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

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

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

getTargets()

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

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

Параметры

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

    function необязательно

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

    (result: TargetInfo[]) => void

    • Результат

      TargetInfo[]

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

Возвраты

  • Promise<TargetInfo[]>

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

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

sendCommand()

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

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

Параметры

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

  • method

    string

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

  • commandParams

    Объект (необязательно)

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

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

    function необязательно

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

    (result?: object) => void

    • Результат

      Объект (необязательно)

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

Возвраты

  • Promise<object | undefined>

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

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

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

События

onDetach

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

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

Параметры

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

    function

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

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

onEvent

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

Срабатывает, когда целевой объект отладки выдает событие инструментирования.

Параметры

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

    function

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

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

    • method

      string

    • params

      Объект (необязательно)