이제 정말 마지막 한 걸음입니다. 지금까지 우리와 함께 만든 '작은 기록 상점'은 내 컴퓨터 안에서만 움직이는 연습작이었습니다. 하지만 배포를 하면 이야기가 달라집니다. 링크 하나로 다른 사람에게 보여줄 수 있고, 휴대폰으로도 열어볼 수 있고, 심지어 "이거 내가 만든 거야"라고 아주 조금은 어깨를 으쓱할 수도 있습니다.
Next.js 프로젝트를 세상에 공개하는 가장 쉬운 방법은 GitHub에 코드를 올리고, Vercel에 연결해서 배포하는 것입니다. Vercel은 Next.js를 만든 팀이 운영하는 플랫폼이라서, 대부분의 Next.js 프로젝트를 별다른 복잡한 설정 없이 배포할 수 있습니다.12
이제 배포가 왜 중요한가요?
배포는 단순히 "인터넷에 파일 올리기"가 아닙니다. 개발자의 시선에서 보면, 배포는 프로젝트가 연습용 코드에서 운영 가능한 서비스로 넘어가는 순간입니다.
로컬에서는 잘 되던 것이 배포 후에는 안 될 수도 있습니다. 환경 변수가 빠졌을 수도 있고, 빌드 과정에서 타입 오류가 날 수도 있고, npm run dev에서는 괜찮았는데 실제 프로덕션에서는 데이터 흐름이 달라질 수도 있습니다. 그래서 배포는 마지막 단계이면서도, 사실은 진짜 테스트의 시작점이기도 합니다.
특히 Next.js 15 기준에서는 fetch 요청과 Route Handler의 GET이 기본적으로 더 이상 자동 캐시되지 않기 때문에, "왜 배포했더니 캐시가 안 먹지?" 같은 일이 생길 수 있습니다. 이 변화는 운영할 때 꼭 알고 있어야 하는 포인트입니다.4
먼저 GitHub에 프로젝트 올리기
Vercel은 GitHub 저장소와 연결해서 배포하는 방식이 가장 편합니다. 한 번 연결해 두면 이후에는 git push만 해도 자동으로 다시 배포됩니다.2
먼저 프로젝트 폴더에서 Git 저장소를 준비합니다.
git init
git add .
git commit -m "first deploy"그다음 GitHub에서 새 저장소를 만들고, 안내된 주소를 연결합니다.
git remote add origin https://github.com/내아이디/my-next-app.git
git branch -M main
git push -u origin main여기서 아주 중요한 점이 하나 있습니다. .env.local 파일은 올리지 않아야 합니다. 이 파일에는 데이터베이스 주소, 비밀 키, 외부 API 키 같은 민감한 값이 들어갈 수 있기 때문입니다. 보통 create-next-app으로 만든 프로젝트는 이미 .gitignore에 이런 파일이 제외되도록 들어 있습니다. 그래도 배포 전에는 한 번 꼭 확인하세요.
Vercel에 프로젝트 연결하기
GitHub에 코드를 올렸다면, 이제 Vercel에 가서 프로젝트를 가져오면 됩니다. Vercel은 GitHub 로그인으로 시작하는 것이 가장 간단합니다.1
배포 흐름은 생각보다 짧습니다.
Vercel에 로그인합니다.
Add New → Project를 누릅니다.
GitHub 저장소 목록에서 방금 올린 프로젝트를 선택합니다.
Import를 누르고 설정을 확인합니다.
Deploy를 누릅니다.
대부분의 경우 Vercel은 이 프로젝트가 Next.js 앱이라는 것을 자동으로 알아차리고, 적절한 빌드 설정도 자동으로 채워줍니다. 공식 학습 문서에서도 프로젝트 이름, 루트 디렉터리, 빌드 명령어, 출력 디렉터리, 개발 명령어는 기본값을 그대로 써도 되는 경우가 많다고 안내합니다.1
쉽게 말하면, Vercel은 "아, 이 친구 Next.js구나. 내가 알아서 준비할게."라고 말해주는 친절한 조수에 가깝습니다.
환경 변수는 Vercel에 따로 넣어야 합니다
초보자가 배포에서 가장 자주 만나는 함정은 바로 이것입니다.
로컬에서 되는데, 배포하면 안 되는 이유 1등은 환경 변수 누락입니다.
내 컴퓨터에서는 .env.local 파일이 있으니 잘 동작합니다. 하지만 Vercel 서버는 내 노트북을 읽지 못합니다. 그러니 Vercel 프로젝트 설정에서 환경 변수를 직접 등록해야 합니다.
예를 들어 이런 값들이 있다면 Vercel에 넣어야 합니다.
DATABASE_URLNEXT_PUBLIC_API_BASE_URLAUTH_SECRET외부 서비스 API 키
여기서 이름 규칙도 다시 기억해 둡시다. NEXT_PUBLIC_로 시작하는 환경 변수는 브라우저 쪽 코드에서도 접근할 수 있는 공개 값입니다. 반대로 접두사 없이 선언한 값은 서버에서만 사용해야 하는 비밀 값입니다. 즉, 비밀번호나 비밀 키는 절대 NEXT_PUBLIC_로 시작하면 안 됩니다.
첫 배포가 끝나면 무엇을 받게 되나요?
배포가 성공하면 Vercel은 주소를 하나 만들어 줍니다. 보통 프로젝트이름.vercel.app 같은 형태입니다. 이 주소로 들어가면 우리가 만든 앱이 실제 인터넷에서 열립니다.1
이 순간이 꽤 뿌듯합니다. 정말입니다. localhost:3000에서만 보이던 화면이 이제 전 세계 어디서든 열리니까요. 작은 기록 상점이 드디어 진짜 가게 간판을 단 셈입니다.
그리고 여기서 끝이 아닙니다. GitHub와 연결된 Vercel 프로젝트는 이후부터 브랜치 푸시와 Pull Request에도 자동으로 반응합니다. 즉, main 브랜치로 푸시하면 운영 배포가 되고, 다른 브랜치나 PR에는 미리보기용 배포 주소가 생성됩니다.2
Preview Deployment는 왜 좋은가요?
Vercel의 아주 큰 장점 중 하나가 바로 Preview Deployment입니다. 브랜치마다 미리보기 링크가 생기기 때문에, 아직 운영에 반영하지 않은 변경사항도 실제 배포 환경처럼 확인할 수 있습니다.2
이 기능이 특히 좋은 이유는 세 가지입니다.
디자이너나 팀원에게 링크만 보내서 바로 확인받을 수 있습니다.
모바일에서도 실제 배포 주소로 테스트할 수 있습니다.
main브랜치를 건드리기 전에 문제를 미리 발견할 수 있습니다.
혼자 개발할 때도 꽤 유용합니다. "이 수정, 괜찮나?" 싶을 때 PR 하나 올리고 미리보기 링크를 열어보면 마음이 편해집니다. 미래의 나와 협업하는 느낌이랄까요.
작은 기록 상점을 배포하는 실전 순서
이번 책의 흐름에 맞춰, 우리가 만든 앱을 배포하는 실제 순서를 한 번 정리해 봅시다.
먼저 로컬에서 마지막 점검을 합니다.
npm run lint
npm run build
npm run startnpm run build는 프로덕션용 빌드를 만들어 보는 단계입니다. 이게 통과하지 않으면 Vercel에서도 거의 비슷하게 실패합니다. npm run start까지 해 보면 개발 서버가 아니라 실제 운영과 비슷한 방식으로 앱이 실행되므로, 더 믿을 만한 점검이 됩니다.
그다음 이상이 없으면 GitHub에 올립니다.
git add .
git commit -m "deploy small-record-shop"
git push origin main이후 Vercel에서 저장소를 Import하고, 환경 변수를 입력하고, 배포 버튼을 누릅니다. 한 번 연결해 두면 다음부터는 main에 푸시할 때마다 자동으로 배포됩니다.2
배포 전에 꼭 확인할 체크리스트
배포는 버튼 한 번이지만, 운영은 버튼 한 번으로 끝나지 않습니다. 그래서 배포 전에 아래 항목을 꼭 확인하는 습관을 들이면 좋습니다.
로컬에서
npm run build가 성공하는지 확인합니다..env.local이 GitHub에 올라가지 않았는지 확인합니다.Vercel에 필요한 환경 변수를 모두 등록했는지 확인합니다.
모바일과 데스크톱에서 주요 페이지 레이아웃이 깨지지 않는지 확인합니다.
링크 이동, 폼 제출, 상세 페이지 진입, 404 페이지 같은 핵심 흐름을 직접 눌러 봅니다.
metadata, 이미지, 폰트 최적화처럼 앞 장에서 다룬 항목이 실제 배포에서도 잘 보이는지 확인합니다.
여기에 Next.js 15 기준으로 추가로 챙기면 좋은 점도 있습니다. fetch가 기본적으로 캐시되지 않으므로, 목록 페이지나 상세 페이지에서 캐싱을 기대했다면 직접 cache 또는 revalidate를 설정해야 합니다. Route Handler의 GET도 기본 캐시가 꺼져 있으니, 운영 성능을 위해 캐시 전략을 다시 점검하세요.4
배포 후에는 무엇을 확인해야 하나요?
배포가 끝났다고 바로 의자에 기대면 안 됩니다. 물론 30초 정도는 괜찮습니다. 하지만 그 뒤에는 꼭 실제 사용자 입장에서 앱을 점검해야 합니다.
가장 먼저 대표 URL에 접속해서 홈 화면이 열리는지 확인합니다. 그다음 기록 목록, 상세 페이지, 새 기록 작성, 수정 또는 삭제 같은 핵심 흐름을 처음부터 끝까지 써 봅니다. 가능하면 휴대폰에서도 한 번 열어 보세요. 내 컴퓨터에서는 예뻤는데 모바일에서는 버튼이 줄 바꿈돼서 찌그러지는 일, 생각보다 자주 일어납니다.
배포 후에는 이런 부분도 함께 보면 좋습니다.
콘솔 에러가 없는지
이미지가 느리거나 깨지지 않는지
새로고침해도 페이지가 잘 열리는지
브라우저 뒤로 가기와 앞으로 가기가 자연스러운지
공유했을 때 제목과 설명이 원하는 대로 보이는지
Vercel에 배포하면 좋은 점
Vercel은 단순히 "올려 주는 곳"이 아닙니다. Next.js와 궁합이 좋아서 배포 뒤에도 여러 장점이 따라옵니다.
공식 문서 기준으로 Vercel은 Next.js 앱을 거의 제로 설정으로 배포할 수 있고, Git 연동을 통해 Preview URL을 만들며, ISR·SSR·이미지 최적화·폰트 최적화 같은 기능을 자연스럽게 활용할 수 있습니다.3
특히 초보자에게 체감이 큰 장점은 이렇습니다.
next/image를 쓰면 이미지 최적화가 자동으로 잘 붙습니다.3App Router의
loading.tsx,Suspense같은 흐름이 배포 환경에서도 잘 살아납니다.3GitHub와 연결하면 브랜치별 미리보기 링크가 생깁니다.2
운영 배포와 이전 배포를 관리하기가 쉽습니다.2
한마디로, Next.js를 배운 사람이 처음 실제 서비스까지 이어 가기에 꽤 좋은 다리입니다.
GitHub Actions는 꼭 써야 하나요?
처음이라면 아니요입니다.
초보자 단계에서는 GitHub 저장소를 Vercel에 직접 연결하는 방식이 가장 쉽고 안정적입니다. 이 방식만으로도 main 푸시 자동 배포, PR 미리보기, 배포 이력 관리까지 충분히 경험할 수 있습니다.2
GitHub Actions는 그다음 단계입니다. 예를 들어 테스트를 통과한 경우에만 배포하고 싶다거나, GitHub Enterprise 환경을 사용한다거나, 빌드 과정을 아주 세밀하게 제어하고 싶은 경우에 고려하면 됩니다. 지금은 "자동 배포가 이렇게 돌아가는구나"를 이해하는 것이 더 중요합니다.
운영을 시작하면 생기는 진짜 고민
배포를 마치고 나면, 공부의 중심이 조금 바뀝니다. 이제는 "어떻게 만들까?"보다 "어떻게 유지할까?"가 더 중요해집니다.
서비스를 운영하다 보면 자연스럽게 이런 질문이 생깁니다.
"왜 어떤 페이지는 빠르고 어떤 페이지는 느릴까?"
"데이터가 바뀌었는데 왜 바로 반영되지 않을까?"
"로그인은 붙이면 구조가 어떻게 달라질까?"
"사용자가 늘어나면 지금 방식으로 괜찮을까?"
이 질문들이 바로 다음 성장 단계의 문입니다. 좋은 소식은, 여러분이 이미 그 문 앞까지 왔다는 점입니다.
다음에 무엇을 공부하면 좋을까요?
이 책으로 Next.js의 기본 흐름과 앱 하나를 끝까지 만드는 경험을 마쳤다면, 이제 다음 단계는 더 선명합니다.
첫째는 인증입니다. 로그인, 회원가입, 권한 구분은 실제 서비스에서 아주 자주 만나는 주제입니다. 사용자별 기록을 보여 주는 앱으로 확장하려면 꼭 필요합니다.
둘째는 데이터베이스입니다. 지금은 간단한 데이터 흐름을 이해하는 데 집중했지만, 실제 서비스로 가려면 PostgreSQL, MySQL, MongoDB 같은 데이터 저장소와 연결하는 경험이 필요합니다.
셋째는 테스트입니다. 기능이 늘어날수록 "이번 수정이 다른 곳을 깨뜨리진 않았나?"를 자동으로 확인하는 힘이 중요해집니다.
넷째는 모니터링과 분석입니다. Vercel은 Analytics와 Web Vitals 추적 기능을 제공하므로, 실제 사용자가 어디서 오래 기다리는지 보는 습관을 들이면 좋습니다.3 다만 Next.js 15에서는 Speed Insights 자동 계측이 제거되었으니, 계속 사용하려면 별도 설정이 필요합니다.4
다섯째는 배포 전략의 확장입니다. 처음에는 Vercel로 충분하지만, 나중에는 Docker, 별도 백엔드, 외부 CDN, 더 정교한 CI/CD로 넘어갈 수도 있습니다. 지금의 배포 경험은 그 출발점이 됩니다.
이 책의 마무리
우리는 처음에 "왜 Next.js인가요?"에서 출발했습니다. 그리고 개발 환경을 준비하고, 프로젝트를 만들고, 폴더 구조를 읽고, 작은 기록 상점을 설계하고, 페이지를 만들고, 이동하고, 동적 라우트를 다루고, 스타일을 입히고, 서버와 클라이언트의 차이를 이해하고, 데이터를 읽고 쓰고, API를 만들고, 캐시와 로딩과 에러를 다루고, SEO와 성능까지 챙겼습니다.
그리고 이제, 마지막으로 세상에 공개했습니다.
이건 단순히 챕터 16을 끝낸 게 아닙니다. 하나의 웹 서비스를 처음부터 끝까지 완주한 것입니다.
처음에는 낯설었던 app 폴더도, page.tsx도, layout.tsx도, fetch도, Server Action도 이제는 전보다 훨씬 덜 무서울 겁니다. 물론 아직 모르는 건 많습니다. 하지만 그건 아주 자연스러운 일입니다. 개발은 "다 알게 되는 과정"이 아니라, 점점 덜 겁먹는 과정에 더 가깝거든요.
작은 기록 상점은 여기서 끝나도, 여러분의 Next.js 활용법은 여기서부터 시작입니다.
참고
1Pages Router: Deploy to Vercel | Next.js
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.