클로드 코드로 앱을 만들면 코딩 자체는 빠릅니다. 2주 안에 기능이 다 만들어집니다. 근데 배포에서 막히는 사람이 많습니다. "로컬에서는 되는데 배포하면 안 돼요"가 그 상황입니다.
AI는 로컬 개발 환경 기준으로 코드를 짜줍니다. 배포 환경은 다릅니다. 이 간격을 모르면 배포에서 계속 막힙니다.
로컬과 배포의 차이
로컬에서 잘 되던 게 배포에서 안 되는 이유 대부분은 이 차이 때문입니다.
- 포트: 로컬은 3000 고정이지만 배포 플랫폼은 PORT 환경변수로 동적 할당
- 환경변수: 로컬 .env 파일은 배포 서버에 없음 — 직접 설정해야 함
- 도메인: 로컬은 localhost, 배포 후엔 다른 도메인 → CORS 에러 발생
- DB: 로컬 DB는 배포 서버에서 접근 불가 — 외부 DB 서비스 필요
- 파일 경로: 윈도우 로컬에서 되던 경로가 리눅스 서버에서 안 되는 경우
자주 나오는 에러와 해결
❌ "Application failed to respond" / 포트 에러
서버 코드에서 포트를 하드코딩했을 때 나옵니다.
const PORT = process.env.PORT || 3000 으로 바꾸면 해결됩니다.❌ 환경변수 undefined 에러
로컬 .env의 값들을 배포 플랫폼(Railway, Vercel)의 Environment Variables에 똑같이 입력해야 합니다. .env 파일 자체는 깃에 올리면 안 됩니다.
❌ CORS 에러
프론트와 백엔드가 다른 도메인이 되면 발생합니다. 백엔드에서
cors({ origin: 'https://your-frontend.vercel.app' }) 설정을 추가해야 합니다.❌ DB 연결 실패
로컬 DB는 배포 서버에서 접근 불가합니다. Supabase, PlanetScale, MongoDB Atlas 같은 외부 DB 서비스로 마이그레이션이 필요합니다.
어떤 플랫폼을 써야 하나
- Vercel: 정적 사이트, Next.js, React — 가장 쉽고 무료 티어 여유로움
- Railway: Express, Python, DB가 있는 풀스택 — 설정 쉽고 무료 티어 있음
- Render: Railway 대안 — 무료 티어는 느리지만 무료
배포는 코딩이 아닙니다. 모르면 막히는 게 정상입니다. 이 부분에서 시간 너무 쓰지 마세요.
배포 전 체크리스트
- 포트를
process.env.PORT로 받도록 수정 - .env 파일의 모든 변수를 플랫폼 환경변수에 입력
- package.json에 start 스크립트 있는지 확인
- node_modules는 .gitignore에 있는지 확인
- DB를 외부 서비스로 전환
- 배포 후 CORS 설정 업데이트
자주 묻는 질문
정적 사이트나 Next.js는 Vercel이 편합니다. Express, Python, DB가 필요한 풀스택은 Railway가 낫습니다. 둘 다 무료 티어가 있습니다.
로컬에서 .env 파일에 넣던 값들을 배포 플랫폼의 Environment Variables 설정에 똑같이 입력하면 됩니다. .env 파일 자체는 깃에 올리면 안 됩니다.
로컬에서는 같은 도메인이라 CORS가 없지만 배포 후엔 프론트와 백엔드가 다른 도메인이 됩니다. 백엔드에서 프론트 도메인을 허용하도록 CORS 설정을 추가해야 합니다.