크롬 확장 프로그램 스크린 캡처 개발 삽질기 (Manifest v3 함정 정리)

 

크롬 확장 프로그램으로 간단한 스크린 캡처 기능을 만들면서 예상보다 많은 시행착오를 겪었다.

기능 자체는 단순했지만, Manifest v3 환경에서 생각보다 까다로운 부분이 많았다.

 

이번 글에서는 실제로 막혔던 부분과 해결 방법을 정리해본다.

---

1. Service Worker에서 DOM 사용 불가

 

Service Worker에서 DOM 사용 불가

 

처음에는 다운로드를 위해 아래 코드처럼 <a> 태그를 생성했다.

const link = document.createElement("a");
link.href = dataUrl;
link.download = "screenshot.png";
link.click();

하지만 아무 반응이 없었다.

원인은 간단했다.
Manifest v3의 background는 Service Worker이기 때문에 DOM이 존재하지 않는다.

 

해결 방법
chrome.downloads.download API를 사용해야 한다.

---

2. downloads 권한 누락

 

코드를 수정했는데도 다운로드가 되지 않았다.

 

downloads 권한 누락

 

이유는 manifest에 downloads 권한이 없었기 때문.

"permissions": ["downloads"]

 

이 한 줄이 없으면 다운로드는 동작하지 않는다.

---

3. activeTab 권한 필요

activeTab 권한 필요

 

처음에는 "tabs" 권한만 추가했는데 캡처가 제대로 동작하지 않았다.

특히 클릭 이벤트 기반에서는

 

 "activeTab" 권한이 필수

"permissions": ["activeTab", "downloads"]

---

 

4. 콜백 방식 대신 Promise 사용

 

기존 callback 방식으로 작성했을 때는 간헐적으로 실패했다.

chrome.tabs.captureVisibleTab(..., callback)

 

Manifest v3에서는 async/await 기반이 훨씬 안정적이다.

const dataUrl = await chrome.tabs.captureVisibleTab(...)

---

 

5. 확장 프로그램 새로고침 안 해서 삽질

 

코드를 아무리 수정해도 반영이 안 되는 문제가 있었다.

원인은 단순했다.

 

chrome://extensions에서 새로고침을 안 함

이건 진짜 가장 많이 하는 실수다.

---

6. 캡처가 안 되는 페이지 존재

 

모든 페이지에서 캡처가 되는 것은 아니다.

 

다음 페이지는 정상적으로 동작하지 않는다.

• chrome:// 페이지
• Chrome 웹스토어
• DRM 콘텐츠 (예: 넷플릭스 → 검은 화면)

이건 버그가 아니라 크롬 정책이다.

---

7. 디버깅은 Service Worker 콘솔에서

일반 웹 콘솔이 아니라

 

 확장 프로그램 → 서비스 워커 → 콘솔

 

여기서 로그를 확인해야 한다.

console.log("clicked", tab);

 

이 로그가 찍히는지부터 확인하면 문제 원인을 빠르게 찾을 수 있다.

---

최종 정리

이번 작업을 통해 느낀 핵심은 다음과 같다.

• Manifest v3에서는 DOM 사용 불가
• downloads API 필수
• activeTab 권한 중요
• async/await 방식 추천
• 확장 프로그램 새로고침 필수

간단한 기능이라도 환경 차이(MV2 → MV3) 때문에 생각보다 많은 삽질을 하게 된다.

---