디버그 확장 프로그램

확장 프로그램은 웹페이지와 동일한 Chrome DevTools에 액세스할 수 있습니다. 확장 프로그램 디버깅 전문가가 되려면 다양한 확장 프로그램 구성요소의 로그와 오류를 찾는 방법을 알아야 합니다. 이 튜토리얼에서는 확장 프로그램을 디버깅하는 기본 기법을 제공합니다.

시작하기 전에

이 가이드는 기본적인 웹 개발 경험이 있다고 가정합니다. 확장 프로그램 개발 워크플로에 대한 소개는 개발 기본사항을 읽어보세요. 사용자 인터페이스 디자인에서는 확장 프로그램에서 사용할 수 있는 사용자 인터페이스 요소를 소개합니다.

확장 프로그램 중단

이 튜토리얼에서는 확장 프로그램 구성요소를 한 번에 하나씩 중단한 다음 이를 해결하는 방법을 보여줍니다. 다음 섹션으로 진행하기 전에 한 섹션에 도입된 버그를 실행취소해야 합니다. 먼저 GitHub에서 손상된 색상 샘플을 다운로드합니다.

매니페스트 디버그

먼저 "version" 키를 "versions"로 변경하여 매니페스트 파일을 분리해 보겠습니다.

manifest.json:

{
  "name": "Broken Background Color",
  "version": "1.0",
  "versions": "1.0",
  "description": "Fix an Extension!",
  ...
}

이제 확장 프로그램을 로컬로 로드해 보겠습니다. 문제를 가리키는 오류 대화상자가 표시됩니다.

Failed to load extension
Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536.
Could not load manifest.

잘못된 매니페스트 키 오류 대화상자입니다.

매니페스트 키가 유효하지 않은 경우 확장 프로그램은 로드되지 않지만 Chrome에서 문제 해결 방법을 알려줍니다.

변경사항을 실행취소하고 잘못된 권한을 입력하여 어떻게 되는지 확인하세요. "activeTab" 권한을 소문자 "activetab"로 변경합니다.

manifest.json:

{
  ...
  "permissions": ["activeTab", "scripting", "storage"],
  "permissions": ["activetab", "scripting", "storage"],
  ...
}

확장 프로그램을 저장하고 다시 로드해 보세요. 이번에는 성공적으로 로드됩니다. 확장 프로그램 관리 페이지에는 세부정보, 삭제, 오류라는 세 가지 버튼이 표시됩니다. 오류가 있으면 오류 버튼 라벨이 빨간색으로 바뀝니다. 오류 버튼을 클릭하여 다음 오류를 확인합니다.

Permission 'activetab' is unknown or URL pattern is malformed.

'오류' 버튼을 클릭하여 오류 메시지를 찾습니다.

계속하기 전에 권한을 다시 변경하고 오른쪽 상단의 모두 지우기를 클릭하여 로그를 지우고 확장 프로그램을 새로고침합니다.

확장 프로그램 오류를 삭제하는 방법

참고: 코드 편집기에서 매니페스트 스키마를 사용하면 매니페스트에 올바른 형식과 필수 입력란이 있는지 확인할 수 있습니다.

서비스 워커 디버그

로그 찾기

서비스 워커는 기본 색상을 스토리지로 설정하고 이를 콘솔에 로깅합니다. 이 로그를 보려면 보기 검사 옆에 있는 파란색 링크를 선택하여 Chrome DevTools 패널을 여세요.

Chrome DevTools 패널의 서비스 워커 로그

핵심사항: 서비스 워커를 검사해도 서비스 워커는 활성 상태로 유지됩니다. 서비스 워커가 종료될 때 확장 프로그램이 올바르게 동작하도록 하려면 DevTools를 닫아야 합니다.

오류 찾기

onInstalled를 소문자 oninstalled로 변경하여 서비스 워커를 중단해 보겠습니다.

service-worker.js:

// There's a typo in the line below;
// ❌ oninstalled should be ✅ onInstalled.
chrome.runtime.onInstalled.addListener(() => { 
chrome.runtime.oninstalled.addListener(() => { 
  chrome.storage.sync.set({ color: '#3aa757' }, () => {
    console.log('The background color is green.');
  });
});

오류 로그를 보려면 새로고침하고 오류를 클릭합니다. 첫 번째 오류는 서비스 워커의 등록에 실패했음을 나타냅니다. 시작 중에 문제가 발생했음을 의미합니다.

Service worker registration failed. Status code: 15.

서비스 워커 등록 오류 메시지

참고: 서비스 워커를 등록하지 못하면 등록 버그를 수정할 때까지 Chrome DevTools에 액세스할 수 없습니다.

실제 오류는 다음 날짜 이후에 발생합니다.

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

포착되지 않은 유형 오류 메시지

도입된 버그를 취소하고 오른쪽 상단의 모두 지우기를 클릭한 다음 확장 프로그램을 새로고침합니다.

서비스 워커 상태 확인

다음 단계에 따라 서비스 워커가 작업을 수행하기 위해 깨어나는 시점을 식별할 수 있습니다.

1. '보기 검사' 위에 있는 확장 프로그램 ID를 복사합니다.

   

   확장 프로그램 관리 페이지의 확장 프로그램 ID

2. 브라우저에서 매니페스트 파일을 엽니다. 예: text chrome-extension://YOUR_EXTENSION_ID/manifest.json
3. 파일을 검사합니다.
4. 애플리케이션 패널로 이동합니다.
5. 서비스 워커 창으로 이동합니다.

코드를 테스트하려면 status 옆에 있는 링크를 사용하여 서비스 워커를 시작하거나 중지합니다.

Application 패널의 서비스 워커 상태입니다. 이미지를 확대하려면 클릭하세요.

또한 서비스 워커 코드를 변경한 경우 Update 또는 skipWaiting을 클릭하여 변경사항을 즉시 적용할 수 있습니다.

Application 패널에서 서비스 워커를 새로고침합니다. 이미지를 확대하려면 클릭하세요.

참고: 다른 확장 프로그램 구성요소는 새로고침되지 않습니다.

팝업 디버그

이제 확장 프로그램이 올바르게 초기화되므로 아래 강조 표시된 줄을 주석 처리하여 팝업을 중단해 보겠습니다.

popup.js:

...
changeColorButton.addEventListener('click', (event) => {
  const color = event.target.value;

  // Query the active tab before injecting the content script
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => { 
    // Use the Scripting API to execute a script
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      args: [color],
      func: setColor
    });
  });
});

확장 프로그램 관리 페이지로 다시 이동합니다. Errors 버튼이 다시 표시됩니다. 클릭하여 새 로그를 확인하세요. 다음과 같은 오류 메시지가 표시됩니다.

Uncaught ReferenceError: tabs is not defined

팝업 오류를 표시하는 확장 프로그램 관리 페이지

팝업을 검사하여 팝업의 DevTools를 열 수 있습니다.

팝업 오류를 표시하는 DevTools입니다.

tabs is undefined 오류는 확장 프로그램에서 콘텐츠 스크립트를 삽입할 위치를 모른다는 의미입니다. tabs.query()를 호출한 다음 활성 탭을 선택하여 이 문제를 해결하세요.

코드를 업데이트하려면 오른쪽 상단의 모두 지우기 버튼을 클릭한 후 확장 프로그램을 새로고침합니다.

참고: 페이지 재정의 및 전체 페이지 옵션과 같이 탭으로 표시되는 다른 확장 프로그램 페이지의 경우 페이지를 검사하거나 Extensions Management 페이지를 방문하여 로그를 찾을 수 있습니다.

콘텐츠 스크립트 디버그

이제 변수 'color'를 'colors'로 변경하여 콘텐츠 스크립트를 중단해 보겠습니다.

content.js:

...
function setColor(color) {
  // There's a typo in the line below;
  // ❌ colors should be ✅ color.
  document.body.style.backgroundColor = color;
  document.body.style.backgroundColor = colors;
}  

페이지를 새로고침하고 팝업을 연 다음 녹색 상자를 클릭합니다. 아무 일도 일어나지 않습니다.

확장 프로그램 관리 페이지로 이동하면 오류 버튼이 표시되지 않습니다. 런타임 오류, console.warning 및 console.error만 확장 프로그램 관리 페이지에 기록되기 때문입니다.

콘텐츠 스크립트는 웹사이트 내에서 실행됩니다. 따라서 이러한 오류를 찾으려면 확장 프로그램이 변경하려는 웹페이지를 검사해야 합니다.

Uncaught ReferenceError: colors is not defined

웹페이지 콘솔에 확장 프로그램 오류가 표시됩니다.

콘텐츠 스크립트 내에서 DevTools를 사용하려면 top 옆에 있는 드롭다운 화살표를 클릭하고 확장 프로그램을 선택합니다.

포착되지 않은 ReferenceError: 색상이 정의되지 않았습니다.

오류 메시지는 colors가 정의되지 않았다고 표시됩니다. 확장 프로그램이 변수를 올바르게 전달하고 있지 않아야 합니다. 색상 변수를 코드에 전달하도록 삽입된 스크립트를 수정합니다.

네트워크 요청 모니터링

가장 빠른 개발자라도 DevTools를 열기 전에 팝업에서 필요한 네트워크 요청을 모두 실행하는 경우가 많습니다. 이러한 요청을 보려면 네트워크 패널 내부에서 새로고침하세요. 그러면 DevTools 패널을 닫지 않고 팝업을 다시 로드합니다.

팝업 네트워크 요청을 보려면 네트워크 패널 내부를 새로고침하세요.

권한 선언

일부 확장 프로그램 API에는 권한이 필요합니다. 확장 프로그램이 매니페스트에서 올바른 권한을 요청하는지 확인하려면 권한 문서 및 Chrome API를 참고하세요.

  {
    "name": "Broken Background Color",
    ...
    "permissions": [
      "activeTab",
      "declarativeContent",
      "storage"
    ],
  ...
  }

핵심사항: 외부 서버에 fetch()를 호출하려면 URL을 호스트 권한으로 선언해야 합니다.

추가 자료

Chrome Devtools에 관한 자세한 내용은 문서를 참고하세요.