배포(deploy)까지 — 실제 서비스로 올리기

🌍 만든 것을 세상에 보여줄 시간

로컬에서 동작하는 앱은 내 컴퓨터에서만 볼 수 있습니다. 다른 사람이 접근하려면 배포(Deploy)가 필요합니다. 배포란 앱을 인터넷에 연결된 서버에 올려서 URL로 접근 가능하게 만드는 것입니다. 이번 강의에서는 Vercel을 기준으로 첫 배포 과정을 단계별로 배웁니다.

🚀 Vercel을 선택하는 이유

배포 플랫폼은 여러 가지가 있지만(Netlify, Railway, Render, AWS...), 입문자에게는 Vercel이 가장 추천됩니다:

• GitHub 저장소 연결만으로 자동 배포 (코드 푸시 → 자동으로 새 버전 배포)
• Next.js 창시팀이 만들어 Next.js와 완벽 호환
• 무료 플랜이 개인 프로젝트에 충분
• HTTPS, CDN이 자동으로 적용

📋 첫 배포 체크리스트

배포 전 확인 사항:

• ☐ GitHub 저장소에 코드가 올라가 있는가?
• ☐ npm run build가 에러 없이 성공하는가? (로컬에서 먼저 확인)
• ☐ 환경변수 목록을 파악했는가? (.env.local에 있는 모든 키)
• ☐ .gitignore에 .env.local이 포함되어 있는가?

⚙️ Vercel 배포 절차

1. Vercel 가입: vercel.com → GitHub 계정으로 로그인
2. 새 프로젝트 추가: "New Project" → GitHub 저장소 선택
3. 환경변수 설정: Settings → Environment Variables → .env.local의 모든 키·값 입력
4. 배포: "Deploy" 클릭 → 1~3분 후 완료
5. URL 확인: your-app.vercel.app 형태의 URL로 접근

💡 이후 git push하면 Vercel이 자동으로 새 버전을 배포합니다.

🔐 환경변수 — 로컬과 배포 환경의 차이

로컬에서는 .env.local에서 환경변수를 읽습니다. 하지만 Vercel에서는 .env.local이 없습니다 — Vercel 대시보드에서 직접 설정해야 합니다.

배포 후 "환경변수를 찾을 수 없다"는 에러가 나면:

Vercel 배포 후 process.env.WEATHER_API_KEY가 undefined라고 나와. 어떻게 설정해야 해?

AI가 Vercel 환경변수 설정 방법을 안내해줍니다.

🐛 첫 배포의 흔한 실패와 해결

에러	원인	해결
Build failed	로컬에서 안 잡히던 타입 에러	npm run build 로컬 실행 후 에러 수정
환경변수 undefined	Vercel에 환경변수 미설정	Vercel 대시보드 → Environment Variables 추가
API 호출 실패	CORS 또는 도메인 허용 미설정	API 서비스에서 배포 도메인 허용 설정
Database 연결 안 됨	DB가 로컬만 허용	DB 설정에서 외부 접근 허용 또는 connection string 확인

🌐 커스텀 도메인 연결

기본으로 주어지는 your-app.vercel.app 대신 자체 도메인을 연결할 수 있습니다:

1. 도메인을 구매합니다 (가비아, 후이즈 등)
2. Vercel Project Settings → Domains → 도메인 추가
3. 도메인 구매처에서 DNS 설정 (Vercel이 안내해주는 CNAME 또는 A 레코드 추가)

이 과정도 AI에게 현재 도메인 구매처를 알려주면 단계별 안내를 받을 수 있습니다.

✅ 정리

• 배포 전 npm run build를 로컬에서 먼저 실행해 에러를 없애세요.
• 환경변수는 Vercel 대시보드에 직접 설정해야 합니다.
• GitHub push → 자동 배포가 기본 흐름입니다.
• 배포 에러는 Vercel 로그를 AI에게 보여주면 해결됩니다.