16강: 배포
세상에 공개하기
이제 내 노트북 밖으로 나갈 시간이에요
15강에서 우리는 에러라는 불청객을 다루는 디버깅(버그를 잡는 과정)을 배웠어요. 이제 여러분의 노트북, 즉 로컬(내 컴퓨터 환경)에서는 서비스가 아주 매끄럽게 돌아가고 있을 거예요. 로그인도 되고, 데이터도 잘 저장되죠.
하지만 웹 서비스의 진짜 목적은 다른 사람들이 내 서비스를 쓰게 만드는 거잖아요? 내 노트북에서만 돌아가는 서비스는 일기장에 쓴 글과 같아요. 이제 그 일기장을 책으로 출판해서 전 세계 사람들이 읽을 수 있게 만들 차례입니다.
기억하시나요? 우리는 8강에서 GitHub Pages(깃허브가 제공하는 무료 호스팅)를 사용해 간단한 화면을 배포해 본 적이 있어요. 하지만 그때는 데이터베이스나 로그인이 없는 아주 단순한 문서 형태였죠.
지금 우리가 만든 건 Supabase(데이터베이스)와 연결되고 서버가 필요한 '진짜' 애플리케이션입니다. 이런 서비스는 좀 더 똑똑하고 강력한 배포 도구가 필요해요. 그래서 오늘 우리는 Vercel(버셀) 이라는 마법 같은 도구를 사용해서 세상에 우리 서비스를 공개할 거예요.
코딩 1줄 모르는 저도 클릭 세 번으로 AI//STUDY 사이트를 배포했습니다. 여러분도 당연히 하실 수 있어요.
이건 뭐예요? — 식당 건물 짓기 vs 배달의민족 등록하기
웹사이트를 인터넷에 올리는 과정을 배포(Deployment) 라고 부릅니다. 예전에는 이 배포라는 게 정말 끔찍하게 어려운 작업이었어요.
예전 방식을 식당 창업에 비유해 볼게요. 과거에는 웹사이트를 띄우려면 서버(24시간 켜져 있는 컴퓨터)를 돈 주고 임대해야 했어요. 식당 건물을 짓는 것과 같죠. 거기에 Linux(서버용 운영체제)를 설치하고, 보안 설정을 하고, FTP(파일 전송 프로그램)로 내 코드를 일일이 복사해서 올렸어요. 전기 공사부터 인테리어까지 다 직접 하는 느낌이었습니다.
하지만 지금 우리가 쓸 Vercel(버셀) 은 완전히 다릅니다. Vercel은 굳이 비유하자면 '배달의민족'이나 '공유 주방' 같은 서비스예요. 건물 짓고 인테리어 할 필요가 전혀 없어요. 여러분은 그냥 GitHub(코드를 보관하는 깃허브)라는 주방에 '맛있는 요리(코드)'만 준비해 두면 됩니다.
- Vercel = 코드를 인터넷에 올려주는 택배 서비스
- 여러분이 GitHub에 코드를
push(업로드) 하면, - Vercel이 그걸 자동으로 알아채고 가져가서 예쁘게 포장합니다. (이 포장 과정을 Build(빌드) 라고 해요)
- 그리고 인터넷 세상에 URL(웹 주소)을 만들어서 배달을 완료합니다. (이게 바로 Deploy(배포) 입니다)
가장 놀라운 건, 한 번 설정해 두면 앞으로 코드를 수정하고 GitHub에 올릴 때마다 Vercel이 알아서 새 버전으로 교체해 준다는 거예요. 우리가 할 일은 그냥 평소처럼 git push를 하는 것뿐입니다.
8강의 GitHub Pages와 뭐가 다른가요?
8강에서 배운 GitHub Pages도 훌륭한 도구예요. 하지만 역할이 조금 달라요.
| 비교 항목 | GitHub Pages (8강) | Vercel (16강) |
|---|---|---|
| 할 수 있는 것 | 정적 파일(HTML, CSS, JS)만 올릴 수 있어요 | 서버 기능(API, 로그인 처리 등)까지 가능해요 |
| 데이터베이스 연결 | 불가능해요 | 환경 변수로 Supabase 등 연결 가능해요 |
| 빌드 과정 | 직접 빌드해서 결과물을 올려야 해요 | git push만 하면 Vercel이 알아서 빌드해요 |
| HTTPS (보안 자물쇠) | 지원 돼요 | 자동 적용돼요 |
| 적합한 용도 | 블로그, 문서 사이트, 포트폴리오 | 로그인이 있는 웹 앱, SaaS, 대시보드 |
14강에서 "16강에서 배울 Vercel에 배포하면 HTTPS가 자동 적용된다"고 예고했었죠? HTTPS(HyperText Transfer Protocol Secure)란 브라우저 주소창에 자물쇠 아이콘이 뜨는 보안 연결이에요. Vercel에 배포하면 별도 설정 없이 자동으로 적용됩니다. 사용자의 비밀번호나 개인 정보가 암호화되어 전송되니까 안전해요.
우리는 이렇게 쓰고 있어요 — AI//STUDY의 자동 배포
저희 디온웍스도 모든 웹 서비스를 Vercel을 통해 배포하고 있어요.
지금 여러분이 보고 계시는 이 AI//STUDY 사이트(ai.d-onworks.com) 역시 Vercel 위에서 돌아가고 있습니다. 제가 오타를 발견하거나 새로운 강의를 추가할 때, 서버에 접속해서 복잡한 명령어를 칠까요? 절대 아닙니다.
저는 그냥 클로드 코드에게 "16강 내용 수정해 줘"라고 말하고, 코드가 수정되면 이렇게 한글로 말합니다.
깃 커밋 푸쉬 해
네, 그냥 한글로만 입력해도 잘됩니다. 클로드가 알아서 커밋 메시지를 만들고, GitHub에 코드를 올려줘요. 그러면 Vercel이 약 30초에서 1분 정도 혼자서 윙윙 돌아가더니, ai.d-onworks.com 사이트에 새로운 내용을 반영해 줍니다. 수동으로 '다시 배포' 버튼을 누를 필요조차 없어요.
자동 배포의 마법 — 코드 수정부터 반영까지
이 과정을 좀 더 자세히 풀어볼게요. 실제로 일어나는 일은 이래요.
- 코드 수정: 클로드 코드에게 "이 부분 고쳐줘"라고 말해요
- git push: 터미널에서
git push origin main한 줄을 입력해요 - Vercel 감지: GitHub에 새 코드가 올라온 걸 Vercel이 자동으로 알아채요 (Webhook이라는 알림 시스템 덕분이에요)
- 빌드 시작: Vercel이 코드를 가져가서 포장(빌드) 작업을 시작해요
- 배포 완료: 보통 30초~2분이면 새 버전이 인터넷에 반영돼요
- URL 그대로: 주소는 바뀌지 않아요. 같은 URL로 접속하면 최신 버전이 보여요
이 전체 과정에서 우리가 하는 일은 2번(git push) 딱 한 줄뿐이에요. 나머지는 Vercel이 다 알아서 해줍니다.
저희가 만든 사내 인사관리 시스템인 DGHR이나, 견적 관리 시스템인 HoneyERP도 마찬가지예요. 다만 이런 시스템들은 중요한 고객 정보나 데이터베이스 비밀번호를 다루기 때문에, Vercel의 환경 변수(Environment Variables) 라는 금고에 비밀번호를 안전하게 보관하는 기능을 적극적으로 활용하고 있답니다.
한번 써볼까요? — Vercel 배포 4단계
자, 이제 여러분의 프로젝트를 전 세계에 공개해 봅시다. 클로드 코드 터미널은 잠시 내려두고, 웹 브라우저를 열어주세요.
1단계: Vercel 가입하기
- 브라우저에서 vercel.com 에 접속합니다.
- 우측 상단의 Sign Up 버튼을 누릅니다.
- Continue with GitHub(깃허브 계정으로 계속하기)를 선택해서 로그인합니다.
- GitHub 연동 권한을 묻는 화면이 나오면 Authorize(허용)를 눌러주세 요.
- (우리의 모든 코드는 이미 GitHub에 있으니까, GitHub 계정으로 가입하는 게 가장 편해요!)
2단계: 프로젝트 가져오기 (Import)
- 로그인이 완료되면 Vercel 대시보드(관리 화면)가 나옵니다.
- 화면에 있는 Add New... 버튼을 누르고 Project를 선택하세요.
- 그러면 내 GitHub에 있는 저장소(Repository) 목록이 쫙 뜹니다.
- 만약 목록에 프로젝트가 안 보인다면, Adjust GitHub App Permissions 링크를 눌러서 Vercel이 해당 저장소에 접근할 수 있도록 권한을 추가해 주세요.
- 배포하려는 프로젝트 이름 옆에 있는 Import 버튼을 클릭합니다.
3단계: 환경 변수 설정하기 (정말 중요해요!)
가장 많이 실수하는 부분입니다. 12~14강에서 우리는 .env.local 파일에 Supabase 주소나 API 키 같은 비밀번호를 넣었죠? 이 파일은 해킹을 막기 위해 GitHub에 안 올라가도록 설정되어 있어요.
GitHub에 비밀번호가 없으니, Vercel도 우리 데이터베이스 주소를 모릅니다. 그래서 Vercel에게 몰래 비밀번호를 알려줘야 해요. 비유하자면, 금고 비밀번호를 적은 쪽지를 Vercel 담당자에게 직접 건네주는 거예요.
보통 클로드 코드에게 "Vercel에 배포해 줘"라고 말하면, 클로드가 먼저 우리 프로젝트의 .env.local 파일을 살펴보고 "이 환경 변수들을 Vercel에 등록해 주세요"라고 목록을 알려줘요.
이 목록을 보고 Vercel 대시보드에서 하나씩 입력하면 돼요. 방법은 이래요.
- Vercel 대시보드에서 내 프로젝트를 클릭하고, Settings > Environment Variables 메뉴로 들어갑니다.
- Key 칸에 이름표(예:
NEXT_PUBLIC_SUPABASE_URL)를 넣고, Value 칸에 값(예:https://abcdefg.supabase.co)을 넣어요.
- Add 버튼을 눌러주세요. 클로드가 알려준 목록의 키를 전부 이 방식으로 추가하면 돼요.
.env.local파일에 있는 모든 키를 빠짐없이 넣어야 해요. 하나라도 빠지면 배포 후 화면이 안 뜰 수 있어요.
4단계: Deploy (배포) 버튼 누르기
모든 키를 넣었다면, 제일 아래에 있는 파란색 Deploy 버튼을 누릅니다.
화면에 종이 꽃가루가 터지는 애니메이션이 나올 때까지 1~2분 정도 기다려주세요. Vercel이 열심히 코드를 빌드(포장) 하는 중입니다.
꽃가루가 터지면 성공입니다! 화면에 보이는 내-프로젝트.vercel.app 같은 링크를 클릭하면 인터넷에 올라간 여러분의 서비스를 볼 수 있어요.
배포가 완료되면 Vercel 대시보드에 Status: Ready(초록 불)가 표시돼요. 이 화면이 보이면 내 서비스가 전 세계 인터넷에 정상적으로 올라간 거예요.
이후에는 코드를 수정하고 GitHub에 푸시할 때마다 Vercel이 자동으로 새 버전을 배포해줘요. 별도로 Vercel 사이트에 접속할 필요 없이, 코드만 푸시하면 끝입니다.
클로드 코드 터미널에서는 이렇게
Vercel 배포는 버튼 클릭으로 끝나지만, 배포하기 전에 우리 컴퓨터에서 코드를 깔끔하게 정리하고 GitHub에 올려두는 작업이 필요해요.
이때 클로드 코드를 활용하면 아주 편합니다. 클로드 코드 대화창에서 !를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.
배포 전 로컬 빌드 테스트
Vercel에 올리기 전에, 내 컴퓨터에서 먼저 빌드가 잘 되는지 확인하는 게 좋아요. 여기서 에러가 나면 Vercel에서도 100% 에러가 나거든요.
# 내 컴퓨터에서 빌드(포장)가 잘 되는지 테스트해 봅니다
# 에러 없이 끝나면 Vercel 배포도 성공할 가능성이 높아요
! npm run build
빌드가 성공하면 터미널에 초록색 글씨로 "Compiled successfully" 같은 메시지가 나와요. 빨간 에러가 나오면 15강에서 배운 디버깅 방법으로 먼저 해결하세요.
GitHub에 코드 올리기
에러 없이 끝났다면, 코드를 GitHub에 올립니다.
# 변경된 파일을 모두 스테이징(포장 준비)합니다
! git add .
# 어떤 변경인지 메모를 남깁니다 (커밋)
! git commit -m "첫 Vercel 배포 준비 완료"
# GitHub로 코드를 보냅니다 — 이 순간 Vercel이 자동으로 배포를 시작해요!
! git push origin main
환경 변수 목록 확인하기
.env.local에 어떤 값들이 있는지 확인하고 싶거나, 어떤 값을 Vercel에 넣어야 할지 헷갈린다면 클로드에게 물어보세요.
클로드, 지금 프로젝트에서 Vercel 환경 변수로 등록해야 하는 키 목록을 정리해 줘.
내 .env.local 파일을 참고해서, 어떤 항목들을 Vercel 대시보드에 복사해 넣어야 하는지 알려줄래?
클로드가 여러분의 프로젝트를 스캔해서 꼭 등록해야 할 키 목록을 친절 하게 리스트업 해줄 거예요.
배포 후 문제가 생겼을 때
배포했는데 화면이 안 뜨거나 이상하게 보인다면, 클로드에게 이렇게 말해 보세요.
Vercel에 배포했는데 화면이 하얗게만 나와.
Vercel 대시보드 빌드 로그에 이런 에러가 있어:
[여기에 에러 메시지를 복사해서 붙여넣기]
어떻게 고치면 돼?
배포는 성공했는데, 로그인 버튼을 누르면 아무 반응이 없어.
로컬에서는 잘 되는데 배포 환경에서만 안 돼.
환경 변수 문제인지 확인해 줄래?
클로드가 에러 원인을 분석하고, 환경 변수 누락인지 코드 문제인지 알려줄 거예요.
Vercel 대시보드에서 빌드 로그 확인하기
배포가 실패하거나, 성공했는데 뭔가 이상할 때 Vercel 대시보드의 빌드 로그를 확인하면 원인을 찾을 수 있어요.
- vercel.com 에 로그인합니다.
- 대시보드에서 내 프로젝트를 클릭합니다.
- Deployments(배포 이력) 탭을 클릭하면, 지금까지의 배포 목록이 시간순으로 나와요.
- 가장 최근 배포를 클릭하면 상세 화면이 열려요.
- Building(빌드) 항목을 클릭하면 빌드 로그(포장 과정 기록)가 한 줄 한 줄 보여요.
빌드 로그에서 빨간색 Error 글씨가 보이면, 그 부분을 복사해서 클로드에게 건네주세요. 15강에서 배운 "복사해서 AI에게 붙여넣기" 방법이 여기서도 그대로 통해요.
배포 후 꼭 확인해야 할 3가지
배포가 성공했다고 끝이 아닙니다. 세상에 공개된 직후에 꼭 점검해야 할 것들이 있어요.
1. 모바일에서 접속해 보기
노트북에서는 예뻤는데, 스마트폰으로 들어가면 버튼이 찌그러지거나 글씨가 화면 밖으로 나가는 경우가 많아요. Vercel이 만들어준 ~.vercel.app 링크를 카카오톡 '나에게 보내기'로 보낸 뒤, 스마트폰으로 꼭 접속해 보세요.
확인할 포인트는 세 가지예요.
- 글씨가 너무 작거나 화면 밖으로 넘치지 않는가
- 버튼을 손가락으로 누를 수 있을 만큼 크기가 적당한가
- 로그인, 데이터 조회 등 주요 기능이 정상 작동하는가
2. 하얀 화면만 뜰 때 (White Screen of Death)
배포 성공이라고 떴는데 링크를 누르니 화면이 새하얗게만 보이나요? 초보자분들이 겪는 배포 후 에러의 90%는 '환경 변수 누락' 입니다.
Vercel 대시보드 상단의 Settings(설정) 탭으로 가서 Environment Variables 메뉴를 확인하세요. 아래 사항을 하나씩 점검해 보세요.
- 철자가 틀린 것은 없는지 (
NEXT_PUBLIC_SUPABASE_URL에서 대소문자, 밑줄 하나라도 틀리면 안 돼요) - 빼먹은 키는 없는지 (
.env.local파일과 하나씩 대조해 보세요) - 값 앞뒤에 공백이 들어간 건 아닌지
수정한 뒤 Save 버튼을 누르고, Deployments 탭에서 가장 최근 배포 옆의 ... 메뉴 > Redeploy(재배포)를 눌러주세요. 환경 변수를 수정해도 자동으로 재배포되지 않으니, 반드시 수동으로 한 번 재배포해야 해요.
3. 나만의 멋진 도메인 연결하기 (커스텀 도메인)
Vercel이 기본으로 주는 주소는 길고 안 예쁩니다. 만약 my-project.com 같은 나만의 도메인(웹 주소)을 샀다면, Vercel에서 쉽게 연결할 수 있어요.
- Vercel 대시보드 > Settings > Domains 메뉴에 갑니다.
- Add Domain 버튼을 누르고 내가 산 도메인 주소를 입력합니다.
- Vercel이 친절하게 DNS(인터넷 전화번호부) 설정을 어떻게 바꿔야 하는지 안내해 줄 겁니다.
- 안내에 따라 도메인 업체(가비아, Cloudflare 등) 사이트에서 DNS 레코드를 수정하면 끝이에요.
커스텀 도메인을 연결하면 HTTPS(보안 자물쇠)도 Vercel이 자동으로 발급해 줘요. 별도 SSL 인증서를 구매하거나 설치할 필요가 전혀 없답니다.
이번 강에서 기억할 것
- Vercel은 훌륭한 택배 기사입니다: 내 GitHub 코드를 자동으로 가져가 인터넷에 띄워줍니다.
- 자동화의 마법: 한 번 Vercel에 연결해 두면, 앞으로는
git push만 해도 알아서 새 버전으로 업데이트됩니다. - 환경 변수는 직접 입력:
.env.local에 있는 비밀번호들은 GitHub에 안 올라가므로, Vercel 대시보드에 직접 입력해야 합니다. - 로컬 빌드 테스트: Vercel에 올리기 전 내 컴퓨터에서
npm run build를 해보면 실패 확률을 크게 줄일 수 있습니다. - HTTPS 자동 적용: Vercel에 배포하면 보안 연결(자물쇠 아이콘)이 자동으로 켜져요. 별도 설정이 필요 없어요.
- 모바일 테스트 필수: URL이 나오면 스마트폰으로 가장 먼저 접속해서 화면이 깨지지 않는지 확인하세요.
이런 분께 추천해요
- "로컬호스트(localhost)를 벗어나고 싶은 분": 내 컴퓨터에서만 보던 서비스를 전 세계 누구에게나 자랑하고 싶은 분
- "서버 관리는 1도 모르는 바이브 코더": Linux 명령어, 포트 포워딩, 방화벽 같은 복잡한 설정 없이 클릭 몇 번으로 끝내고 싶은 분
- "포트폴리오를 제출해야 하는 취준생": 면접관이나 지인에게 당장 클릭해서 볼 수 있는 결과물 링크가 필요하신 분
참고 링크
▸개정 이력1건
- v12026-04-13초판
이 글이 도움이 되었나요?