GitHub와 Vercel로 인터넷에 공개하기

내 컴퓨터 안의 사이트를 인터넷으로 보내기

지금까지 만든 Next.js 사이트는 주로 http://localhost:3000에서 확인했습니다. 이 주소는 내 컴퓨터 안에서만 열리는 작업용 주소입니다. 카페 안에서만 볼 수 있는 임시 메뉴판 같은 것입니다.

이제 이 사이트를 실제 인터넷 주소로 공개해 보겠습니다. 이번 장에서 사용할 도구는 두 가지입니다.

• GitHub: 프로젝트 보관함

• Vercel: 자동 게시 도구

GitHub는 파일을 온라인에 보관하고 변경 기록을 남기는 서비스입니다. 사진첩에 날짜별로 사진을 정리해 두는 것처럼, 프로젝트가 언제 어떻게 바뀌었는지 기록합니다.

Vercel은 GitHub에 올라온 Next.js 프로젝트를 읽어서 인터넷에 공개해 주는 서비스입니다. Next.js를 잘 알아보는 게시 담당자라고 생각하면 됩니다. Vercel은 Next.js 프로젝트를 배포할 때 별도의 복잡한 설정 없이 시작할 수 있도록 지원합니다.¹

여기서 배포는 사이트를 인터넷에 공개하는 일을 뜻합니다. 내 컴퓨터 안에서만 보이던 화면을 다른 사람도 주소로 접속할 수 있게 만드는 과정입니다.

AI 생성 이미지

전체 흐름 먼저 보기

오늘 할 일은 다음 순서입니다.

1. 내 Next.js 프로젝트가 정상 실행되는지 확인한다.

2. GitHub에 프로젝트 저장소를 만든다.

3. 내 컴퓨터의 프로젝트 파일을 GitHub에 올린다.

4. Vercel에서 GitHub 저장소를 연결한다.

5. Vercel이 만들어 준 실제 주소로 사이트를 확인한다.

6. 이후 수정할 때는 GitHub에 다시 올리면 Vercel이 자동으로 새 버전을 배포한다.

처음에는 단계가 많아 보이지만 핵심은 단순합니다.

수정 → 저장 → GitHub에 올리기 → Vercel이 자동 배포

이 흐름만 기억하면 됩니다.

배포 전 확인할 것

먼저 프로젝트 폴더를 VS Code로 열고 터미널에서 개발 서버를 실행합니다.

npm run dev

브라우저에서 http://localhost:3000을 열었을 때 화면이 정상적으로 보여야 합니다. 로컬에서 에러가 나는 프로젝트는 Vercel에서도 대부분 실패합니다.

가능하다면 배포 전에 한 번 더 다음 명령어도 실행해 보세요.

npm run build

npm run dev는 작업 중 화면을 확인하는 명령어이고, npm run build는 실제로 배포할 수 있는 상태인지 점검하는 명령어에 가깝습니다. Vercel도 배포 과정에서 이와 비슷한 빌드 단계를 거칩니다. 그래서 localhost에서는 얼핏 보였던 문제가 npm run build에서 먼저 발견되기도 합니다.

배포 전에는 다음을 확인하세요.

• 브라우저에 빨간 에러 화면이 없는가?

• 터미널에 큰 에러 메시지가 없는가?

• app/page.tsx, app/layout.tsx, components 폴더의 파일명이 맞는가?

• 이미지를 public 폴더에 넣었는가?

• 비밀번호, API 키 같은 민감한 값을 코드에 직접 적지 않았는가?

특히 마지막 항목이 중요합니다. GitHub에 올린 코드는 저장소 공개 범위에 따라 다른 사람이 볼 수도 있습니다. 비밀번호, 관리자 키, 결제 관련 키는 코드에 직접 넣지 않는 습관을 들이세요.

GitHub는 프로젝트 보관함이다

GitHub를 이해하려면 먼저 저장소(repository)라는 말을 알아야 합니다. 저장소는 프로젝트 하나를 담는 온라인 폴더입니다.

예를 들어 이 책에서 만든 프로젝트 이름이 my-next-site라면, GitHub에도 my-next-site라는 저장소를 만들 수 있습니다.

GitHub와 관련해 자주 만나는 말은 세 가지입니다.

• commit: 현재 변경 내용을 하나의 저장 지점으로 남기는 일

• push: 내 컴퓨터의 commit을 GitHub로 올리는 일

• repository: 프로젝트를 보관하는 저장소

commit은 "여기까지 작업 완료"라고 표시하는 것에 가깝습니다. push는 그 완료 표시를 인터넷 보관함인 GitHub에 올리는 일입니다.

비개발자라면 처음부터 Git 명령어를 외울 필요는 없습니다. GitHub Desktop이나 VS Code의 버튼을 활용하는 편이 훨씬 쉽습니다.

가장 쉬운 방법: GitHub Desktop 사용하기

GitHub Desktop은 GitHub에서 제공하는 데스크톱 앱입니다. 명령어 대신 버튼으로 commit과 push를 할 수 있습니다.

진행 순서는 다음과 같습니다.

1. GitHub 계정을 만든다.

2. GitHub Desktop을 설치하고 로그인한다.

3. File → Add local repository를 선택한다.

4. 내 Next.js 프로젝트 폴더를 선택한다.

5. 변경된 파일 목록을 확인한다.

6. 아래쪽 입력칸에 작업 내용을 짧게 적는다.

7. Commit to main 버튼을 누른다.

8. Publish repository 또는 Push origin 버튼을 누른다.

여기서 한 가지 상황을 알아 두면 좋습니다. 프로젝트 폴더를 선택했을 때 "이 폴더는 Git 저장소가 아니다"라는 안내가 나올 수 있습니다. 이때는 GitHub Desktop에서 저장소를 새로 만들겠다는 선택지, 예를 들어 create a repository 같은 버튼을 눌러 현재 폴더를 Git 저장소로 만들면 됩니다. 이미 Git 저장소로 만들어진 프로젝트라면 바로 변경 파일 목록이 보입니다.

작업 내용을 적는 칸에는 거창한 문장을 쓰지 않아도 됩니다.

• 첫 배포 준비

• 홈페이지 문구 수정

• 문의 페이지 추가

• 로고 이미지 변경

이 정도면 충분합니다.

처음 GitHub에 올릴 때 Publish repository 버튼이 보일 수 있습니다. 이것은 "이 프로젝트를 GitHub에 처음 올리겠다"는 뜻입니다. 여기서 공개 범위를 고를 수 있습니다.

• Public: 다른 사람도 저장소 코드를 볼 수 있음

• Private: 초대한 사람만 저장소 코드를 볼 수 있음

연습용이거나 실제 사업용 사이트라면 처음에는 Private를 권장합니다. 나중에 필요하면 바꿀 수 있습니다.

VS Code로 올리는 경우

VS Code에도 Git 기능이 들어 있습니다. 왼쪽의 나뭇가지 모양 아이콘이 Source Control입니다.

대략적인 흐름은 GitHub Desktop과 같습니다.

1. 변경된 파일을 확인한다.

2. 메시지를 적는다.

3. Commit을 누른다.

4. Sync 또는 Push를 누른다.

다만 처음 설정에서는 Git 설치, GitHub 로그인, 저장소 연결이 필요할 수 있습니다. 이 단계에서 막힌다면 GitHub Desktop을 사용하는 편이 더 쉽습니다.

이 책의 목표는 Git 전문가가 되는 것이 아닙니다. Next.js 사이트를 안전하게 수정하고 공개하는 흐름을 익히는 것입니다. 그러니 명령어보다 흐름을 먼저 잡으세요.

Vercel은 자동 게시 도구다

GitHub에 프로젝트가 올라갔다면 이제 Vercel로 배포할 차례입니다.

Vercel은 GitHub 저장소를 연결해 두면, 새 변경 사항이 올라올 때마다 자동으로 사이트를 다시 만들어 공개합니다. 특히 Next.js와 잘 맞도록 설계되어 있어 기본 프로젝트라면 복잡한 설정을 많이 하지 않아도 됩니다.¹

진행 순서는 다음과 같습니다.

1. Vercel에 접속한다.

2. GitHub 계정으로 로그인한다.

3. Add New 또는 New Project를 선택한다.

4. GitHub 저장소 목록에서 내 프로젝트를 찾는다.

5. Import를 누른다.

6. Framework Preset이 Next.js로 잡혀 있는지 확인한다.

7. 특별한 설정이 없다면 그대로 Deploy를 누른다.

Vercel은 프로젝트를 가져온 뒤 보통 다음 일을 자동으로 처리합니다.

• GitHub 저장소에서 코드를 가져온다.

• 필요한 패키지를 설치한다.

• Next.js 프로젝트를 운영용으로 빌드한다.

• 인터넷 주소를 발급한다.

배포가 끝나면 프로젝트이름.vercel.app 형태의 주소를 받을 수 있습니다. 이제 이 주소는 내 컴퓨터가 아니라 인터넷에서 열리는 주소입니다. 다른 사람에게 보내서 확인을 부탁할 수 있습니다.

첫 배포가 실패했을 때 확인할 것

배포가 실패하면 Vercel 화면에 빨간 표시와 함께 로그가 나옵니다. 로그는 배포 과정에서 생긴 기록입니다. 식당 주방의 조리 과정 기록처럼, 어디서 멈췄는지 알려 줍니다.

처음에는 다음 순서로 확인하세요.

1. 내 컴퓨터에서 npm run dev가 정상 실행되는가?

2. 가능하다면 내 컴퓨터에서 npm run build도 성공하는가?

3. GitHub에 최신 파일을 push했는가?

4. 파일 이름의 대소문자가 정확한가?

5. 이미지 경로가 /logo.png처럼 public 기준으로 되어 있는가?

6. 코드 안에 닫히지 않은 태그나 따옴표가 없는가?

특히 파일 이름의 대소문자는 배포할 때 자주 문제가 됩니다. 내 컴퓨터에서는 Logo.png와 logo.png를 비슷하게 처리해 넘어가는 경우가 있어도, 배포 환경에서는 둘을 다른 이름으로 보고 실패할 수 있습니다. 이미지 파일 이름과 코드에서 부르는 이름을 정확히 맞추세요.

자주 검색할 만한 키워드는 다음과 같습니다.

• Vercel Next.js build failed

• Next.js module not found Vercel

• Next.js failed to compile Vercel

• Vercel case sensitive file name

Vercel에서 실패해도 당황하지 마세요. 대부분은 로컬에서는 우연히 넘어갔지만 배포 환경에서는 더 엄격하게 발견된 문제입니다. 로그에서 Error, failed, not found, Module not found 같은 단어를 먼저 찾아보면 원인을 좁히는 데 도움이 됩니다.

수정하면 자동으로 새 버전이 올라간다

첫 배포가 끝나면 이후 작업은 훨씬 단순해집니다.

예를 들어 홈페이지 문구를 수정한다고 해 보겠습니다.

1. VS Code에서 app/page.tsx를 수정한다.

2. 저장한다.

3. localhost:3000에서 확인한다.

4. GitHub Desktop에서 변경 내용을 commit한다.

5. push한다.

6. Vercel이 자동으로 새 배포를 시작한다.

7. 잠시 뒤 실제 주소에 새 내용이 반영된다.

즉, 매번 Vercel에 들어가서 파일을 직접 올릴 필요가 없습니다. GitHub에 변경 내용만 올리면 Vercel이 알아서 다시 게시합니다.

이 구조는 협업할 때도 좋습니다. 디자이너가 화면을 확인하고, 기획자가 문구를 검토하고, 개발자가 수정한 뒤 같은 주소에서 결과를 볼 수 있습니다.

운영 단계에서 만나는 용어들

배포를 한 번 해 보면 새로운 용어가 보이기 시작합니다. 지금 모두 깊게 알 필요는 없습니다. 의미만 가볍게 잡아 두면 됩니다.

Production

Production은 실제 방문자가 보는 운영 사이트입니다. 가게로 비유하면 손님에게 실제로 열려 있는 매장입니다.

보통 main 브랜치에 올라간 안정적인 버전이 Production으로 배포됩니다.

Preview Deployment

Preview Deployment는 미리보기 배포입니다. 아직 실제 운영 사이트에 반영하기 전, 변경된 화면을 별도 주소로 확인하는 기능입니다. Vercel은 Git 제공자와 연동해 변경 사항이나 Pull Request마다 미리보기 주소를 만들 수 있습니다.¹

이 기능은 협업할 때 유용합니다.

• "이 버튼 색상 괜찮나요?"

• "새 랜딩페이지 문구 확인 부탁드립니다."

• "모바일 화면에서 어색한 곳이 있나요?"

이런 검토를 실제 운영 사이트를 건드리지 않고 진행할 수 있습니다.

Domain

도메인(domain)은 사람이 읽기 쉬운 사이트 주소입니다.

Vercel이 처음 주는 주소는 보통 my-next-site.vercel.app처럼 생겼습니다. 실제 서비스라면 mybrand.com이나 mybrand.co.kr 같은 주소를 연결하고 싶을 수 있습니다.

도메인 연결은 Vercel의 Domains 설정에서 시작합니다. 다만 도메인을 구입한 업체의 DNS 설정을 바꿔야 할 수 있습니다. DNS는 "이 주소로 오면 어느 서버로 보내라"고 알려 주는 인터넷 주소 안내판입니다.

이 부분은 직접 할 수도 있지만, 회사 사이트나 고객이 많은 서비스라면 전문가에게 맡기는 것이 안전합니다.

Environment Variables

환경 변수(environment variables)는 코드에 직접 쓰기 어려운 설정값을 따로 보관하는 공간입니다. 집 열쇠를 현관문에 붙여 두지 않고 주머니에 넣어 두는 것과 비슷합니다.

예를 들어 다음 값들은 코드에 직접 적지 않는 것이 좋습니다.

• 외부 서비스 API 키

• 데이터베이스 주소

• 이메일 발송 서비스 비밀 키

• 결제 서비스 비밀 키

Vercel에는 프로젝트 설정에서 환경 변수를 등록하는 메뉴가 있습니다. 화면에 공개되어도 되는 값과 절대 공개되면 안 되는 값을 구분해야 합니다.

특히 NEXT_PUBLIC_으로 시작하는 값은 브라우저에 노출될 수 있습니다. 이름에 PUBLIC이 들어간다고 해서 무조건 안전한 것이 아니라, "사용자에게 보여도 되는 값"에만 붙여야 합니다.

직접 할 일과 맡기면 좋은 일

비개발자가 직접 해도 좋은 일은 다음과 같습니다.

• GitHub Desktop으로 commit, push하기

• Vercel에서 GitHub 저장소 연결하기

• 첫 배포 주소 확인하기

• 간단한 문구, 이미지, 링크 수정 후 다시 배포하기

• Preview 주소를 팀원이나 고객에게 공유하기

전문가에게 맡기면 좋은 일도 있습니다.

• 결제, 로그인, 개인정보 저장이 포함된 배포

• 복잡한 환경 변수 설정

• 데이터베이스 연결

• 회사 도메인의 DNS 변경

• 배포 실패 원인이 서버 코드나 보안 설정과 관련된 경우

Next.js와 Vercel은 작은 사이트를 빠르게 공개하는 데 매우 편리합니다. 하지만 공개 사이트는 누구나 접근할 수 있습니다. 보안, 개인정보, 결제처럼 위험이 큰 영역은 혼자 해결하려 하지 않는 것이 좋습니다.

이번 장의 핵심

GitHub는 프로젝트를 보관하고 변경 기록을 남기는 곳입니다. Vercel은 그 프로젝트를 읽어 인터넷에 자동으로 공개하는 도구입니다.

처음 한 번만 연결해 두면 이후 흐름은 단순합니다.

VS Code에서 수정 → 로컬에서 확인 → GitHub에 push → Vercel 자동 배포

이제 여러분의 Next.js 사이트는 내 컴퓨터 안에만 있지 않습니다. 실제 주소를 가진 웹사이트가 되었습니다. 다음 단계는 이 흐름을 더 똑똑하게 쓰는 것입니다. AI에게 에러를 물어보고, 수정 방향을 제안받고, 모르는 코드를 함께 읽는 방법을 배워 보겠습니다.

참고

¹Next.js on Vercel