설명
chrome.debugger API는 Chrome 원격 디버깅 프로토콜의 대체 전송 역할을 합니다. chrome.debugger를 사용하여 하나 이상의 탭에 연결하여 네트워크 상호작용을 계측하고 JavaScript를 디버그하고 DOM 및 CSS를 변경하는 등의 작업을 실행합니다. Debuggee 속성 tabId를 사용하여 sendCommand가 있는 탭을 타겟팅하고 onEvent 콜백에서 tabId로 이벤트를 라우팅합니다.
권한
debugger이 API를 사용하려면 확장 프로그램의 매니페스트에서 "debugger" 권한을 선언해야 합니다.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
개념 및 사용법
연결되면 chrome.debugger API를 통해 Chrome DevTools 프로토콜을 전송할 수 있습니다.
(CDP) 명령어를 실행합니다. CDP에 대한 자세한 설명은 범위를 벗어납니다.
CDP에 대해 자세히 알아보려면
공식 CDP 문서를 참조하세요.
대상
대상은 디버그 중인 항목을 나타냅니다. 여기에는 탭,
iframe 또는 worker가 포함될 수 있습니다. 각 대상은 UUID로 식별되며 대상에는
유형 (예: iframe, shared_worker)
타겟 내에는 여러 개의 실행 컨텍스트가 있을 수 있습니다. 예를 들어 프로세스 iframe은 고유한 타겟을 얻지 않고 대신 여러 가지 컨텍스트가 포함됩니다
제한된 도메인
보안상의 이유로 chrome.debugger API는 일부 Chrome DevTools에 대한 액세스를 제공하지 않습니다.
프로토콜 도메인. 사용 가능한 도메인은 접근성,
감사, CacheStorage, 콘솔,
CSS, 데이터베이스, 디버거, DOM
DOMDebugger, DOMSnapshot,
에뮬레이션, 가져오기, IO, 입력,
검사기, 로그, 네트워크, 오버레이,
페이지, 성능, 프로파일러,
런타임, 스토리지, 타겟, 추적,
WebAudio, WebAuthn도 포함합니다.
프레임 사용
프레임은 타겟에 일대일 매핑되지 않습니다. 하나의 탭 내에서 여러 개의 동일한 프로세스 프레임이 동일한 타겟을 공유할 수 있지만 실행 컨텍스트입니다. 반면에 새로운 표적은 프로세스 외부 iframe용으로 생성됩니다.
모든 프레임에 연결하려면 각 프레임 유형을 별도로 처리해야 합니다.
Runtime.executionContextCreated이벤트를 수신 대기하여 새 항목 식별 여러 개의 실행 컨텍스트를 생성합니다.다음 단계에 따라 관련 대상에 연결합니다. 식별이 가능합니다
관련 대상에 연결
대상에 연결한 후 추가 관련 대상에 연결하는 것이 좋습니다. 프로세스 외부 하위 프레임 또는 관련 작업자 등이 포함됩니다.
Chrome 125부터 chrome.debugger API는 플랫 세션을 지원합니다. 이
기본 디버거 세션에 추가 타겟을 하위 요소로 추가하고
chrome.debugger.attach를 다시 호출할 필요 없이 메시지를 보낼 수 있습니다. 대신
chrome.debugger.sendCommand를 호출할 때 sessionId 속성을 추가할 수 있습니다.
명령을 보내려는 하위 대상을 식별합니다.
프로세스 외부 하위 프레임에 자동으로 연결하려면 먼저
Target.attachedToTarget 이벤트를 전달합니다.
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");
}
});
그런 다음 Target.setAutoAttach 명령어를 다음 명령어로 전송하여 자동 연결을 사용 설정합니다.
true로 설정된 flatten 옵션:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
예
이 API를 사용하려면 chrome-extension-samples에서 디버거 API 예시를 설치하세요. 저장소
유형
Debuggee
디버깅 대상 식별자입니다. tabId, extensionsId 또는 targetId를 지정해야 합니다.
속성
-
extensionId
문자열(선택사항)
디버그하려는 확장 프로그램의 ID입니다. 확장 프로그램 백그라운드 페이지에 연결하는 것은
--silent-debugger-extension-api명령줄 스위치를 사용하는 경우에만 가능합니다. -
tabId
숫자 선택사항
디버그하려는 탭의 ID입니다.
-
targetId
문자열(선택사항)
디버그 타겟의 불투명 ID입니다.
DebuggerSession
디버거 세션 식별자입니다. tabId, extensionsId 또는 targetId 중 하나를 지정해야 합니다. 선택사항으로 sessionId를 제공할 수도 있습니다. onEvent에서 전송된 인수에 sessionId가 지정된 경우, 이벤트가 루트 디버깅 대상 세션 내의 하위 프로토콜 세션에서 발생한다는 의미입니다. sendCommand에 전달될 때 sessionId가 지정되면 루트 디버깅 대상 세션 내의 하위 프로토콜 세션을 타겟팅합니다.
속성
-
extensionId
문자열(선택사항)
디버그하려는 확장 프로그램의 ID입니다. 확장 프로그램 백그라운드 페이지에 연결하는 것은
--silent-debugger-extension-api명령줄 스위치를 사용하는 경우에만 가능합니다. -
sessionId
문자열(선택사항)
Chrome DevTools 프로토콜 세션의 불투명 ID입니다. tabId, ExtensionId 또는 targetId로 식별된 루트 세션 내에서 하위 세션을 식별합니다.
-
tabId
숫자 선택사항
디버그하려는 탭의 ID입니다.
-
targetId
문자열(선택사항)
디버그 타겟의 불투명 ID입니다.
DetachReason
연결 종료 이유입니다.
열거형
"target_closed"
"canceled_by_user"
TargetInfo
디버그 대상 정보
속성
-
연결됨
부울
디버거가 이미 연결되어 있으면 true입니다.
-
extensionId
문자열(선택사항)
확장 프로그램 ID로, 유형이 'background_page'인 경우 정의됩니다.
-
faviconUrl
문자열(선택사항)
파비콘 URL 타겟팅
-
id
문자열
대상 ID입니다.
-
tabId
숫자 선택사항
탭 ID로, 유형 == '페이지'인 경우 정의됩니다.
-
제목
문자열
대상 페이지 제목
-
대상 유형입니다.
-
URL
문자열
대상 URL
TargetInfoType
대상 유형입니다.
열거형
'페이지'
"background_page"
"직원"
'기타'
메서드
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
디버거를 지정된 타겟에 연결합니다.
매개변수
-
target
연결할 디버깅 대상입니다.
-
requiredVersion
문자열
디버깅 프로토콜 버전('0.1')이 필요합니다. 일치하는 주 버전과 마이너 버전 이상의 디버깅 대상에만 연결할 수 있습니다. 프로토콜 버전 목록은 여기에서 확인할 수 있습니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
반환 값
-
프로미스<void>
Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
지정된 타겟에서 디버거를 분리합니다.
매개변수
-
target
분리할 디버깅 대상입니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
반환 값
-
프로미스<void>
Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
사용 가능한 디버그 타겟 목록을 반환합니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(result: TargetInfo[]) => void
-
결과
사용 가능한 디버그 타겟에 해당하는 TargetInfo 객체의 배열입니다.
-
반환 값
-
Promise<TargetInfo[]>
Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
지정된 명령어를 디버깅 타겟으로 전송합니다.
매개변수
-
target
명령어를 전송할 디버깅 대상입니다.
-
method
문자열
메서드 이름입니다. 원격 디버깅 프로토콜에서 정의된 메서드 중 하나여야 합니다.
-
commandParams
객체(선택사항)
요청 매개변수가 있는 JSON 객체입니다. 이 객체는 지정된 메서드에 대한 원격 디버깅 매개변수 스키마를 준수해야 합니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(result?: object) => void
-
결과
객체(선택사항)
JSON 객체입니다. 응답의 구조는 메서드 이름에 따라 다르며 '반환'에 의해 정의됩니다. 원격 디버깅 프로토콜에 있는 명령 설명의 속성입니다.
-
반환 값
-
Promise<object | 정의되지 않음>
Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
이벤트
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
브라우저가 탭의 디버깅 세션을 종료할 때 실행됩니다. 이는 탭이 닫히고 있거나 연결된 탭에 대해 Chrome DevTools가 호출 중일 때 발생합니다.
매개변수
-
콜백
함수
callback매개변수는 다음과 같습니다.(source: Debuggee, reason: DetachReason) => void
-
source
-
reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
디버깅 타겟에서 계측 이벤트에 문제가 발생할 때마다 실행됩니다.
매개변수
-
콜백
함수
callback매개변수는 다음과 같습니다.(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
문자열
-
params
객체(선택사항)
-