Vercel 가입과 첫 배포

1. 첫 페이지 만들어 GitHub에 올리기
2. Vercel 가입
3. 저장소 Import
4. Deploy
5. 내 주소로 열어 보기
6. 고치면 자동으로 새로워짐

1. 아주 간단한 첫 페이지 만들어 GitHub에 올리기

배포할 대상이 있어야 하므로 먼저 아주 작은 사이트를 하나 만듭니다. 파일은 index.html 하나면 충분합니다. 웹 서버는 주소만 입력하면 그 폴더의 index.html을 가장 먼저 보여 주는 약속이 있어서, 파일 이름을 꼭 index.html로 해야 합니다.

3장에서 내려받은 문서 아래의 ai-site 폴더를 Code 탭에서 선택한 상태로 진행합니다. 그다음 아래처럼 말합니다.

ai-site 폴더에 index.html 파일 하나로 첫 사이트를 만들어줘.
- 화면 가운데에 큰 제목 "[내 이름 또는 닉네임]의 첫 사이트"와 한 줄 소개 문장
- 배경색은 [좋아하는 색], 글자는 읽기 편한 크기
- 휴대폰 화면에서도 깨지지 않게 (반응형)
- 버튼 하나를 누르면 인사말 문구가 바뀌는 간단한 동작
만든 다음 내 PC의 브라우저에서 열어 볼 수 있게 열어줘. 내가 확인하고 괜찮다고 하면, GitHub 저장소 ai-site 의 main 브랜치에 올려줘.
회사 자료나 개인정보는 파일에 넣지 마.

Claude가 파일을 만들고, 브라우저로 열어 주고, 내가 "좋아"라고 하면 GitHub로 올립니다. 올리기 전에 내 눈으로 먼저 확인하는 순서입니다.

잘 됐는지 확인하기

• 내 PC에서: 브라우저에 큰 제목, 소개 문장, 버튼이 보이고 버튼을 누르면 문구가 바뀝니다. 브라우저 주소창에는 file:///C:/Users/...처럼 내 PC 경로가 보이는데, 이 주소는 나만 볼 수 있습니다. 아직 인터넷에 올라가지 않은 상태입니다.
• GitHub에서: github.com/[내 사용자 이름]/ai-site를 열어 파일 목록에 index.html이 보이면 성공입니다. 안 보이면 페이지를 새로고침하고, 그래도 없으면 Claude에게 "GitHub에 올라갔는지 확인하고 알려줘"라고 부탁하세요.

2. Vercel 가입하기

1. 가입 페이지 열기

   브라우저 주소창에 vercel.com/signup을 입력하고 Enter를 누릅니다. "Your first deploy is just a sign-up away."라는 제목 아래에 가입 방법을 고르는 버튼이 줄지어 나옵니다. Continue with Google, Continue with GitHub, Continue with ChatGPT, Continue with Apple, Continue with Email 같은 버튼이고, Show other options를 누르면 다른 방법이 더 나옵니다. 이 교재에서는 Continue with GitHub를 누릅니다. 이 첫 화면에서는 플랜을 고르지 않습니다. 화면 문구는 업데이트로 조금 다를 수 있습니다.

   

2. Continue with GitHub 누르기

   Continue with GitHub를 누르면 GitHub 화면으로 이동합니다. 3장에서 GitHub에 이미 로그인해 두었다면 로그인 없이 바로 다음 화면이 나옵니다.

   왜 GitHub로 가입하나요?

   Vercel은 GitHub 저장소를 가져가야 합니다. GitHub 계정으로 가입하면 그 연결이 처음부터 이어져서 저장소 목록을 바로 볼 수 있습니다. 가입에 쓴 GitHub 계정이 Vercel의 기본 로그인 수단이 됩니다. 이메일로 가입하는 것도 가능하지만 나중에 GitHub를 따로 연결해야 합니다.

3. GitHub의 권한 승인 화면에서 Authorize

   GitHub가 "Vercel이 내 계정 정보 일부를 읽도록 허용하겠습니까?"라고 묻는 화면(제목에 Authorize Vercel이 들어갑니다)을 보여 줍니다. Vercel 공식 문서에 따르면 이때 요청하는 것은 내 이메일 주소를 읽는 권한 등 기본 계정 정보입니다. 내용을 읽고 초록색 Authorize 버튼을 누릅니다. 비밀번호나 2단계 인증 코드를 한 번 더 물을 수 있습니다.

   이 승인은 "Vercel로 로그인"하기 위한 것입니다. 내 저장소 파일을 가져가는 권한은 아래 "3. GitHub 저장소를 Vercel로 가져오기" 절차에서 따로 정합니다.

4. 플랜이나 사용 목적을 물으면 Hobby 선택

   가입 과정 중이나 가입 직후에 사용 목적, 이름, 플랜을 묻는 화면이 나올 수 있습니다. 나오지 않으면 이 단계는 건너뛰어도 됩니다. 플랜을 고르는 화면이 나오면 Hobby(개인 프로젝트용, 무료)를 고릅니다. 이름 칸이 있으면 화면에 표시될 이름을 입력하고 Continue를 누릅니다. 화면 문구와 순서는 업데이트로 조금 다를 수 있으니 "Hobby"라는 단어를 찾으면 됩니다. 카드 번호를 요구하는 화면이 나오면 Pro를 고른 것이므로 멈추고 Hobby로 돌아가세요.

5. 가입 완료 화면 확인

   Vercel 화면으로 돌아오면 가입이 끝난 것입니다. 대시보드(관리 화면)나 "처음 프로젝트를 만들어 보세요"라는 안내가 보입니다. 이메일 인증이나 추가 본인 확인(휴대폰 문자 등)을 요구하면 화면 안내에 따라 본인이 직접 진행하세요. 오른쪽 위 둥근 프로필 그림이 보이면 로그인된 상태입니다.

3. GitHub 저장소를 Vercel로 가져오기 (Import)

이제 이 장의 핵심입니다. 눌러야 할 버튼을 순서대로 적었습니다.

1. Add New...
2. Project
3. Import Git Repository
4. Import
5. Deploy

1. 대시보드에서 Add New... > Project 누르기

   vercel.com/dashboard를 엽니다. 화면 오른쪽 위에 Add New... 버튼이 있습니다. 누르면 작은 메뉴가 펼쳐지고 그 안의 Project를 선택합니다. (Vercel 공식 문서는 같은 위치를 "New Project 버튼"이라고 부르기도 합니다. 처음 가입한 직후에는 대시보드에 바로 "Import Git Repository" 영역이 보일 수 있으며, 그 경우 이 단계를 건너뛰어도 됩니다.)

2. Import Git Repository 영역에서 내 GitHub 계정 고르기

   "Import Git Repository"라는 제목 아래에 저장소 목록이 나옵니다. 목록 위 왼쪽에 보이는 드롭다운에서 코드 보관 서비스(GitHub)와 내 계정이 선택되어 있는지 확인합니다. 처음이라면 목록이 비어 있거나 Install(또는 "Add GitHub Account") 같은 버튼이 보입니다. 이것은 Vercel이 내 GitHub 저장소를 볼 수 있도록 "Vercel GitHub App"을 설치해야 한다는 뜻입니다. 다음 단계로 넘어갑니다.

3. 처음이라면: Vercel GitHub App 설치하고 접근 범위 고르기

   Install을 누르면 GitHub 화면이 열리고 "Install Vercel" 같은 제목의 설치 화면이 나옵니다. 설치할 위치로 내 개인 계정을 선택한 뒤, Repository access(저장소 접근 범위)에서 두 가지 중 하나를 고릅니다.

   Only select repositories 권장

   • 내가 고른 저장소만 Vercel이 볼 수 있습니다.
   • "Select repositories" 드롭다운을 눌러 ai-site를 선택합니다.
   • 다른 저장소(앞으로 만들 저장소 포함)는 보이지 않으므로 안전합니다.
   • 새 저장소를 배포할 때마다 그 저장소를 한 번 추가해 줘야 합니다.

   All repositories

   • 내 모든 저장소(앞으로 만들 것 포함)를 Vercel이 볼 수 있습니다.
   • 저장소를 추가할 때마다 설정을 바꿀 필요가 없어 편합니다.
   • 다른 목적의 저장소가 섞여 있다면 필요 이상으로 많은 접근을 허용하게 됩니다.

   접근 범위를 고른 뒤 초록색 Install 버튼을 누릅니다. 비밀번호나 2단계 인증을 한 번 더 요구하면 입력합니다. Vercel이 요구하는 권한은 "저장소 파일을 읽고, 배포 결과를 GitHub에 표시하고, 새 파일이 올라오면 알림을 받는 것" 등입니다.

   나중에 저장소를 더 추가하려면

   GitHub에서 프로필 그림 > Settings > Applications로 들어가 설치된 앱 중 Vercel의 Configure를 누르면 접근할 저장소를 추가하거나 뺄 수 있습니다(Vercel 공식 도움말 안내). Vercel Import 화면에서도 GitHub App 설정(Configure) 링크로 갈 수 있습니다.

4. ai-site 옆의 Import 누르기

   설치가 끝나면 Vercel Import 화면으로 돌아오고, 저장소 목록에 ai-site가 한 줄로 나타납니다. 그 줄 오른쪽 끝에 있는 Import 버튼을 누릅니다. 목록에 없으면 페이지를 새로고침해 보세요. 그래도 없으면 아래 "막혔을 때"를 확인하세요.

5. Configure Project 화면: 건드릴 것과 건드리지 않을 것

   "Configure Project"(프로젝트 설정) 화면이 나옵니다. 우리 사이트는 파일 한 장이라 거의 모든 칸을 기본값 그대로 두면 됩니다.

   항목	어떻게 하나요	이유
   Project Name	자동으로 저장소 이름(ai-site)이 들어 있습니다. 원하면 바꿔도 됩니다.	이 이름이 내 사이트 주소에 들어갑니다. 예: https://ai-site.vercel.app. 같은 이름의 주소를 다른 사람이 이미 쓰고 있으면 Vercel이 조금 다른 주소를 만들어 줍니다. 영문 소문자, 숫자, 하이픈을 쓰고 실명, 회사명 같은 정보는 넣지 않습니다.
   Framework Preset	Other로 두거나, 자동 인식된 값을 그대로 둡니다.	Next.js 같은 도구를 쓰지 않는 순수 HTML 사이트라서 별도 틀이 필요 없습니다.
   Root Directory	./ 그대로 둡니다.	index.html이 저장소 맨 위에 있으므로 시작 위치를 바꿀 필요가 없습니다.
   Build and Output Settings	펼치지 않고 비워 둡니다. (Build Command, Output Directory, Install Command 모두 비움)	HTML 파일을 변환할 필요가 없어서 "만드는 단계(빌드)"가 필요 없습니다.
   Environment Variables	비워 둡니다.	비밀번호나 키 같은 설정값을 넣는 칸인데 이번에는 쓸 일이 없습니다. 이 칸에 값을 넣게 될 때도 Claude 대화창에는 붙여넣지 마세요.

   이미 다른 사람이 같은 프로젝트 이름의 주소를 쓰고 있으면 주소 끝에 짧은 글자가 덧붙을 수 있습니다. 최종 주소는 배포가 끝난 뒤 "대시보드에서 내 사이트 주소 찾아 클릭하기" 단계의 Domains 항목에서 확인합니다.

6. Deploy 버튼 누르기

   화면 아래쪽의 Deploy 버튼을 누릅니다. 잠시 뒤 배포 진행 화면으로 바뀌고, 로그(진행 기록)가 한 줄씩 올라갑니다. 우리 사이트는 파일 한 장이라 보통 1분 안팎이면 끝납니다. 창을 닫지 말고 기다리세요.

7. 축하 화면 확인

   배포가 끝나면 "Congratulations!" 같은 축하 문구와 함께 내 사이트의 작은 미리보기 그림이 나옵니다. 오른쪽(또는 아래)에 Continue to Dashboard 버튼이 있습니다. 이 화면이 보이면 배포가 완료된 것입니다. 공식 문서에 따르면 새 프로젝트의 첫 배포는 항상 Production(실제 주소용)으로 만들어집니다. 화면 문구는 업데이트로 조금 다를 수 있습니다.

8. 대시보드에서 내 사이트 주소 찾아 클릭하기

   Continue to Dashboard를 누르면 방금 만든 프로젝트 화면이 열립니다. 이 화면에서 다음 두 곳을 찾으세요.

   • Production Deployment 영역: 방금 만든 배포가 보이고 상태가 Ready(초록색 표시)로 되어 있으면 정상입니다.
   • Domains 항목: https://[프로젝트이름].vercel.app 모양의 주소가 링크로 적혀 있습니다. 이것이 내 사이트 주소입니다. 이 링크를 누릅니다.

   화면 배치와 문구는 업데이트로 조금 다를 수 있습니다. "Ready"나 ".vercel.app으로 끝나는 주소"를 찾으면 됩니다.

9. 내 사이트가 뜨는 것 확인하기

   새 탭이 열리고 이 장 맨 앞에서 만든 첫 페이지가 그대로 보입니다. 주소창에 https://[프로젝트이름].vercel.app이 보이고, 앞에 자물쇠 표시가 있습니다(https는 암호화된 안전한 연결이라는 뜻입니다). 이제 다른 브라우저 탭을 열어 이 주소를 직접 입력해도 같은 화면이 나옵니다. 이것이 "내 사이트 주소를 쳐서 띄운다"는 뜻입니다.

10. 휴대폰으로도 열어 보기

    내 사이트가 정말 인터넷에 올라갔는지 확인하는 가장 확실한 방법입니다. 휴대폰 브라우저 주소창에 같은 주소를 직접 입력하세요. 주소 입력이 번거로우면 PC에서 주소를 복사해 메신저의 "나에게 보내기"로 보내고, 휴대폰에서 누르면 됩니다. 와이파이를 끄고 모바일 데이터로 열어도 열립니다. 그 화면이 보이면 내 사이트가 PC 밖 인터넷에 공개되었다는 증거입니다. 버튼을 눌러 인사말이 바뀌는지, 글자가 화면에 잘 맞는지도 확인해 보세요.

누구나 열 수 있나요? 로그인 화면이 뜰 때

Vercel은 "배포 보호(Deployment Protection)"라는 기능으로 미리보기 주소를 보호합니다. 새 프로젝트에는 Vercel Authentication(Vercel 로그인을 요구하는 보호 방식)이 켜진 채로 시작하는 경우가 많습니다. 보호 범위는 일반적으로 Standard Protection(Production 도메인을 뺀 나머지를 보호)이어서, 아래 표처럼 주소 종류에 따라 열리는 방식이 다릅니다.

다른 사람이 긴 주소를 열면 Vercel 로그인 화면이 나오는 것이 정상입니다. 지금 설정을 확인하려면 프로젝트 화면에서 Settings를 누르고 왼쪽 메뉴의 Deployment Protection으로 들어갑니다. Vercel Authentication 스위치와 보호 범위가 보입니다. 기본값은 시기와 프로젝트에 따라 다를 수 있으므로 이 화면에서 직접 확인하는 것이 가장 정확합니다. 공식 문서 기준으로 비밀번호 보호(Password Protection)는 Hobby 플랜에서 쓸 수 없고 Pro 이상에서 유료로 제공됩니다.

4. 고치면 저절로 새로워지는 것 체험하기 (자동 재배포)

Vercel을 쓰는 가장 큰 이유가 이것입니다. 이번에는 Vercel 화면에서 아무 버튼도 누르지 않습니다. Claude에게 제목을 바꾸고 GitHub에 올려 달라고만 말합니다.

1. Claude에게 제목 바꾸고 올려 달라고 말하기

   ai-site 의 index.html 에서 큰 제목을 "[새 제목]" 으로 바꿔줘.
   바꾼 뒤에 변경 내용을 "제목 변경" 이라는 메시지로 저장(commit)하고, GitHub 의 main 브랜치에 올려줘(push).
   올린 다음 어떤 파일이 바뀌었는지 한 줄로 알려줘.

   Claude가 파일을 고치고 commit, push를 합니다. push가 끝나면 GitHub가 Vercel에게 "새 내용이 올라왔다"고 알려 줍니다.

2. Vercel의 Deployments 탭에서 진행 보기

   Vercel 프로젝트 화면 위쪽 메뉴에서 Deployments 탭을 누릅니다. 목록 맨 위에 방금 올린 내용에 대한 새 줄이 생겨 있습니다. 줄에는 내가 쓴 메시지("제목 변경")와 브랜치 이름 main이 보입니다. 상태가 시간에 따라 이렇게 바뀝니다.

   • Building: 배포를 만드는 중입니다. 보통 몇 초에서 1분 정도 걸립니다.
   • Ready: 완료입니다. 초록색 표시가 나오고 줄에 Production, Current 같은 표시가 붙습니다.

   새로 고침 버튼을 누르지 않아도 화면이 스스로 바뀌는 경우가 많지만, 안 바뀌면 브라우저를 새로고침하세요.

3. 내 사이트 주소 새로고침해서 바뀐 제목 확인하기

   상태가 Ready가 되면, 앞에서 열어 둔 내 사이트 탭으로 가서 F5로 새로고침합니다. 예전 모습이 그대로 보이면 Ctrl+F5(캐시를 무시하고 새로 불러오기)를 누르세요. 새 제목이 보이면 성공입니다. 휴대폰에서도 새로고침하면 같은 새 제목이 나타납니다.

   정리하면 내 PC에서 한 일은 "GitHub에 올리기" 하나뿐인데, 배포 버튼을 누르지 않고도 인터넷의 내 사이트가 바뀌었습니다.

main에 올리면 진짜 사이트, 다른 브랜치에 올리면 미리보기

Vercel은 "어느 브랜치에 올렸느냐"로 실제 사이트에 반영할지 정합니다. 브랜치(branch)는 같은 프로젝트의 별도 작업 줄기라고 생각하면 됩니다. main이 "진짜 줄기"이고, 새 줄기를 만들어 실험할 수 있습니다.

단, 공식 문서에 따르면 프로젝트의 가장 첫 배포는 어느 브랜치에서 했든 항상 Production입니다. 그 이후부터 위 표의 규칙이 적용됩니다. 미리보기 주소는 앞의 "누구나 열 수 있나요" 표처럼 기본적으로 Vercel 로그인을 요구합니다.

ai-site 에서 new-title 이라는 새 브랜치를 만들어줘.
그 브랜치에서 index.html 의 큰 제목을 "[시험용 제목]" 으로 바꾸고 commit 한 뒤, GitHub 에 new-title 브랜치로 올려줘.
main 브랜치에는 합치지 말고, 올린 뒤 브랜치 이름을 알려줘.

주소 이름 바꾸기

내 사이트 주소는 프로젝트 이름에서 만들어집니다. 마음에 안 들면 두 가지 방법으로 바꿀 수 있습니다. 개인 도메인(예: 내이름.com)을 사서 연결하는 방법도 있지만 이번 교육 범위 밖입니다.

방법 1: 프로젝트 이름 바꾸기

1. 프로젝트 화면
2. Settings
3. General
4. Project Name 수정
5. Save

이름은 영문 소문자, 숫자, 점(.), 밑줄(_), 하이픈(-)만 쓸 수 있고 100자까지 가능합니다(하이픈 세 개 연속은 불가). 저장하면 이후 새 배포부터 .vercel.app 주소가 새 이름으로 만들어집니다. 공식 도움말은 예전 .vercel.app 주소가 계속 열린다고 보장하지 않으니, 이미 공유한 주소가 있다면 새 주소로 다시 알려야 한다고 안내합니다. GitHub와의 자동 배포 연결은 이름을 바꿔도 유지됩니다.

방법 2: Domains에서 사용 가능한 .vercel.app 이름 추가하기

1. 프로젝트 화면
2. Settings
3. Domains
4. Add Domain

입력 칸에 원하는이름.vercel.app을 쓰고 추가합니다. 이미 다른 사람이 쓰는 이름이면 사용할 수 없다는 안내가 나오고, 사용 가능하면 추가됩니다. 화면 문구는 업데이트로 조금 다를 수 있습니다.

대안: Vercel CLI로 배포하기 (선택)

GitHub 연결이 계속 막힌다면, 내 PC 폴더를 Vercel에 곧바로 올리는 방법이 있습니다. Vercel CLI(명령어 도구)를 쓰는 방식이며, Claude에게 부탁하면 됩니다. 단, 이 방식은 GitHub와 연결하지 않으므로 파일을 고쳐 GitHub에 올려도 자동으로 새로워지지 않습니다. 고칠 때마다 다시 배포 명령을 실행하거나, 프로젝트 Settings의 Git 항목에서 나중에 저장소를 연결해야 합니다. 이 교육의 기본 방법은 앞에서 한 GitHub 연결입니다.

1. Claude에게 Vercel CLI 설치 부탁하기

   Vercel CLI는 Node.js가 있어야 설치됩니다(Vercel 공식 문서는 Node.js 18 이상을 안내합니다). Node.js가 없다면 Claude가 먼저 알려 줍니다.

   Vercel CLI를 설치해줘.
   먼저 node --version 으로 Node.js가 설치되어 있는지 확인하고, 없으면 설치 방법을 알려줘.
   있다면 npm i -g vercel 로 전역 설치하고, 끝나면 vercel --version 결과를 보여줘.
   로그인(vercel login)은 내가 직접 할 테니 실행하지 마.

2. vercel login은 내가 직접 (PowerShell)

   새 PowerShell 창을 열고 아래 명령을 입력합니다. 로그인은 본인 계정 확인이 필요한 단계라 내가 직접 합니다.

   vercel login

   브라우저가 열리면 Vercel 로그인 화면에서 Continue with GitHub로 로그인하고 화면의 승인 버튼을 누릅니다. 성공하면 PowerShell에 로그인이 되었다는 문구가 나타납니다. 이후 단계가 화면에 안내된 대로 이어지며, 문구는 CLI 버전에 따라 조금 다를 수 있습니다.

3. Claude에게 배포 부탁하기

   vercel login 을 마쳤어. ai-site 폴더에서 Vercel CLI로 배포해줘.
   처음 배포라서 프로젝트 연결 질문이 나올 거야. 프로젝트 이름은 ai-site 로 하고, 기본값으로 진행하되 어떤 질문이 나왔고 무엇으로 답했는지 알려줘.
   먼저 미리보기 배포를 하고, 내가 확인하면 vercel --prod 로 실제 주소(Production)에 배포해줘. 끝나면 주소를 알려줘.

   Claude가 알려 준 주소를 브라우저에 입력해 내 사이트가 열리는지 확인하세요. 로그인 화면이 나오면 위의 "누구나 열 수 있나요" 설명을 참고하세요.

막혔을 때

Vercel 배포가 Error로 끝났어. 아래 빌드 로그를 읽고 원인을 쉬운 말로 설명해줘. 그리고 ai-site 폴더에서 고칠 수 있는 것이면 고쳐서 GitHub 에 다시 올려줘.

[여기에 빌드 로그를 붙여넣기]

이 장 끝 체크리스트

• Claude가 만든 index.html이 GitHub 저장소에 올라가 있습니다
• Hobby 플랜(개인, 비영리, 무료)으로 Vercel에 가입했고 사용 조건을 이해했습니다
• Vercel GitHub App을 설치하고 접근 범위(Only select repositories 권장)를 정했습니다
• Import, Configure Project, Deploy를 거쳐 축하 화면을 봤습니다
• Domains의 https://[프로젝트이름].vercel.app 을 눌러 내 사이트가 뜨는 것을 확인했습니다
• 휴대폰에서도 내 주소를 열어 봤습니다
• Claude에게 제목을 바꿔 올리게 하고, Deployments의 Building에서 Ready까지 보고, 새로고침해서 바뀐 제목을 확인했습니다