배포 (Deployment)
내 컴퓨터에서만 돌아가던 프로젝트를 인터넷에 올려서 누구나 접속할 수 있게 만드는 과정입니다.
🤔 혹시 이런 경험 있나요?
AI의 도움으로 멋진 웹 앱을 완성했습니다. 내 컴퓨터에서 localhost:3000으로 접속하면 잘 돌아갑니다. 그런데 친구에게 보여주고 싶어서 URL을 보냈더니... 접속이 안 됩니다. 당연합니다. localhost는 말 그대로 내 컴퓨터에서만 작동하니까요. 이 앱을 세상에 공개하려면 배포(Deployment)가 필요합니다.
🏠 localhost에서 인터넷으로
배포를 이해하려면 먼저 개발 환경과 운영 환경의 차이를 알아야 합니다.
| 구분 | 개발 환경 (localhost) | 운영 환경 (배포 후) |
|---|---|---|
| 접속 | 내 컴퓨터에서만 가능 | 전 세계 누구나 가능 |
| 주소 | localhost:3000 | myapp.vercel.app |
| 서버 | 내 컴퓨터가 서버 역할 | 클라우드 서버가 24시간 운영 |
| 데이터 | 로컬 DB 또는 테스트 데이터 | 실제 사용자 데이터 |
배포란 결국 "내 코드를 인터넷에 연결된 서버에 올려서, 24시간 돌아가게 만드는 것"입니다.
🚀 배포 플랫폼: 어디에 올릴까요?
과거에는 서버를 직접 사거나 임대해야 했지만, 지금은 클릭 몇 번으로 배포할 수 있는 플랫폼이 많습니다.
프론트엔드 + 서버리스 함수
| 플랫폼 | 특징 | 무료 범위 |
|---|---|---|
| Vercel | Next.js 공식 배포 플랫폼, 가장 간편함 | 개인 프로젝트 무료 |
| Netlify | 정적 사이트에 강하고, 폼 기능 내장 | 월 100GB 대역폭 |
| Cloudflare Pages | 전 세계 CDN, 빠른 속도 | 무제한 대역폭 |
백엔드 / 풀스택
| 플랫폼 | 특징 | 무료 범위 |
|---|---|---|
| Railway | DB 포함 풀스택 배포, 직관적 UI | 월 $5 크레딧 |
| Fly.io | Docker 기반, 글로벌 배포 | 소규모 무료 |
| Render | 자동 배포, 다양한 언어 지원 | 정적 사이트 무료 |
바이브코딩 초보자에게는 Vercel을 가장 추천합니다. GitHub 저장소를 연결하면 코드를 푸시할 때마다 자동으로 배포됩니다.
📝 배포의 기본 과정
Vercel을 예로 들면, 배포는 생각보다 간단합니다.
1. GitHub에 코드를 올립니다 (git push)
2. Vercel에 가입하고 GitHub 저장소를 연결합니다
3. Vercel이 자동으로 코드를 빌드합니다
4. 빌드가 성공하면 URL이 생성됩니다 (예: myapp.vercel.app)
5. 이제 누구나 이 URL로 접속할 수 있습니다이후에는 코드를 수정하고 git push만 하면 자동으로 재배포됩니다. 이것을 CI/CD(지속적 통합/지속적 배포)라고 합니다.
🌐 도메인: 나만의 주소 연결하기
배포하면 myapp.vercel.app 같은 기본 주소가 생깁니다. 하지만 실제 서비스라면 myapp.com 같은 커스텀 도메인을 사용하고 싶을 것입니다.
1. 도메인 구매 (가비아, Namecheap, Cloudflare 등)
2. 배포 플랫폼에서 도메인 설정
3. DNS 레코드 연결 (CNAME 또는 A 레코드)
4. HTTPS 인증서 자동 발급 (대부분 플랫폼이 자동 처리)대부분의 배포 플랫폼이 도메인 연결 가이드를 제공하므로, AI에게 "Vercel에 커스텀 도메인 연결하는 방법 알려줘"라고 물어보면 됩니다.
🔒 환경 변수: 배포 환경에서의 비밀 관리
개발할 때 .env 파일에 저장해둔 API 키와 DB 비밀번호는 배포 환경에서 별도로 설정해야 합니다. .env 파일은 GitHub에 올라가지 않으므로, 배포 플랫폼의 환경 변수 설정에서 직접 입력해야 합니다.
개발 환경: .env 파일에 저장
OPENAI_API_KEY=sk-abc123...
DATABASE_URL=postgresql://...
배포 환경: 플랫폼 대시보드에서 설정
Vercel → Settings → Environment Variables
Railway → Variables 탭이 단계를 빠뜨리면 배포 후 "환경 변수를 찾을 수 없습니다" 에러가 발생합니다. 배포 후 에러가 나는 가장 흔한 원인 중 하나이므로 꼭 확인하세요.
⚠️ 바이브코딩할 때 흔한 배포 실수
1. 환경 변수를 배포 플랫폼에 설정하지 않음
로컬에서는 잘 되는데 배포하면 에러가 나는 1순위 원인입니다. 배포 전에 .env 파일의 모든 변수를 배포 플랫폼에도 등록했는지 확인하세요.
2. 빌드 에러를 무시하고 배포 시도
npm run build를 로컬에서 먼저 실행해보세요. 여기서 에러가 나면 배포도 실패합니다. AI에게 빌드 에러 메시지를 그대로 보여주면 해결 방법을 알려줍니다.
3. 데이터베이스 연결 설정 누락
로컬 DB(localhost:5432)와 운영 DB는 다릅니다. Supabase, Neon 같은 클라우드 DB 서비스를 사용하고, 배포 환경의 DATABASE_URL을 올바르게 설정해야 합니다.
📋 30초 요약
-
배포는 내 컴퓨터의 프로젝트를 인터넷에 공개하는 과정입니다. Vercel, Netlify, Railway 같은 플랫폼을 사용하면 클릭 몇 번으로 가능합니다.
-
GitHub에 코드를 올리고 배포 플랫폼을 연결하면, 코드 수정 시 자동으로 재배포됩니다. 이것을 CI/CD라고 합니다.
-
배포 환경에는 환경 변수를 별도로 설정해야 합니다. 로컬에서 되는데 배포 후 안 되면, 환경 변수 설정을 가장 먼저 확인하세요.
바이브코딩으로 만든 앱을 Vercel에 배포했는데, 로컬에서는 잘 되던 기능이 배포 후에 작동하지 않습니다. 가장 먼저 확인해야 할 것은 무엇일까요?
연관 개념
훅 (Hooks) 알아보기
Claude Code가 특정 행동을 하기 전·후에 자동으로 실행되는 명령입니다. 파일 수정 직후 자동 포맷, 커밋 직전 lint 실행 같은 자동 검사·자동 작업을 만들 때 씁니다.
서브에이전트 (Subagents) 알아보기
한 작업의 부분을 따로 나눠 처리하는 보조 에이전트입니다. 주력 에이전트가 작업 전체를 조율하고, 서브에이전트들이 코드 검토, 자료 조사, 테스트 작성 같은 부분 작업을 동시에 처리해 결과를 합칩니다.
Plan Mode (실행 전 검토 단계) 활용하기
Claude Code가 실제로 파일을 수정하기 전에 무엇을 어떻게 바꿀지 계획만 먼저 보여주는 모드입니다. 사용자가 계획을 검토·승인한 뒤에야 실제 변경이 진행됩니다.
관련 인사이트
쉽게 설치하는 코덱스(Codex) CLI 세팅가이드(맥)
맥(Mac)에 OpenAI 코덱스 CLI(Codex CLI)를 처음 설치하는 분을 위해, 터미널 실행부터 Homebrew·Node.js 사전 준비, 본체 설치, ChatGPT 로그인, GPT-5.5 모델 선택까지 단순하게 정리했습니다. 클로드 코드(Claude Code)와의 차이도 마지막에 짧게 짚었습니다.
쉽게 설치하는 코덱스(Codex) CLI 세팅가이드(윈도우)
윈도우 PC에 OpenAI 코덱스 CLI(Codex CLI)를 처음 설치하는 분을 위해, PowerShell 관리자 모드부터 Node.js 준비, 본체 설치, ChatGPT 로그인, GPT-5.5 모델 선택까지 단순하게 정리했습니다. 클로드 코드(Claude Code)와의 차이도 마지막에 짧게 짚었습니다.
쉽게 설치하는 클로드코드 세팅가이드(맥)
맥(Mac)에 클로드 코드(Claude Code)를 처음 설치하는 분을 위해, 터미널 실행부터 Homebrew·Git·Node.js 사전 준비, 본체 설치, 한국어 설정, 첫 작업 시작까지 9단계로 단순하게 정리했습니다.
