이 강의 사이트(hans17.com)를 실제로 만들며 부딪힌 에러와 해결책 20선. 대부분 한 번은 겪습니다.
배포 · Vercel
1. Cannot find module '.v0/inject-built-with-v0.mjs' — v0로 만든 프로젝트의 빌드 커맨드가 그 파일을 찾음. → 레포에 no-op 스텁(process.exit(0))을 두거나 빌드 커맨드를 next build로.
2. vercel env add ... preview 가 git_branch_required — CLI 52 버그. → npm i -g vercel@latest 후 --value <v> --yes, 또는 대시보드에서 추가.
3. 정적 파일이 배포에서 404(업로드 누락) — macOS에서 저장/클립보드로 만든 파일의 확장속성(com.apple.quarantine, ls에 @)을 CLI가 건너뜀. → xattr -c <file> 또는 ffmpeg/sips로 재인코딩.
4. 런타임 fs.readFileSync 가 Vercel에서 파일 못 찾음 — 정적분석으로 추적 안 됨. → next.config의 outputFileTracingIncludes에 경로 추가, 또는 JSON은 import.
5. vercel env pull 안 해서 값이 undefined — 로컬에 키 없음. → vercel env pull 로 동기.
빌드 · Next.js
6. Unrecognized key 'eslint' in NextConfig — Next 16에서 제거됨. → next.config에서 eslint 키 삭제.
7. params/searchParams 가 Promise — Next 15+. → const { id } = await params;
8. 거대 JSON import 로 타입체크가 느림/멈춤 — tsc가 거대 리터럴 타입 추론. → fs.readFileSync+JSON.parse 또는 as 캐스팅.
로컬 · 사내망
9. tsx 스크립트에서 키가 undefined — tsx는 .env.local 자동 로드 안 함. → 실행 시 키를 환경변수로 주입.
10. 사내 프록시 self-signed certificate in chain — MITM 프록시. → NODE_EXTRA_CA_CERTS=./회사CA.pem, DB는 sslmode 제거 + ssl rejectUnauthorized false.
RAG · 임베딩
11. 검색이 0건(한국어) — text-embedding-3-small은 한국어 유사도가 낮음(관련 매치도 0.2~0.4). → threshold 0.15~0.2(0.3은 과함).
12. pgvector insert 실패 — 임베딩 배열을 그대로 못 넣음. → '[0.1,0.2,...]' 텍스트 형태로 insert.
13. anon 키로 테이블 조회가 빈 결과(RLS) — select 정책 없음. → 읽기는 SECURITY DEFINER RPC(세션 필터)로, 직접 select는 차단.
14. Supabase MCP net::ERR_FAILED — 사내 프록시 차단. → DDL은 Postgres 직접 연결(pg)로.
LLM
15. Claude JSON 응답 앞뒤에 설명이 붙음 — JSON Mode 없음. → 정규식/코드펜스 파싱 extractJSON() + 스키마 프롬프트.
16. 한국어 비용이 예상보다 큼 — 영어 대비 토큰 약 2.5배. → 반복 프롬프트는 영어로 · Prompt Caching.
음성 · 미디어
17. TTS 401 / 빈 오디오 — 잘못된 voice id 또는 키. → ElevenLabs Voices에서 id 재확인, 키 확인.
18. 오디오가 자동재생 안 됨 — autoplay 정책. → 사용자 클릭(제스처) 후 play(). 막히면 ▶ 버튼 노출.
19. 외부 오디오(Apple 미리듣기) 재생 — CORS 걱정. → <audio src> 미디어 재생은 CORS 불필요, 그대로 됨.
기타
20. mailto로 파일 첨부가 안 됨 — 표준상 불가. → 본문에 다운로드 링크, 진짜 첨부는 서버 발송(Resend).
핵심 정리
- 십중팔구 환경변수 · 인증서 · threshold · xattr 넷 중 하나입니다.
- 에러 메시지를 그대로 강사 Agent나 Claude Code에 붙여 넣고 물어보세요 — 대부분 위 패턴입니다.
