본문으로 건너뛰기

05. 막혔을 때

이 페이지는 사람들이 가장 자주 멈추는 자리를 모아 둔 곳입니다. 본인이 보고 있는 증상과 가까운 항목을 찾아 그 아래의 안내를 따라가 보세요. 이 페이지에 없는 증상이라면 에러 메시지를 그대로 복사해서 Claude Code에 붙여 넣고 "이거 어떻게 고쳐?" 라고 물으면 다음에 시도할 만한 한 수가 보통 따라옵니다.

환경 설정에서 막힐 때​

Node가 설치되지 않습니다​

대개 nvm install 20 이 도중에 멎거나 그냥 실패한 상태입니다.

macOS와 Linux에서는 새 터미널을 열고 command -v nvm 을 실행해 봅니다. 출력이 비어 있다면 nvm 자체는 설치됐지만 셸 시작 파일(.zshrc 또는 .bashrc)에 로더가 안 들어간 상태입니다. nvm 설치 출력 끝부분에 적혀 있던 두 줄(export NVM_DIR="$HOME/.nvm" ...)을 그 파일 안에 손으로 붙여 넣고 새 터미널을 엽니다.

Windows에서는 WSL2 설치를 끝까지 마쳤는지 다시 한번 확인합니다. 이 가이드의 명령은 PowerShell에서 동작하지 않습니다. 모든 단계는 WSL2 위 Ubuntu 셸 안에서 실행해야 합니다.

node --version 이 v20보다 낮은 숫자를 출력합니다​

여러 Node 버전이 깔려 있고 시스템 기본이 옛 버전을 가리키는 상태입니다.

nvm use 20
nvm alias default 20

이 두 줄을 실행한 다음 새 터미널을 열고 node --version 을 다시 확인합니다.

pnpm install 이 권한 에러로 실패합니다​

EACCES 또는 permission denied 가 보인다면 npm 글로벌 설치 위치 권한이 가장 흔한 원인입니다. 이 base는 글로벌 설치가 필요 없으니 다음을 순서대로 시도해 봅니다.

  • sudo 로 다시 시도하지 마세요. 보통 문제를 더 키웁니다.
  • 이전 시도에서 만들어진 node_modules/ 가 있다면 지우고 다시: rm -rf node_modules pnpm-lock.yaml.
  • 그래도 안 풀리면 nvm으로 깐 Node를 다시 설치: nvm uninstall 20 && nvm install 20.

init.sh 가 멈췄습니다​

bash init.sh 가 도중에 멈춘 자리는 화면에 마지막으로 출력된 줄이 알려 줍니다.

어디서 멈췄나어디를 보면 되나
pnpm install 자리위의 "pnpm install이 권한 에러로 실패합니다" 항목
pnpm run typecheck 자리타입 에러 출력을 복사해 Claude Code에 붙여 넣습니다. 보통 원인은 tsconfig.json 의 path alias 불일치이거나 의존성 버전 불일치입니다.
pnpm run build 자리빌드 로그를 끝까지 읽어 봅니다. CRXJS 에러가 보인다면 manifest.config.ts 의 entry-point 경로가 틀린 경우가 가장 많습니다.

Chrome이 확장을 로드하지 못합니다​

"압축해제된 확장 프로그램을 로드합니다" 에서 내 폴더가 안 보입니다​

dist/ 폴더를 가리켜야 합니다. 빌드를 아직 한 번도 안 돌렸다면 pnpm run build 부터 실행하세요. 폴더는 보이는데 회색으로 흐릿하게 떠서 못 고른다면 dist/ 안에 manifest.json 이 있는지 확인합니다. 없으면 빌드가 끝까지 가지 못한 상태입니다.

"manifest 파일이 누락되었거나 읽을 수 없습니다"​

dist/manifest.json 이 생성되지 않았거나 깨진 상태입니다. pnpm run build 를 다시 실행하고 빌드 로그에서 누락된 에러가 없는지 확인합니다.

확장은 로드됐는데 아이콘이 안 보입니다​

Chrome 우측 상단의 퍼즐 모양 아이콘을 누르면 설치된 확장 목록이 펼쳐집니다. 거기서 본인 확장을 찾아 핀 아이콘을 누르면 툴바에 고정됩니다.

첫 실행이 아무 반응도 없습니다​

사이드패널이 안 열립니다​

먼저 Chrome 버전이 114 이상인지 확인합니다 (chrome://version). sidepanel API는 Chrome 114에 들어왔습니다. 버전이 충분한데도 안 열린다면 manifest.json 을 열어 permissions 배열에 sidePanel 이 있는지 확인합니다. 빠져 있다면 트리거 UI 모드 설정이 반영되지 않은 상태입니다.

"Analyze and send" 가 콘솔에 아무것도 안 찍습니다​

옵션 페이지(chrome://extensions → 본인 확장 → 세부정보 → 확장 프로그램 옵션)에서 백엔드 모드가 console-log 로 설정돼 있는지 먼저 확인합니다.

다음으로, 어느 콘솔을 보고 있는지가 처음에 흔히 헷갈리는 자리입니다. 사이드패널 자체의 콘솔은 사이드패널 안에서 우클릭 → "검사" → Console 탭으로 들어갑니다. background service worker는 콘솔이 따로 있습니다. chrome://extensions 의 본인 확장 카드에서 세부정보를 누른 다음 "Service Worker" 링크를 클릭하면 따로 떠오릅니다. 분석된 페이로드는 보통 background 콘솔 쪽에 찍힙니다.

백엔드 연결에서 막힐 때​

401 또는 403 에러​

supabase-direct 라면 Supabase의 Settings → API 페이지에서 anon key (anon public 행)를 다시 복사합니다. service_role 키는 절대 확장 안에서 쓰지 마세요. 이 키는 데이터에 전권을 가지므로 확장에 박아 배포하는 순간 보안 사고가 됩니다.

server-relay 라면 토큰 끝에 공백이나 줄바꿈이 따라 붙었는지 확인합니다. 옵션 페이지에 붙여 넣을 때 흔한 원인입니다.

Supabase에 데이터가 들어오지 않습니다​

Table Editor를 열고 page_contents 가 실제로 존재하는지 먼저 확인합니다. SQL Editor에서 만든 테이블이 다른 스키마에 들어가 있을 수 있으니 public 스키마인지 확인하세요. 이상이 없다면 Authentication → Policies 로 가서 만들어 둔 RLS 정책이 INSERT를 허용하는지 확인합니다. 둘 다 정상이라면 DevTools의 Network 탭을 열고 supabase.co 로 향한 요청의 응답 본문을 읽어 봅니다. 거절된 이유가 거기 적혀 있습니다.

CORS 에러 — server-relay 전용​

서버가 확장의 origin을 허용해야 합니다. 확장의 origin은 chrome-extension://<extension-id> 이고, extension-id는 chrome://extensions 의 본인 확장 카드에 표시됩니다. 그 origin을 서버의 Access-Control-Allow-Origin 에 추가합니다. private 배포 가정 아래라면 모든 chrome-extension:// origin을 허용해도 됩니다.

빌드와 패키징에서 막힐 때​

pnpm run package 가 zip을 못 만듭니다​

pnpm run build 가 먼저 정상으로 끝나야 합니다. dist/ 폴더가 없거나 비어 있으면 package가 만들 자리가 없습니다. 빌드 로그를 끝까지 읽고, 에러가 보이면 그 메시지를 Claude Code에 붙여 넣습니다.

dev 서버가 갑자기 안 뜹니다​

pnpm run dev 실행 시 포트가 이미 사용 중이라는 메시지가 보일 수 있습니다. 이전에 실행해 둔 dev 서버가 종료되지 않은 경우입니다. 새 터미널을 열고 lsof -ti:5173 | xargs kill 같은 명령으로 그 포트를 잡고 있는 프로세스를 종료한 다음 다시 실행하세요. 포트 번호가 5173이 아닐 수 있으니 화면의 메시지를 한 번 더 확인합니다.

코드를 수정했는데 확장에 반영이 안 됩니다​

크게 두 가지 자리를 의심해 봅니다. 먼저 dev 서버가 돌고 있는지 확인하세요. pnpm run dev 가 멎어 있다면 새 빌드가 떨어지지 않은 상태입니다. 다음으로 background service worker는 자동 리로드가 다른 진입점보다 늦게 따라옵니다. chrome://extensions 의 본인 확장 카드에서 새로고침 아이콘을 한 번 누르면 강제로 재기동됩니다.

content script 수정은 페이지를 새로고침해야 반영되는 경우가 많습니다. 같은 탭에서 F5를 누르면 새 content script가 다시 주입됩니다.

권한 변경 후 자동으로 비활성화됩니다​

Chrome이 manifest의 권한이 바뀐 것을 감지하면 사용자에게 다시 동의를 받기 위해 확장을 일시적으로 비활성화합니다. chrome://extensions 에서 본인 확장 카드를 보고 토글이 꺼져 있다면 다시 켭니다. 새 권한에 대한 안내가 한 번 뜨면 동의를 누른 다음 정상 동작합니다.

확장 ID가 갑자기 바뀌었습니다​

이런 일이 생기면 거의 항상 .crx 패키징 키 (.pem)가 바뀌었거나 unpacked 로 다시 로드한 경우입니다. unpacked로 로드된 확장은 폴더 경로 기반으로 ID가 정해지고, 다른 폴더로 옮기면 새 ID가 됩니다. self-host .crx 배포 중이라면 06-distribution의 ".pem 키 만들기와 보관" 항목을 다시 확인하세요. 같은 키로 같은 폴더에서 패킹해야 ID가 유지됩니다.

그 밖에​

이 페이지에 같은 증상이 없다면 두 가지를 더 시도해 볼 수 있습니다.

먼저, 에러 메시지 전체를 복사해 Claude Code에 붙여 넣고 "이거 고쳐 줘" 라고 입력합니다. 다음에 시도할 한 수를 보통 잘 짚어 줍니다.

그래도 풀리지 않는다면 GitHub 이슈를 열거나 팀 Slack에 글을 올립니다. 다음 세 가지를 함께 적어 주세요.

  • 어디서 막혔는지 (어느 파일, 어느 명령)
  • 에러 메시지 전체
  • 환경 정보 (macOS / Linux / Windows, Node 버전, Chrome 버전)