앱이 완성됐습니다. 내 컴퓨터에서는 완벽하게 돌아갑니다. 친구에게 자랑하려고 주소창의 localhost:3000을 복사해서 보냈더니, 친구는 “안 열리는데?“라고 답합니다. 큰맘 먹고 배포라는 걸 했더니, 이번에는 내 컴퓨터에서 멀쩡하던 앱이 인터넷에서는 에러를 뿜습니다.
바이브 코딩에서 가장 많은 사람이 좌절하는 구간이 바로 여기, 배포입니다. 이번 편에서는 배포가 정확히 뭘 하는 일인지, 그리고 “로컬에선 되는데 배포하면 안 되는” 문제의 원인 대부분을 차지하는 세 가지를 풀어봅니다.
localhost는 “내 컴퓨터”라는 뜻입니다
localhost는 특별한 주소가 아니라 “지금 이 컴퓨터”를 가리키는 대명사입니다. 개발 중에 AI가 “localhost:3000에서 확인하세요”라고 하는 것은, 내 컴퓨터 안에서 임시로 돌고 있는 앱을 내 컴퓨터의 브라우저로 보라는 뜻입니다.
그러니 친구에게 localhost:3000을 보내면, 친구의 브라우저는 친구의 컴퓨터 안에서 앱을 찾습니다. 당연히 없죠. 내 앱은 아직 내 컴퓨터 밖으로 나간 적이 없으니까요. 게다가 내 컴퓨터의 앱은 개발 프로그램을 끄거나 노트북을 덮는 순간 꺼집니다. 다른 사람이 쓸 수 있는 서비스가 되려면 두 가지가 필요합니다. 24시간 켜져 있는 컴퓨터와, 누구나 찾아올 수 있는 주소.
배포는 이사입니다
이 두 가지를 해결하는 작업이 배포입니다. 배포는 한마디로 내 컴퓨터에 있던 앱을 서버로 이사시키는 일입니다. 서버라고 하면 거창하게 들리지만, 그냥 “24시간 켜져 있고 인터넷에 연결된 남의 컴퓨터”입니다.
바이브 코딩에서 많이 쓰는 Vercel이나 Netlify 같은 서비스가 이 이사를 대행해줍니다. 이들이 해주는 일은 세 가지입니다.
- 서버 임대: 자기네 데이터센터의 컴퓨터를 빌려줍니다.
- 빌드(build): 개발용 코드를 서비스용으로 변환·압축합니다. 이삿짐 포장인 셈입니다.
- 주소 발급:
내앱.vercel.app같은, 전 세계 누구나 접속할 수 있는 주소를 줍니다.
여기서 빌드라는 단어는 기억해둘 가치가 있습니다. 개발 모드는 관대해서 어지간한 문제는 눈감아주지만, 빌드는 엄격한 검사관이라 개발 중에는 조용하던 문제를 배포 직전에 무더기로 지적합니다. “로컬에선 되는데 배포가 실패해요”의 상당수가 이 빌드 단계에서 걸리는 것입니다.
로컬에선 되는데 배포하면 안 되는 3대 원인
배포에 성공했는데 앱이 이상하게 동작한다면, 원인은 십중팔구 다음 셋 중 하나입니다.
1위: 환경변수를 등록하지 않았다. 2편에서 API 키를 .env 파일에 넣고, 그 파일은 .gitignore로 Git이 따라가지 않게 했습니다. 그 결과 .env는 이삿짐에 실리지 않습니다. 서버에 도착한 내 앱은 키가 없어서 AI 호출도 DB 접속도 전부 실패합니다. 배포 서비스 대시보드의 “Environment Variables” 메뉴에 .env 내용을 등록하고 다시 배포하면 해결됩니다. 로컬에선 되는데 배포하면 안 될 때 가장 먼저 확인할 곳입니다.
2위: 빌드 검사에서 걸렸다. 배포 자체가 실패하면서 빨간 로그가 나오는 경우입니다. 당황할 것 없이 배포 서비스가 보여주는 빌드 로그를 통째로 복사해서 AI에게 붙여넣으면 됩니다. “빌드가 이 로그를 내면서 실패했어. 고쳐줘.”
3위: DB가 새 손님을 모른다. DB 서비스에 따라 “어디서 오는 접속을 허용할지” 설정이 있습니다. 지금까지는 내 컴퓨터에서만 접속했지만, 이제 서버가 접속하는 것이므로 허용 목록이나 접속 주소 설정을 손봐야 하는 경우가 있습니다. 이것도 증상(로그)을 AI에게 주면 빠르게 좁혀줍니다.
도메인: 주소를 내 이름으로
배포가 끝나면 내앱.vercel.app 같은 주소가 생깁니다. 이대로 써도 되지만, myapp.com 같은 내 도메인을 붙일 수도 있습니다. 도메인은 도메인 판매 사이트에서 연 단위로 빌리고, 연결 작업은 “이 이름으로 찾아오면 저 서버로 안내하라”는 전화번호부(DNS) 등록입니다. 배포 서비스 대시보드가 절차를 안내해주고, 등록 후 전 세계 전화번호부에 퍼지는 데 몇 분에서 하루쯤 걸릴 수 있습니다. 연결 직후에 바로 안 열린다고 당황하지 않아도 됩니다.
배포 후 3분 점검 루틴
배포 버튼을 눌렀다고 끝이 아닙니다. 매번 이 세 가지만 확인하면 사고의 대부분을 미리 잡습니다.
- 배포된 주소로 직접 접속합니다. 개발 중이던 localhost 말고, 실제 주소로요.
- 핵심 기능을 한 번씩 눌러봅니다. 회원가입, 저장, AI 호출처럼 백엔드와 환경변수가 얽힌 기능 위주로.
- 이상하다면 배포 서비스 대시보드의 로그(Logs) 메뉴를 열어 빨간 줄을 AI에게 복사해줍니다. 1편에서 말한 “서버의 비명”이 바로 여기 찍힙니다.
정리
localhost는 “내 컴퓨터”라는 뜻이라 남에게 보내도 열리지 않습니다.- 배포는 24시간 켜진 서버로 앱을 이사시키고 공개 주소를 받는 일이며, Vercel 같은 서비스가 대행해줍니다.
- 로컬과 배포의 차이 3대장: 환경변수 미등록(1위), 빌드 검사 탈락, DB 접속 설정. 특히
.env는 이삿짐에 실리지 않는다는 것만 기억해도 절반은 해결됩니다. - 도메인 연결은 전화번호부(DNS) 등록이라 퍼지는 데 시간이 걸릴 수 있습니다.
- 배포 후에는 실제 주소 접속 → 핵심 기능 클릭 → 로그 확인, 3분 루틴을 돌립니다.
다음 편은 에러 메시지입니다. 빨간 글씨를 무서워하지 않고 읽는 법, AI에게 에러를 제대로 전달하는 법, 그리고 AI가 같은 버그를 못 고치고 뱅뱅 돌 때 탈출하는 법을 다룹니다.