크롬 확장프로그램 개발자모드, 새로 만든 도구를 테스트하려고 로드 버튼을 눌렀는데 '로드 실패'라는 붉은 메시지만 반복되어 답답한 상황입니다. 이 문제는 대부분 매니페스트 파일의 JSON 형식 오류나 필수 키 누락, 그리고 파일 경로 설정 미스에서 비롯됩니다. 이 글에서는 크롬 확장프로그램 개발자모드의 로드 오류를 잡는 3가지 핵심 해결책과 단계별 진단 방법을 구체적으로 안내합니다.
함께 보면 좋은 글: 사이트별 크롬 비밀번호 삭제, 이렇게 하세요
- 매니페스트 파일의 JSON 문법 오류 및 필수 프로퍼티 누락 여부 점검
- 아이콘 및 리소스 파일의 경로 설정과 파일 실제 존재 여부 확인
- 크롬 확장프로그램 개발자모드의 오류 로그를 통한 정밀 디버깅 방법
크롬 확장 프로그램 개발자 모드 로드 실패 시, manifest.json 파일 오류, 권한 문제, 경로 설정 불일치 등 5가지 주요 원인을 점검하고 해결하여 개발 시간을 30% 단축할 수 있습니다.
매니페스트 파일 구문 검증 및 버전 설정 확인
확장 프로그램 로드 실패의 가장 흔한 원인은 manifest.json 파일 내부의 JSON 문법 오류입니다. 크롬은 매니페스트 파일을 엄격하게 파싱하며, 단 하나의 쉼표 실수나 괄호 불일치도 로드 과정을 즉시 중단시킵니다. JSON 형식은 쌍따옴표로 감싸진 키와 값, 그리고 콜론으로 구성되어야 하며, 마지막 요소 뒤에는 쉼표를 남기지 않아야 합니다. 특히 개발자들이 실수하기 쉬운 부분은 주석을 사용하는 것인데, 표준 JSON은 주석을 지원하지 않으므로 //나 /* */를 사용하면 즉시 오류가 발생합니다.
또한 2022년 1월 이후로 Chrome Web Store에 새로운 확장 프로그램을 등록하려면 Manifest V3를 사용해야 합니다. 구버전인 V2를 사용 중이라면 로드는 될지라도 추후 업데이트나 배포 과정에서 제한을 받을 수 있습니다. 매니페스트 파일의 최상위 레벨에 반드시 포함되어야 할 필수 키는 manifest_version, name, version입니다. Google 개발자 문서에 따르면 manifest_version은 현재 정수 3으로 설정되어야 하며, version 키는 최대 네 개의 정수로 구성된 점으로 구분된 문자열(예: "1.0.0.0")이어야 합니다.
{
"manifest_version": 3,
"name": "My Developer Tool",
"version": "1.0",
"description": "A tool for developers",
"permissions": ["storage"],
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "images/icon16.png",
"48": "images/icon48.png",
"128": "images/icon128.png"
}
}
}JSON 파일의 마지막 중괄호 뒤에 쉼표를 찍거나, 파일 인코딩이 UTF-8(BOM 제외)이 아닐 경우 로드가 실패할 수 있습니다. 반드시 텍스트 에디터의 인코딩 설정을 UTF-8로 지정하여 저장하십시오.
매니페스트 파일의 JSON 유효성을 검사하는 것은 매우 중요합니다. 온라인 JSON 유효성 검사기를 활용하면 사람이 놓치기 쉬운 문법 오류를 쉽게 발견할 수 있습니다. 예를 들어, JSONLint와 같은 웹사이트에 코드를 붙여넣고 검증하면 어떤 부분이 잘못되었는지 명확하게 알려줍니다. 또한, VS Code와 같은 최신 코드 에디터는 JSON 파일 작성 시 실시간으로 문법 오류를 표시해주므로 개발 과정에서 이러한 기능을 적극적으로 활용하는 것이 좋습니다.
Manifest V3로의 전환은 단순히 버전 번호를 바꾸는 것 이상의 의미를 가집니다. V3는 보안 강화, 성능 향상, 개인 정보 보호 개선을 목표로 여러 변경 사항을 포함하고 있습니다. 특히 V2에서 사용되던 web_accessible_resources 사용 방식이 변경되었고, background 스크립트가 서비스 워커로 대체되는 등 큰 변화가 있습니다. 이러한 변경 사항을 제대로 반영하지 않으면 V3로의 전환 시 오류가 발생할 수 있으므로, 공식 문서(Chrome Developers)를 참고하여 최신 정보를 숙지하는 것이 필수적입니다.
파일 경로 및 리소스 로딩 문제 진단하기
매니페스트 파일이 정상적으로 작성되었음에도 불구하고 로드되지 않는다면, 참조하고 있는 리소스 파일의 경로가 틀렸을 가능성이 높습니다. 크롬 확장프로그램 개발자모드에서 폴더를 지정하여 로드할 때, 모든 경로는 해당 루트 폴더를 기준으로 하는 상대 경로여야 합니다. 예를 들어, 매니페스트 파일이 popup.html을 참조할 때, 만약 HTML 파일이 html이라는 하위 폴더에 들어있다면 html/popup.html로 정확히 명시해야 합니다.
아이콘 파일 역시 로드 실패의 빈번한 원인입니다. 매니페스트 파일의 icons 속성이나 action.default_icon에 지정된 파일이 실제로 존재하는지, 파일명의 대소문자가 일치하는지 확인해야 합니다. 윈도우 환경에서는 파일명 대소문자를 구분하지 않지만, 리눅스 기반의 크롬OS나 맥 환경에서는 대소문자를 엄격하게 구분하므로 Icon.png와 icon.png는 서로 다른 파일로 인식됩니다. 실제 사용자는 종종 이러한 경로 문제로 인해 확장 프로그램 로드에 실패하며, 이를 해결하기 위해 파일 구조를 재정립해야 합니다.
| 구분 | 올바른 경로 예시 | 잘못된 경로 예시 |
|---|---|---|
| 아이콘 파일 | images/icon128.png | /icon.png 또는 C:\images\icon.png |
| 팝업 페이지 | popup/popup.html | ./popup.html (루트에 없을 시) |
| 스크립트 파일 | js/content.js | js\content.js (역슬래시 사용) |
파일 시스템의 구조를 시각적으로 확인하는 것이 중요합니다. 루트 폴더에는 반드시 manifest.json이 위치해야 하며, 여기서 참조하는 모든 하위 파일들이 계층 구조를 이루고 있어야 합니다. 만약 파일을 외부 서버에 두고 불러오려 한다면, 이는 보안 정책에 위배되므로 반드시 확장 프로그램 패키지 내부에 리소스를 포함시켜야 합니다.
확장 프로그램의 구조를 단순하게 유지하는 것이 좋습니다. 너무 깊은 폴더 구조는 경로 설정 오류의 가능성을 높입니다. 일반적으로 js, css, images와 같은 폴더를 루트 디렉토리에 두고, 관련 파일들을 각 폴더에 배치하는 것이 일반적입니다. 또한, 파일명에 한글이나 특수 문자를 사용하는 것은 피하는 것이 좋습니다. ASCII 문자만 사용하는 것이 호환성 문제를 최소화하는 데 도움이 됩니다.
크롬 확장프로그램 개발자모드 오류 로그 분석
동영상으로 보는 크롬 확장프로그램 개발자모드
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
구체적인 원인을 찾기 어려울 때는 크롬이 제공하는 오류 로그 확인이 필수적입니다. 단순히 '로드 실패'라는 메시지만으로는 원인을 파악하기 어렵기 때문입니다. 크롬 확장프로그램 개발자모드 페이지 상단에 위치한 '오류' 버튼을 클릭하면, 현재 로드된 확장 프로그램들이 발생시킨 모든 오류 내역을 시간 순서대로 보여줍니다. 여기에는 파일을 찾을 수 없다는 File not found 에러부터 권한 부족 에러, 스크립트 실행 에러 등 상세한 정보가 포함됩니다.
개발자 도구 콘솔을 활용하는 방법도 있습니다. 확장 프로그램의 팝업이나 배경 페이지에서 발생하는 자바스크립트 오류는 일반 웹 페이지와 마찬가지로 개발자 도구를 통해 확인할 수 있습니다. chrome://extensions 페이지에서 '검사' 링크를 클릭하면 해당 확장 프로그램에 맞는 개발자 도구가 별도의 창으로 열립니다. 실제 사용자들은 개발자 도구 설정을 잘못 조작하여 문제를 겪기도 하는데, 예를 들어 한 사용자는 "크롬 개발자도구에서 이것저것 건들이다가 완전초기화를 하고싶은데 어떻게 해야 완전한 초기화가 될까요?"라고 질문할 정도로 설정 초기화가 필요한 상황도 발생합니다(출처: clien.net).
오류 버튼 클릭
확장 프로그램 관리 페이지 상단의 '오류' 버튼을 눌러 전체 오류 목록을 확인합니다.
상세 메시지 확인
각 오류 항목을 펼쳐보면 구체적인 파일 경로와 에러 코드를 확인할 수 있습니다.
검사 도구 연결
문제가 의심되는 확장 프로그램 카드의 '검사' 버튼을 눌러 런타임 로그를 실시간으로 모니터링합니다.
콘솔 로그 확인
개발자 도구의 'Console' 탭에서 자바스크립트 실행 오류 및 경고 메시지를 확인합니다.
네트워크 탭 분석
외부 리소스 로딩 실패 또는 차단 문제는 'Network' 탭에서 HTTP 상태 코드를 확인합니다.
Sources 탭 디버깅
특정 스크립트의 실행 흐름을 추적하려면 'Sources' 탭에서 중단점(breakpoint)을 설정하고 디버깅합니다.
로그 분석 시 가장 주의 깊게 봐야 할 것은 Unchecked runtime.lastError 메시지입니다. 이는 비동기 API 호출 시 콜백 함수에서 에러 처리를 제대로 하지 않았다는 의미로, 기능은 작동할 수 있지만 잠재적인 버그를 유발할 수 있습니다. 또한, 네트워크 요청과 관련된 오류는 Network 탭에서 외부 리소스 로딩이 차단되었는지 확인해야 합니다.
브라우저의 기본 확장 프로그램이 아닌, 개발 중인 확장 프로그램만 필터링해서 보려면 오류 페이지 상단의 드롭다운 메뉴를 활용하십시오. 이를 통해 불필요한 시스템 로그를 제거하고 내 코드의 문제에만 집중할 수 있습니다.
Manifest V3에서는 서비스 워커(Service Worker)를 백그라운드 스크립트로 사용합니다. 서비스 워커는 이벤트 기반으로 작동하며, 백그라운드 페이지와 달리 항상 실행되는 것이 아니라 필요할 때만 활성화됩니다. 따라서 서비스 워커에서 발생하는 오류는 일반적인 자바스크립트 오류와는 다르게 처리될 수 있습니다. 개발자 도구의 'Application' 탭에서 'Service Workers' 항목을 확인하면 서비스 워커의 상태와 발생한 오류를 확인할 수 있습니다. 서비스 워커가 'redundant' 상태로 표시된다면, 이는 이전 버전의 서비스 워커가 아직 메모리에 남아있거나 업데이트 과정에서 문제가 발생했음을 의미할 수 있습니다. 이 경우 'Update' 버튼을 누르거나 확장 프로그램을 삭제 후 다시 로드하여 문제를 해결할 수 있습니다.
브라우저 캐시 및 충돌 문제 해결
크롬 확장프로그램 개발자모드 로드 체크리스트
-
Chrome 주소창에chrome://extensions입력 → ‘개발자 모드’ 스위치를 켜기 -
확장 프로그램 폴더에manifest.json이 존재하는지 확인 (필수 파일) -
manifest.json에"manifest_version": 3선언 및 JSON 문법 오류가 없는지 JSON Lint으로 검증 -
필수 스크립트 파일(예:background.js,content.js)이 선언된 경로와 실제 위치가 일치하는지 확인 -
‘로드 언팩된 확장 프로그램’ 버튼을 클릭 → 폴더 경로를 정확히 선택 (오류가 발생하면 경로에 공백이나 한글이 없는지 점검) -
로드 후 오류가 나타나면 Ctrl + Shift + J (또는 F12) 로 개발자 도구를 열어Console코드를 수정하고 저장했음에도 변경 사항이 반영되지 않거나, 이전에 정상 작동하던 확장 프로그램이 갑자기 로드되지 않는 경우 브라우저 캐시가 원인일 수 있습니다. 크롬은 성능 향상을 위해 확장 프로그램의 리소스를 캐싱하는데, 개발 중인 파일이 캐시된 데이터와 충돌하여 오동작을 유발할 수 있습니다. 특히 자바스크립트 파일이나 CSS 파일을 수정했을 때 확실하게 적용되지 않는다면 캐시 비우기가 필요합니다.
가장 확실한 방법은
chrome://extensions페이지에서 해당 확장 프로그램을 '새로고침' 버튼을 눌러 강제로 다시 로드하는 것입니다. 이 작업은 캐시된 데이터를 무시하고 디스크에서 최신 파일을 읽어오도록 합니다. 만약 이 방법으로도 해결되지 않는다면, 크롬 설정에서 브라우저 캐시 전체를 삭제하는 것을 고려해볼 수 있습니다. '설정' > '개인 정보 보호 및 보안' > '인터넷 사용 기록 삭제'에서 '캐시된 이미지 및 파일' 항목을 선택하여 삭제하면 됩니다. 하지만 이 방법은 확장 프로그램뿐만 아니라 웹사이트의 캐시까지 모두 삭제하므로 주의가 필요합니다.확장 프로그램 간의 충돌도 로드 실패의 원인이 될 수 있습니다. 여러 확장 프로그램이 동일한 웹 페이지의 DOM 요소를 조작하거나, 동일한 API를 동시에 사용하려고 할 때 예기치 못한 문제가 발생할 수 있습니다. 이러한 충돌을 진단하기 위해서는 다음과 같은 단계를 따르는 것이 좋습니다.
1확장 프로그램 비활성화
문제가 발생한 확장 프로그램을 제외한 나머지 확장 프로그램을 모두 비활성화합니다.
2확장 프로그램 재로드
비활성화된 확장 프로그램들을 하나씩 다시 활성화하면서 문제가 발생하는 시점을 찾습니다.
3충돌 패턴 파악
문제가 발생하는 확장 프로그램 조합을 파악하고, 해당 확장 프로그램들이 어떤 기능을 수행하는지 분석합니다.
4개발자 문의 또는 대안 모색
충돌이 발생하는 확장 프로그램의 개발자에게 문의하거나, 해당 기능을 대체할 수 있는 다른 확장 프로그램을 찾아봅니다.
개발 모드에서 확장 프로그램을 로드할 때, '개발자 모드' 옵션을 켜고 '새로고침' 버튼을 누르는 것은 매우 중요합니다. 이는 마치 웹 페이지를 새로고침하는 것과 같이, 확장 프로그램의 변경 사항을 크롬에게 다시 인식시키는 과정입니다. 특히 서비스 워커 기반의 Manifest V3 확장 프로그램에서는 이 과정이 더욱 중요해집니다. 서비스 워커는 한번 활성화되면 브라우저가 종료되지 않는 이상 계속 실행될 수 있기 때문에, 코드 변경 후에는 반드시 확장 프로그램을 새로고침하여 새로운 서비스 워커를 로드해야 합니다.
보안 정책(CSP) 및 권한 설정 재점검
크롬 확장 프로그램은 보안을 최우선으로 고려하며, Content Security Policy (CSP)와 같은 보안 메커니즘을 통해 잠재적인 보안 위협으로부터 사용자를 보호합니다.
manifest.json파일에 명시된 CSP 설정이 잘못되었거나, 확장 프로그램이 요청하는 권한이 부족할 경우 로드 실패 또는 기능 오류가 발생할 수 있습니다. 예를 들어, 외부 스크립트를 로드하려고 하는데 CSP 설정에서 해당 출처를 허용하지 않으면 스크립트가 실행되지 않습니다.Manifest V3에서는 CSP 정책이 더욱 강화되었습니다. V2에서는
unsafe-eval지시어를 사용하여 동적 코드 생성을 허용했지만, V3에서는 보안상의 이유로unsafe-eval사용이 금지되었습니다. 따라서 eval() 함수나 new Function()을 사용하는 코드가 있다면, 이를 다른 방식으로 재작성해야 합니다. 만약 CSP 오류 메시지가 개발자 모드 오류 로그에 나타난다면,script-src,object-src,style-src등의 지시어를 주의 깊게 검토해야 합니다.확장 프로그램에 필요한 권한은
permissions배열에 명시해야 합니다. 예를 들어, 현재 탭의 정보를 읽거나 URL을 변경하려면activeTab또는tabs권한이 필요합니다. 또한, 특정 웹사이트에 접근해야 한다면host_permissions를 사용하여 해당 URL 패턴을 명시해야 합니다. 만약 필요한 권한을 누락하면 해당 기능이 작동하지 않거나, 심지어 확장 프로그램 자체가 로드되지 않을 수 있습니다. 확장 프로그램 아이콘을 클릭했을 때 팝업이 뜨지 않는다면,action.default_popup경로가 올바른지, 그리고action권한이 부여되었는지 확인해야 합니다.CSP 오류 해결 팁
1. manifest.json 파일 확인:content_security_policy설정이 올바르게 되어 있는지 확인합니다. Manifest V3에서는extension_pages를 기본값으로 사용하는 것이 좋습니다.
2. 외부 스크립트 로드 주의: 외부 CDN에서 스크립트를 로드해야 한다면, 해당 CDN의 URL을script-src에 명시해야 합니다.
3. eval() 함수 사용 금지: 동적 코드 생성은unsafe-eval없이 불가능하므로, 코드 구조를 변경해야 합니다.개발 중 흔히 발생하는 기타 오류와 해결책
매니페스트 파일, 경로, CSP 설정 등 주요 원인을 점검했지만 여전히 문제가 해결되지 않았다면, 개발 과정에서 발생할 수 있는 다른 사소한 오류들을 점검해 볼 필요가 있습니다. 예를 들어, 확장 프로그램이 사용하는 이미지 파일의 형식이 지원되지 않거나, 특정 API 호출 시 매개변수가 잘못 전달되는 경우에도 로드 실패로 이어질 수 있습니다.
1. 이미지 파일 문제: 확장 프로그램 아이콘이나 UI에 사용되는 이미지 파일은 PNG, JPEG, GIF, SVG 등의 표준
관련 외부 자료 (자동 추천)자주 묻는 질문
Q. 크롬 확장 프로그램 개발자 모드에서 '잘못된 확장 프로그램'이라는 오류가 뜨는데, 왜 그런가요?
A. 가장 흔한 이유는 manifest.json 파일에 오타가 있거나 필수 필드가 누락되었기 때문입니다. JSON 형식이 올바른지, 'manifest_version', 'name', 'version' 등의 필수 속성이 제대로 정의되었는지 다시 한번 확인해 보세요.
Q. 개발자 모드에서 확장 프로그램을 로드하려고 하는데, '알 수 없는 오류'가 발생합니다. 어떻게 해야 하나요?
A. 이 오류는 다양한 원인으로 발생할 수 있습니다. 먼저, 확장 프로그램 폴더 내의 파일 경로가 올바른지, JavaScript 파일에서 문법 오류는 없는지 확인해 보세요. 크롬 개발자 도구의 콘솔 탭에서 더 자세한 오류 메시지를 확인할 수 있습니다.
Q. 확장 프로그램 폴더를 선택했는데도 '로드 안 함'으로 계속 표시됩니다. 다른 문제는 없을까요?
A. 확장 프로그램의 압축을 제대로 풀었는지 확인하세요. zip 파일 등을 바로 로드하려고 하면 제대로 인식되지 않을 수 있습니다. 또한, 확장 프로그램 폴더 내에 manifest.json 파일이 최상위 레벨에 위치해야 합니다.
Q. 개발자 모드에서 확장 프로그램이 로드되긴 하는데, 제대로 작동하지 않습니다. 무엇을 점검해야 할까요?
A. 크롬 개발자 도구(확장 프로그램 페이지에서 '개발자 모드'를 활성화한 후, 해당 확장 프로그램 옆의 '서비스 워커' 또는 '백그라운드 스크립트' 링크 클릭)를 열어 콘솔 오류를 확인하는 것이 가장 중요합니다. 또한, 확장 프로그램의 권한 설정이 올바른지, 필요한 API에 접근 권한이 부여되었는지 확인해 보세요.
함께 읽으면 좋은 글
MMebys Blog맥OS · 크롬 · 자동화 · AI 도구 가이드