배포수동 검토 가이드확인일 2026-07-07

로컬은 되는데 Vercel에 올리면 터질 때

집 컴퓨터에서는 되는데 배포 URL만 500·빈 화면·API 실패일 때, Vercel 비밀값 칸부터 순서대로 좁힙니다.

한 줄 결론

로컬과 배포의 차이는 거의 항상 비밀값 설정칸·코드 실행 장소(edge/node)·빌드 시점 코드에서 납니다.

아래 내용은 초보 바이브코더를 위한 일반 안내입니다. 서비스·지역·약관에 따라 달라질 수 있으며, 실제 사업화·운영 전에는 해당 분야 전문가 확인이 필요합니다.

먼저 용어부터 — 그다음 실행 프롬프트

env: 배포 서버에만 넣는 비밀 설정값
runtime: 코드가 edge(가벼움)에서 도는지 node(풀 기능)에서 도는지

Environment variables
이건 env(환경변수)입니다
비밀값·설정을 코드 밖에 두는 칸입니다. 로컬은 .env.local, 배포는 Vercel Environment Variables.
- 비밀은 Git에 커밋하지 않습니다
- 로컬과 배포 값이 다르면 ‘로컬만 됨’이 납니다
- 이름만 같아도 값이 비면 500이 납니다
이런 곳에 · OAuth secret · DATABASE_URL · API Key · CRON_SECRET
지금 할 일 · .env.example에 이름만 적고, 실제 값은 .env.local에만
비용·주의 · 잘못된 env로 무한 재시도하면 API 비용이 늘 수 있습니다.
AI 프롬프트 보기
```
Next.js + Vercel env 점검. 로컬은 되는데 배포만 실패. 필요한 키 목록(값 제외), Production 탭 확인 순서.
```

바로 실행 — AI 프롬프트

로컬 npm run dev는 되는데 Vercel만 500입니다. 에러 로그: [   ]. env 목록(값 제외). edge vs node runtime 차이 점검 순서.

막히면 다시 넣을 프롬프트

Vercel production 500. Function log: [   ]. 로컬과 다른 env: [   ]. middleware·runtime 설정 확인.

럭키스팟 해석은 원출처를 바탕으로 한 실전 안내입니다. 요금·약관·라이선스는 제공자 페이지 최신 조건을 결제·배포 전에 대조하세요. 실제 사업화 전에는 해당 분야 전문가 확인이 필요할 수 있습니다.

초보자 한 줄 설명

내 컴퓨터(.env.local)와 Vercel 서버는 별개입니다. 변수를 대시보드에도 똑같이 넣어야 합니다.

먼저 AI 에이전트에게 붙여넣을 프롬프트

Next.js 앱이 로컬 dev에선 되고 Vercel 프로덕션만 500이다.
증상: [   ]. 최근 변경: [   ].
1) Vercel Runtime Logs에서 볼 항목 순서
2) env 누락/오타 체크리스트
3) edge vs node 의심 시 확인할 파일 패턴
4) 로컬 production 재현 명령
추측 말고 위 순서대로만 안내.

AI가 해줄 수 있는 일

로컬 production 모드 재현 명령
env 누락·코드 실행 장소(edge/node) 의심 파일 짚기
Runtime Logs 읽는 순서 안내

사람이 직접 해야 하는 외부 설정

Vercel 대시보드에서 Runtime Logs 열기
Settings → Environment Variables에 비밀값 등록
로컬에서 npm run build && npm start로 먼저 재현

외부 설정 경로

Vercel → Project → Logs → Runtime Logs
Vercel → Project → Settings → Environment Variables
Supabase/Neon → Project Settings → Connection string

제대로 됐는지 확인하는 방법

로컬 production 모드에서 같은 에러가 나는지
env 이름 오타·Production 미적용이 없는지
문제 API만 curl로 호출해 상태 코드 확인

실행 순서

1Runtime Logs 첫 스택 확인
2Vercel env vs .env.example 대조
3로컬 npm run build && start
4문제 API만 curl
5preview 배포로 bisect

막히면 다시 AI에게 줄 프롬프트

Next.js가 로컬 dev에선 되고 Vercel 배포만 [500 / 빈 화면 / API만 실패].
증상: [   ], Runtime Log 첫 에러: [붙여넣기].
env 체크리스트·edge/node 의심 파일·로컬 build 재현만 순서대로.

막히는 지점

.env.local만 채우고 Vercel env 비움
edge에서 node 전용 패키지 사용
빌드 성공=런타임 성공으로 오해

비용·보안·저작권·약관 주의

로그에 secret 마스킹
프로덕션 DB 최소 권한
함수 실행·대역·DB 연결 과금. 로그 확인 습관 필요.

대안 도구

Netlify · Railway · self-host Docker

럭키스팟 판단

npm run build && npm start를 로컬에서 먼저 돌리면 배포 전에 절반은 걸러집니다.

이런 사람이 보면 좋음

처음 Vercel에 올려 보는 바이브코더
로컬 빌드는 통과하는데 배포 URL만 에러가 나는 사람
DB·API가 로컬에서만 연결되는 사람

초보자가 보통 착각하는 지점

.env.local만 채우면 Vercel에도 자동 적용된다고 생각합니다. Vercel → Settings → Environment Variables에 별도 등록이 필요합니다.
비밀값을 브라우저 화면 코드에서 그대로 쓰면 서버 비밀번호가 노출될 수 있는데, NEXT_PUBLIC_ 없이도 된다고 믿습니다.
빌드 로그가 초록색이면 실제 접속도 문제없다고 봅니다. 빌드 성공 후 첫 요청에서만 터지는 경우가 많습니다.

실제 점검 체크리스트

Vercel → Project → Settings → Environment Variables에 필수 비밀값이 Production·Preview 모두 들어갔는지 확인합니다.
브라우저에도 보이는 설정 이름(NEXT_PUBLIC_)과 서버 전용 비밀값을 구분했는지 확인합니다.
Supabase/Neon → Project Settings → Connection string이 배포에서 쓰는 주소인지 확인합니다.
API가 edge(가벼운 실행)인지 node(일반 서버)인지 확인하고, node 전용 패키지를 edge에 쓰지 않았는지 봅니다.
generateStaticParams·dynamic 설정 때문에 배포 환경에서 404가 나지 않는지 확인합니다.
로컬에서 npm run build && npm run start로 배포와 비슷한 모드를 한 번 돌려 봅니다.

실패했을 때 보는 순서

1Vercel → Project → Logs → Runtime Logs에서 첫 에러를 읽습니다.
2빌드 로그와 실행 로그를 구분합니다. 빌드만 성공한 경우가 많습니다.
3Vercel → Settings → Environment Variables에서 이름 오타·빈 값·Production 미적용 여부를 확인합니다.
4문제 나는 API 경로만 curl 또는 브라우저 네트워크 탭으로 직접 호출해 봅니다.
5edge ↔ node 실행 장소 변경이 필요한지 의심 파일을 점검합니다.
6최근 커밋을 revert하거나 preview 배포로 어느 시점부터 깨졌는지 좁힙니다.

배포 전 확인 항목

로컬에서 npm run build && npm run start로 프로덕션 모드를 한 번 돌려 봤습니다.
필수 환경 변수 목록을 README 또는 체크리스트로 적어 두었습니다.
health check용 간단한 /api/ping 또는 상태 페이지가 있습니다.
에러 시 사용자에게 보이는 메시지에 stack trace·secret이 없습니다.

보안·법적 주의

환경 변수는 팀원 공유 시에도 채팅·이슈에 평문으로 붙이지 마세요.
프로덕션 DB URL·관리자 키는 최소 권한 계정을 쓰는 것이 일반적입니다. 실제 운영 전 보안 전문가 검토를 권합니다.
로그에 개인정보·토큰이 남지 않도록 마스킹하세요.

Vercel배포환경변수프로덕션