📝 한줄 요약
Claude Code와 함께 Next.js 가계부 웹앱을 Vercel에 처음 배포해보면서, 첫 배포는 성공했지만 두 번째 배포에서 만난 'No Next.js detected' 에러를 빌드 로그 한 줄로 추적해 해결한 후기입니다.
달력이 컴퓨터 화면에 표시됩니다
원형 차트가 포함된 대시보드 스크린샷
검정색 배경의 화면 스크린샷
바쁘시면 이것만 읽어도 돼요:
목표: 흩어져 있던 지출 기록을 한 곳에 모을 가계부 웹앱 MVP를 만들고, 진짜 공개 URL까지 가보기
인상 깊었던 순간: 환경변수 4개 (Google OAuth 2개, NEXTAUTH_SECRET, NEXTAUTH_URL)를 어떻게 채워야 하는지 AI가 순서대로 안내해줘서 흐름이 한 번도 끊기 지 않았다
막혔던 곳: 두 번째 배포에서 "Next.js를 못 찾겠다"는 에러가 났는데, 코드는 멀쩡한데 왜 안 되는지 막막했음
핵심 해결 방법: 에러 메시지만 보지 말고, 빌드 로그 전체를 AI에게 통째로 넘겼더니 "removed 441 packages in 2s" 한 줄에서 단서를 짚어줌 → Vercel 대시보드의 Root Directory 설정을 의심 → 한 번에 해결
얻은 것: 배포·디버깅을 자력으로 할 수 있게 됐고, 다른 Next.js 프로젝트에도 그대로 재사용 가능한 워크플로우를 손에 넣음
배운 교훈: "AI에게 줄 정보가 많을수록 답이 정확해진다" — 에러 메시지 한 줄만 던지면 일반론이 돌아오지만, 로그 전체를 던지면 단서를 짚어낸다
🎯 이런 분들께 도움돼요
Next.js 코드는 짤 줄 알지만 Vercel 배포는 이번이 처음인 개발자
Vercel CLI를 처음 써보거나, OAuth 환경변수 세팅 흐름을 한 번에 정리해두고 싶은 분
에러가 떴을 때 AI한테 어떤 정보를 어떤 형태로 던지면 효율적인지 패턴을 익히고 싶은 분
GPTers Claude Code 스터디 토요일 과제처럼 "MVP를 배포까지 가져가야 하는" 상황의 스터디 참여자
😫 문제 상황 (Before)
개인 지출을 매번 메모장에 끄적이거나 이런저런 가계부 앱에 흩어져서 기록하고 있었어요. 한 달 지나서 다시 보려고 하면 "그때 그 식비를 어디다 적었더라" 하면서 여러 앱을 뒤지는 게 일이었고요.
원하는 건 단순했어요. 달력에 서 그날 클릭하면 지출이 보이고, 차트로 카테고리별 합계를 한눈에 볼 수 있는 나만의 도구. 큰 기능은 필요 없고, 우선 한 화면이라도 작동하는 MVP를 만들어서 진짜 공개 URL로 띄워보는 것이 이번 토요일 과제의 목표였습니다.
지금까지 Claude Code로 스킬을 만드는 것까진 해봤지만, 실제 사용자가 접속할 수 있는 배포 단계는 처음이었어요. 그래서 "이번 한 번은 처음부터 끝까지 가본다"를 목표로 잡았습니다.
🛠️ 사용한 도구
도구명: Claude Code
모델: Claude Opus 4.7 (1M context)
배포 플랫폼: Vercel (Fluid Compute, Node.js 24)
기술 스택 (AI가 잡아준 것): Next.js 14 + NextAuth (Google 로그인) + FullCalendar (달력) + Recharts (차트) + Tailwind CSS
🔧 작업 과정
환경변수 4개 채우기 — 외우지 말고 순서대로 받기
배포 직전, 빌드를 한 번 돌려보려고 했는데 .env.local 파일에 채워야 할 변수가 4개 있더라고요. Google OAuth 클라이언트 ID/Secret, NEXTAUTH_SECRET, NEXTAUTH_URL. 이름만 봐서는 뭘 어디서 가져와야 하는지 막막했어요.
그래서 그냥 통째로 던졌습니다.
# .env.local 파일을 열어 4개 변수 채우기:
# GOOGLE_CLIENT_ID=...
# GOOGLE_CLIENT_SECRET=...
# NEXTAUTH_SECRET=$(openssl rand -base64 32)
# NEXTAUTH_URL=http://localhost:3000
npm run build # 빌드 에러 확인
해당 내용을 채우려면 어떻게 해야하는지 순서대로 알려줄래
AI가 단계별로 안내해줬어요.
Google Cloud Console에서 OAuth 2.0 클라이언트 만들기 — 어디로 들어가서, 어떤 메뉴를 눌러서, 콜백 URL은 뭘로 설정해야 하는지 한 줄씩
NEXTAUTH_SECRET 생성 —
openssl rand -base64 32명령어 한 줄로 즉시 시크릿 생성 (외울 필요 없이 그때그때 받으면 됨)NEXTAUTH_URL 설정 — 로컬은
http://localhost:3000, 나중에 Production용은 Vercel 배포 후 URL로 바꿔야 한다는 주의사항까지빌드 검증 — 다 채운 다음
npm run build로 환경변수 누락이 있 는지 한 번 확인
여기서 "오!" 했던 부분이 있어요. 사람이 알려주면 보통 "환경변수가 뭐고, 왜 필요하고, Google Cloud Console이 뭐고…" 하는 배경 설명부터 시작하잖아요. AI는 "지금 당장 클릭할 메뉴 → 복사할 값 → 어느 줄에 붙여넣을지" 만 정확히 짚어줘서 흐름이 한 번도 안 끊겼어요. 모르는 건 추가로 물어보면 되니까 우선 진행이 중요했죠.
Vercel CLI 설치와 로그인 — 인터랙티브 입력은 사용자가 직접
환경변수가 다 채워졌으니 이제 배포할 차례. Vercel CLI도 처음이라 한 줄씩 받았습니다.
npm i -g vercel
vercel --version
vercel login
여기서 살짝 막혔던 건 vercel login이 브라우저를 열어서 인증을 받는 인터랙티브 명령어였다는 점이에요. AI가 직접 실행하면 입력을 받을 사람이 없으니 멈춰버립니다.
해결은 간단했어요. 명령어 앞에 !를 붙여서 사용자가 직접 실행하면 됐어요. (Claude Code의 기능)
! vercel login
이러면 제가 직접 명령을 실행하고, 결과(브라우저 인증 완료 메시지)는 다시 AI 화면으로 돌아옵니다. 흐름이 안 끊기죠.
첫 배포 성공 — vercel --prod 한 줄
로그인까지 끝나고 vercel --prod를 실행했더니, 의외로 한 번에 됐어요. CLI가 자동으로:
.vercel/project.json파일을 만들어서 프로젝트를 Vercel 계정에 자동 연결환경변수 4개를 Production 환경에 한 번에 등록
빌드 → 배포 → 공개 URL 발급까지 한 흐름으로 처리
여기까지가 토요일 오후의 작업이었어요. "어, 생각보다 쉽네?" 하고 마무리하려는 순간이었죠.
다음 날, 두 번째 배포에서 막힘 — "No Next.js detected"
다음 날 다시 배포를 했더니 갑자기 빌드가 실패합니다.
Error: No Next.js version detected.
Make sure your package.json has "next" in either "dependencies" or "devDependencies".
Also check your Root Directory setting matches the directory of your package.json file.
당황스러웠어요. 어제는 됐는데 오늘은 왜 안 되지? 코드는 하나도 안 바뀌었고, package.json을 열어봐도 next: 14.2.5가 멀쩡히 들어있었거든요.
검색해보면 흔한 해결책은 "package.json에 next 추가하세요" 같은 일반론인데, 제 경우엔 이미 들어 있었으니 도움이 안 됐어요.
빌드 로그 통째로 던지기 — "removed 441 packages" 한 줄의 단서
여기서 AI한테 그냥 에러 메시지가 아니라 빌드 로그 전체를 까서 보여달라고 했어요.
이거 디버깅 좀 도와줘
[Vercel 빌드 실패 화면 그대로 복붙]
AI가 vercel inspect --logs 명령으로 빌드 로그 전체를 가져왔어요. 그리고 사람 눈에는 잘 안 보일 한 줄을 짚어줬어요.
"'removed 441 packages in 2s' — 이게 핵심 단서예요.
npm install이 패키지를 설치한 게 아니라 제거한 거예요. 이건 업로드된package.json에next같은 dependency가 안 들어있다는 뜻이에요. 그런데 우리 로컬package.json엔 멀쩡히 있죠. 그럼 Vercel이 보는 package.json이 다른 위치의 것이라는 얘기예요."
그러면서 가설을 하나 던졌어요.
"Vercel 대시보드의 Root Directory 설정에 혹시
web/같은 값이 들어있나요? CLI는 이미web/폴더에서 업로드를 시작하는데, 대시보드에서도web/를 설정해 놓으면 Vercel은web/web/package.json을 찾게 돼서 못 찾는 거예요."
대시보드 들어가서 Settings → Build and Development Settings → Root Directory를 확인했는데… 비어 있었어요. 가설은 살짝 빗나갔지만, 어쨌든 정상 설정이 확인됐으니 일단 다시 배포만 해보기로 했어요.
Root Directory 비어있어, 다시 배포해봐
vercel --prod 한 번 더 → 16초 만에 빌드 성공. 깔끔하게 끝났어요. 첫 배포 직후 캐시가 잠시 꼬여 있었던 것 같은데, 정확한 원인을 100% 짚진 못해도 로그 분석 → 가설 → 검증 사이클을 한 번 돌린 것만으로도 다음에 같은 에러를 만났을 때 어디서부터 봐야 할지 감이 잡혔어요.
✅ 결과 (After)
Before vs After
항목
Before
After
지출 기록
메모장·앱 여러 곳에 흩어짐
공개 URL 하나로 접근 가능
배포 능력
Vercel 배포 한 번도 안 해봄
CLI 설치 → 환경변수 → 배포 → 에러 디버깅까지 자력
에러 대응
에러 메시지로 구글링
빌드 로그를 통째로 AI에게 던지는 패턴
다음 프로젝트
0부터 시작
같은 워크플로우를 다른 Next.js 앱에 그대로 재사용 가능
결과물
기술 스택: Next.js 14 + NextAuth (Google 로그인) + FullCalendar + Recharts + Tailwind
빌드 시간: 16초
💬 이 과정에서 배운 AI 활용 팁
효과적이었던 것
에러 메시지 한 줄만 던지지 말고 로그 전체를 통째로 던지기 — 에러 메시지만 던지면 일반론(검색하면 나오는 답)이 돌아옵니다. 빌드 로그 200줄을 통째로 던지면 AI가 사람 눈에 안 보이는 한 줄(예: "removed 441 packages")을 단서로 짚어줘요. 정보를 많이 줄수록 답이 정확해집니다.
외울 명령어는 외우지 말고 흐름으로 묻기 —
openssl rand -base64 32같은 한 줄을 외우는 것보다 "환경변수 4개 채우려면 어떻게 해?"라고 흐름으로 물어보는 게 빠릅니다. AI가 그때그때 필요한 명령을 정확한 순서로 던져줘요.인터랙티브 입력은
!접두사로 사용자가 직접 —vercel login처럼 브라우저 인증이 필요한 명령은 AI가 직접 못 돌립니다.! vercel login처럼 사용자가 받아서 실행하면 결과가 다시 AI 화면으로 돌아와서 흐름이 안 끊겨요.
이렇게 하면 안 돼요
검색부터 시작하기 — 에러가 떴다고 곧장 구글링부터 가면 일반론에 휘둘려서 본인 상황과 안 맞는 해결책을 시도하게 됩니다. 먼저 AI한테 로그를 통째로 줘서 본인 상황에 맞는 가설부터 받으세요.
AI한테 "왜 안 돼?"만 묻기 — "왜 안 돼?"보다 "이 로그/에러 메시지/현재 설정을 보고 가능한 원인을 짚어줘"가 훨씬 정확한 답을 받습니다.
🌍 다른 업무에 적용한다면?
API 호출이 실패할 때 — 응답 메시지만 보지 말고 요청·응답 헤더 + 상태 코드 + 본문을 통째로 던지면 인증 토큰 만료, CORS, 페이로드 형식 등 정확한 원인을 짚어줍니다.
사내 도구의 빌드/배포 실패 — Jenkins, GitHub Actions 등 어디든 로그를 통째로 던지는 패턴이 통합니다.
엑셀 함수가 안 돌 때 — 에러 셀 하나만 캡처하지 말고 수식 + 참조하는 셀 + 데이터 형식까지 함께 던지세요.
핵심은 같아요. "이 에러 왜 떠?" → "이 컨텍스트 전부를 보고 가능한 원인을 짚어줘" 로 질문 패턴을 바꾸는 것.
🚀 앞으로의 계획
이번 배포가 끝이 아니라 시작이에요. 다음 주차 PRD 워크스페이스로 이어가서 기능을 한 단계씩 붙일 계획입니다.
카테고리별 차트 — 식비/교통/문화 등 카테고리 단위로 월간 분포 시각화
월간 리포트 — 매월 1일 자동 정리되는 한 달 요약 뷰
예산 알림 — 카테고리별 예산 한도에 가까워지면 알림
데이터 영속화 — 지금은 로그인까지만이라 다음은 Vercel Marketplace의 데이터베이스(Neon Postgres, Upstash Redis 등) 연결
토요일 MVP를 베이스로 PRD를 다듬어서 한 단계씩 진행하는 게 2주차 목표입니다.
📋 재사용 가능한 프롬프트
프롬프트 1: 환경변수 처음 채울 때
다음 환경변수를 채워야 하는데, 각각 어디서 어떻게 가져와야 하는지 순서대로 알려줘. 외울 필요 없이 그때그때 받아서 진행할 수 있게 명령어 한 줄씩 던져주면 좋겠어.
[채워야 할 환경변수 이름들 붙여넣기][본인 프로젝트의 프레임워크/플랫폼] 환경입니다.
프롬프트 2: 배포·빌드 에러로 막혔을 때
배포에서 다음 에러가 떴어. 에러 메시지만 보고 일반적인 해결책을 주지 말고, 빌드 로그 전체를 까서 사람 눈에 안 보이는 단서가 있는지 먼저 짚어줘. 그 단서로 가능한 원인 가설 2-3개를 우선순위 매겨서 알려줘.
[에러 메시지 + 빌드 로그 통째로 붙여넣기]현재 프로젝트 구조: [폴더 구조 한 줄 요약]
프롬프트 3: 인터랙티브 명령이 필요할 때
다음 명령은 브라우저 인증/사용자 입력이 필요해서 AI가 직접 못 돌리지? 내가 직접 실행할 수 있게
! 명령어형식으로 알려주고, 결과를 어디서 어떻게 확인하면 다음 단계로 넘어갈 수 있는지도 알려줘.[실행이 필요한 명령]
