4-1. 웹 서비스 배포 (Vercel & GitHub Pages)
내 컴퓨터에서만 작동하던 웹앱을, 클릭 몇 번과 한국어 지시문(프롬프트)만으로 실제 인터넷 주소에 올려 누구나 접속하게 만드는 두 가지 길(Vercel, GitHub Pages)을 끝까지 따라 해봅니다. 오늘 이 페이지를 마치면, 여러분의 결과물은 더 이상 "내 노트북 안에만 있는 것"이 아니라 카카오톡으로 링크 하나만 보내면 모두가 열어보는 진짜 서비스가 됩니다.
1. 배포가 뭔가요? 정적 사이트는 또 뭐죠?
지금까지 여러분은 npx live-server나 python3 -m http.server로 웹앱을 띄워봤습니다. 그런데 그 주소(보통 localhost:8080 같은 것)는 오직 내 컴퓨터에서만 열립니다. 옆자리 동료에게 그 주소를 보내봐야 아무것도 안 보여요. 이걸 해결하는 마지막 단계가 바로 배포입니다.
배포(Deploy)란?
내 컴퓨터에서만 보이던 결과물을 인터넷 주소(URL)로 누구나 볼 수 있게 올리는 것입니다. 배포가 끝나면 https://...로 시작하는 영구 주소가 생기고, 그 링크를 받은 사람은 누구든(휴대폰으로도) 여러분의 웹앱을 열 수 있습니다.
정적 사이트(Static Site)란?
서버에서 복잡한 계산을 하지 않고, 미리 만들어 둔 HTML·CSS·JS 파일을 그대로 보여주기만 하는 사이트입니다. 우리가 1~3장에서 만든 뽀모도로 타이머, 습관 트래커, 카드뉴스 생성기가 모두 정적 사이트예요. 그래서 무료로, 그리고 아주 빠르게 인터넷에 올릴 수 있습니다. 이번 장의 두 도구(Vercel·GitHub Pages)는 바로 이 정적 사이트를 공짜로 호스팅해 주는 서비스입니다.
💡 안심하세요. 정적 사이트 배포는 회원 정보나 결제를 다루는 무거운 백엔드 작업이 아닙니다. "파일 묶음을 인터넷 책장에 꽂아 두는 것"에 가깝습니다. 그래서 비개발자도, 무료로, 1분 안에 할 수 있습니다.
2. git · 커밋 · 푸시 — 딱 이만큼만 알면 됩니다
배포를 이야기하면 꼭 따라 나오는 단어가 git(깃), 커밋, 푸시입니다. 무섭게 들리지만, 오늘 우리에게 필요한 정의는 딱 세 줄입니다. (참고로 git 명령어를 직접 외울 필요는 없습니다. 에이전트에게 시킬 거예요.)
GitHub(깃허브)
내 코드 파일들을 보관하는 인터넷 상의 내 작업 창고입니다. 무료 계정만 있으면 됩니다. 배포 도구들은 보통 이 창고를 들여다보고 사이트를 띄웁니다.
커밋(Commit)
지금까지의 변경 내용을 "저장 지점"으로 한 번 찍어 두는 것입니다. 게임에서 세이브 포인트를 만드는 것과 같아요. 나중에 문제가 생기면 이 지점으로 되돌아올 수 있습니다.
푸시(Push)
내 컴퓨터에 찍어 둔 저장본을 인터넷의 내 깃허브 창고로 올려보내는 것입니다. 푸시를 해야 비로소 다른 사람(과 배포 도구)이 내 코드를 볼 수 있습니다.
그래서 우리가 할 일은?
이 셋을 손으로 칠 필요가 없습니다. 에이전트에게 한국어로 "깃에 올리고 배포까지 해줘"라고 부탁하면, 에이전트가 커밋과 푸시 명령을 알아서 대신 실행해 줍니다.
다만 에이전트가 깃허브 창고에 코드를 올리려면, 그 전에 딱 한 번 끝내야 하는 준비가 있습니다. 바로 (1) 내 컴퓨터에 깃 도구가 깔려 있는지 확인하고, (2) 깃허브에 "이게 내 계정이야"라고 로그인(인증)을 해두는 것입니다. 여기가 비개발자가 가장 많이 멈추는 지점이라, 화면을 보면서 천천히 같이 통과해 봅시다. 이 한 번만 해두면, 다음부터는 영원히 안 해도 됩니다.
0단계 — 준비물 3가지 점검 (터미널에 한 줄씩)
프로젝트 폴더에서 터미널을 열고, 아래 세 줄을 한 줄씩 입력해 보세요. 버전 숫자가 나오면 "이미 깔려 있다"는 뜻이라 그냥 넘어가면 됩니다.
node -v
git --version
gh --version
| 명령어 | 이게 뭔가요 | 안 깔려 있으면 (없을 때만) |
|---|---|---|
node -v |
세 도구 공통 엔진. v20.x.x처럼 나오면 OK. |
nodejs.org에서 LTS 설치 후 터미널 재시작. |
git --version |
버전을 저장·관리하는 도구. git version 2.x.x면 OK. |
맥은 보통 이미 있음. 없으면 xcode-select --install(맥) 또는 git-scm.com(윈도우). |
gh --version |
깃허브 로그인·창고 생성을 도와주는 공식 도구(GitHub CLI). gh version 2.x.x면 OK. |
맥은 brew install gh, 윈도우는 winget install --id GitHub.cli --source winget, 또는 cli.github.com에서 설치. |
💡 "command not found"가 떠도 당황하지 마세요. 그건 "아직 안 깔렸다"는 뜻일 뿐, 고장이 아닙니다. 위 표의 설치 방법을 따른 뒤 터미널을 껐다 켜고 다시 같은 명령을 쳐보세요. 사실 이 설치조차 에이전트에게 "내 컴퓨터에 git이랑 gh(GitHub CLI)가 깔려 있는지 확인하고, 없으면 내 운영체제에 맞는 설치 방법을 한국어로 알려줘"라고 시키면 알아서 점검해 줍니다.
1단계 — 깃허브 계정 만들기 (1분, 무료)
github.com에서 이메일·비밀번호·아이디(이게 나중에 주소에 들어갑니다)만 정하면 무료 계정이 생깁니다. 이미 계정이 있다면 이 단계는 건너뛰세요. 이 아이디가 곧 github.com/내아이디/... 주소의 그 "내아이디"가 됩니다.
2단계 — 깃허브에 "이게 내 계정이야" 로그인하기 (gh auth login)
이제 내 컴퓨터에게 "내 깃허브 계정은 이거야"라고 딱 한 번 알려줄 차례입니다. 터미널에 아래 한 줄을 칩니다.
gh auth login
그러면 터미널 안에서 영어 질문이 위아래 화살표(↑↓)로 고르는 메뉴 형태로 차례차례 나옵니다. 처음 보면 당황스럽지만, 아래대로 고르고 Enter만 누르면 됩니다. (gh 버전에 따라 질문 문구가 조금 다를 수 있어요 — 뜻만 같으면 똑같이 고르면 됩니다.)
"Where do you use GitHub?" → GitHub.com을 골라 Enter. (회사 전용 깃허브가 아니라면 항상 이것)
"What is your preferred protocol…?" → HTTPS를 골라 Enter. (가장 무난하고 추가 설정이 없음)
"Authenticate Git with your GitHub credentials?" → Yes(Y)로 Enter. (깃 명령도 같이 인증해 둠)
"How would you like to authenticate?" → Login with a web browser를 골라 Enter. (가장 쉬운 길)
D를 고르면 터미널에 여덟 자리 코드(예: A1B2-C3D4)가 뜨고 "Press Enter to open github.com…"이라고 나옵니다. 그대로 Enter를 누르면 브라우저가 열립니다.
터미널의 그 여덟 자리 코드를 복사해 둡니다. (터미널에 그대로 떠 있어요)
열린 브라우저 페이지(github.com/login/device)에 그 코드를 붙여넣고 "Continue"를 누릅니다.
"Authorize GitHub CLI" 같은 초록 버튼을 눌러 접근을 허용합니다. (깃허브 비밀번호를 한 번 더 물어볼 수 있어요)
💡 성공하면 이런 화면이 보입니다. 브라우저에 "Congratulations, you're all set!" 비슷한 문구가 뜨고, 터미널로 돌아오면 초록 체크와 함께
✓ Logged in as 내아이디같은 줄이 보입니다. 이게 보이면 인증 끝 — 다시는 안 해도 됩니다. 확인만 더 하고 싶다면gh auth status를 쳐서Logged in to github.com as 내아이디가 나오는지 보면 됩니다.
💡 여기서도 막히면 에이전트에게. 코드 입력 창을 못 찾거나 화살표 메뉴가 헷갈리면, 화면을 캡처해 에이전트에게 "gh auth login을 하는 중인데 지금 이 화면에서 뭘 눌러야 해?"라고 물어보세요. 영어 메뉴를 한국어로 풀어 다음 행동을 짚어 줍니다.
준비가 끝났습니다. 이제 아래 프롬프트 하나면, 에이전트가 깃허브 창고 생성부터 커밋·푸시까지 한 번에 처리해 줍니다. (앞에서 gh auth login을 끝냈으니, 이번엔 별도 로그인 없이 곧장 진행됩니다.)
"이 폴더의 모든 파일을 처음으로 깃(git)으로 관리하고 싶어. 깃 저장소를 초기화하고, 적절한 .gitignore 파일도 만들어줘. 그다음 gh CLI로 내 GitHub에 새 공개 저장소를 만들어서 지금까지 만든 파일 전부를 커밋하고 푸시해줘. 혹시 gh 로그인이 안 되어 있으면 먼저 'gh auth login'을 어떻게 진행해야 하는지 한국어로 단계별로 알려줘. 막히는 부분이 있으면 내가 뭘 클릭하거나 입력해야 하는지 한국어로 짚어줘."
💡 성공하면 이런 화면이 보입니다. 에이전트가 터미널에서 작업을 마치면 "푸시 완료" 같은 메시지와 함께
https://github.com/내계정/저장소이름주소를 알려줍니다. 그 주소를 브라우저에서 열어 내 파일들(특히index.html)이 잘 올라가 있으면 성공입니다. 이제 이 창고를 배포 도구에 연결할 차례입니다.
3. 잠깐 — 내 메인 파일 이름은 index.html인가요?
배포 도구는 주소로 처음 접속한 사람에게 어떤 파일을 첫 화면으로 보여줄지 정해야 합니다. 그 약속된 파일 이름이 바로 소문자 index.html입니다. 1~3장에서 만든 파일이 pomodoro.html, habit.html, cardnews.html처럼 제각각이라면, 배포 후 첫 화면이 비거나 404가 뜰 수 있어요. 배포 전에 이걸 먼저 정리하면 사고를 막을 수 있습니다.
가장 자주 여는 앱을 첫 화면으로
- 예:
habit.html→index.html로 이름 변경 - 앱이 한 개뿐이거나, 대표작 하나만 보여줄 때 가장 간단
- 주소 끝에 파일명 없이
github.io/저장소/만 쳐도 바로 그 앱이 열림
여러 앱을 한 입구에서 고르게
- 새
index.html이 "내 작품 모음" 목차 역할 - 그 안에서 각 앱(
pomodoro.html등)으로 가는 링크 버튼 제공 - 포트폴리오처럼 보여 면접·제안에서 인상이 좋음
둘 다 손으로 할 필요 없습니다. 상황에 맞는 프롬프트 하나면 에이전트가 파일 이름을 바꾸거나, 예쁜 목차 페이지를 새로 만들어 줍니다.
"내 프로젝트 폴더에 HTML 파일이 여러 개 있어(pomodoro.html, habit.html, cardnews.html). 배포했을 때 첫 화면으로 쓸 소문자 index.html이 아직 없어. 이 세 앱으로 들어가는 링크 버튼이 있는 깔끔한 목차용 index.html을 새로 만들어줘. 카드 형태로 각 앱 제목과 한 줄 설명을 넣고, 모바일에서도 안 깨지게 해줘. 그리고 각 링크는 같은 폴더 기준의 상대경로(예: ./habit.html)로 걸어줘."
★ 딱 하나만 기억하세요. 폴더 맨 위(root)에 소문자
index.html이 반드시 하나는 있어야 합니다.Index.html(대문자 I)도,main.html도 안 됩니다. 이 한 가지가 배포 후 "빈 화면·404"의 가장 흔한 원인입니다. 정리했다면 다시 한 번 "index.html 추가한 것 깃에 커밋하고 푸시해줘"라고 시켜 깃허브에 반영하세요.
4. 어디에 배포할까? Vercel vs GitHub Pages
두 방법 모두 무료로 시작할 수 있고 정적 사이트에 잘 맞습니다. 처음이라면 둘 다 해보고 마음에 드는 쪽을 고르세요. 깔끔한 주소와 자동 배포가 좋으면 Vercel, 가입 없이 깃허브만으로 끝내고 싶으면 GitHub Pages입니다.
최첨단 기능 & 깔끔한 URL
cleanUrls옵션으로 주소에서 확장자(.html) 제거 가능- CLI 명령어로 터미널에서 곧바로 즉시 배포
- 깃허브에 푸시(push)할 때마다 실시간 자동 반영 및 미리보기 지원
- 나만의 커스텀 도메인 연결이 쉬움
- 무료(Hobby) 플랜은 개인·비상업용. 돈을 버는 서비스라면 유료 Pro 플랜이 필요
추가 가입 없는 초간단 정적 호스팅
- GitHub 계정만 있으면 설정 탭 클릭 몇 번으로 완료 (무료 계정은 공개(public) 저장소에서만 사용 가능)
- 별도의 배포 툴이나 CLI 설치가 필요 없음
- 오픈소스 프로젝트나 포트폴리오·이력서 페이지에 매우 유용
- 반영까지 약 1분 정도 기다려야 하는 점만 기억
5. 방법 A. Vercel로 배포하기
정적 HTML/CSS/JS 웹사이트를 전 세계에 고속으로 보여주는 무료 배포 플랫폼입니다. 길이 두 갈래입니다. (A) 마우스로 클릭하는 GUI 방식과 (B) 터미널에 명령어를 치는 CLI 방식입니다. 처음엔 A로 감을 잡고, 익숙해지면 B가 훨씬 빠릅니다.
경로 A — GUI로 깃허브 저장소 가져오기 (처음 추천)
Vercel 가입: vercel.com에 접속해 "Continue with GitHub"로 깃허브 계정과 연동해 가입합니다.
저장소 임포트: 대시보드에서 Add New… → Project를 누르고, 앞서 푸시해 둔 내 깃허브 저장소 옆의 Import 버튼을 클릭합니다.
그대로 Deploy: 정적 사이트라 따로 설정할 게 없습니다. 설정 화면이 떠도 손대지 말고 Deploy 버튼만 누르세요.
배포 완료: 30초~1분이면 축하 화면과 함께 https://내프로젝트.vercel.app 주소가 생깁니다. 그 주소를 클릭하면 내 웹앱이 인터넷에 뜬 걸 볼 수 있습니다.
💡 자동 배포의 마법. 한 번 연결해 두면, 앞으로 에이전트에게 "변경사항 깃에 푸시해줘"라고만 해도 Vercel이 그걸 감지해 사이트를 자동으로 새로 배포합니다. 수정 → 푸시 → 자동 반영. 손이 갈 일이 거의 없어집니다.
경로 B — CLI로 터미널에서 바로 배포 (익숙해지면 더 빠름)
깃허브를 거치지 않고, 내 폴더에서 터미널 명령어 몇 줄로 곧장 라이브 배포하는 방법입니다. 프로젝트 폴더 안에서 순서대로 입력하세요.
★ 먼저 "프로젝트 폴더 안에서" 터미널을 여세요 (이걸 빼먹으면 배포가 통째로 어긋납니다).
vercel은 지금 터미널이 가리키는 그 폴더를 그대로 인터넷에 올립니다. 그래서index.html이 있는 내 프로젝트 폴더가 아닌 엉뚱한 위치(예: 홈 폴더)에서vercel을 치면, 텅 빈 폴더가 배포되어 빈 화면이 떠버립니다. 폴더로 들어가는 방법은 두 가지예요.
- 맥: Finder에서 내 프로젝트 폴더를 우클릭 → "폴더에서 새로운 터미널 열기"를 누르면, 그 폴더에 들어간 상태로 터미널이 열립니다.
- 윈도우: 탐색기에서 내 프로젝트 폴더 안의 빈 공간을 우클릭 → "터미널에서 열기"를 누르세요.
- 또는 직접 이동: 어떤 터미널에서든
cd 폴더경로를 입력하면 그 폴더로 들어갑니다(예:cd ~/Desktop/my-app). 제대로 들어왔는지는ls(맥) 또는dir(윈도우)를 쳐서 목록에index.html이 보이는지로 확인하세요.
Vercel 도구 설치: npm i -g vercel — 컴퓨터에 vercel 명령어를 한 번만 설치합니다.
첫 배포 & 연결: 프로젝트 폴더에서 vercel — 처음엔 로그인과 함께 영어 질문이 5~6개 나옵니다. (아래 표대로 거의 다 Enter) 새 프로젝트의 첫 배포는 바로 운영(Production) 주소로 올라갑니다.
수정 후 다시 배포: 두 번째부터 그냥 vercel을 치면 확인용 미리보기(Preview) 주소만 생깁니다. 실제 공개 주소에 반영하려면 vercel --prod를 치세요. 터미널에 뜨는 https://...vercel.app 주소가 최종 결과물입니다.
npm i -g vercel
vercel
vercel --prod
2단계에서 vercel을 처음 치면, 먼저 로그인 안내가 나옵니다. 브라우저가 열리면 Vercel 가입 때 쓴 방법(예: GitHub)으로 로그인하고 승인을 누르면 터미널로 돌아옵니다. 로그인 안내 없이 에러가 나면 vercel login을 먼저 실행한 뒤 다시 vercel을 치세요. 로그인 화면 모양은 vercel 버전마다 조금씩 다릅니다. 그다음부터 아래 영어 질문들이 차례로 나옵니다. 대괄호 안 대문자(Y/n의 Y)가 기본값이고, 그냥 Enter를 누르면 그 기본값이 선택됩니다. (vercel 버전에 따라 문구가 조금 다를 수 있어요 — 뜻만 같으면 똑같이 누르면 됩니다.)
| 터미널에 뜨는 영어 질문 | 무슨 뜻 & 무엇을 누를까 |
|---|---|
Set up and deploy "~/내폴더"? [Y/n] |
"이 폴더를 배포할까?" → 그냥 Enter(=Y). 대문자 Y가 기본값입니다. |
Which scope should contain your project? |
"어느 계정에 둘까?" → 내 이름(개인 계정)이 보이면 그대로 Enter. 보통 선택지가 하나뿐입니다. |
Link to existing project? [y/N] |
"기존 프로젝트에 연결할까?" → 처음이니 Enter(=N, 새로 만듦). 여기선 대문자 N이 기본값이라 그냥 Enter면 됩니다. |
What's your project's name? |
주소에 들어갈 이름. 폴더명이 회색으로 미리 채워져 있으니 마음에 들면 Enter. (소문자·영문·하이픈만) |
In which directory is your code located? ./ |
"코드가 어느 폴더에 있어?" → 지금 폴더가 맞으니 ./ 그대로 Enter. |
Want to modify these settings? [y/N] |
자동 감지된 설정을 바꿀지. 정적 사이트는 손댈 게 없으니 Enter(=N). |
💡 요약: 거의 다 Enter입니다. 헷갈리면 "이름을 정하라"는 질문 빼고는 전부 그냥 Enter만 눌러도 됩니다. 성공하면
✅ Production: https://내프로젝트.vercel.app [복사됨]같은 줄이 출력되고, 그 주소가 바로 전 세계에 공개된 내 웹앱입니다. (새 프로젝트의 첫vercel은 바로 공개 주소로 올라가고, 그다음부터는vercel이 미리보기,vercel --prod가 공개 주소 반영이라는 점만 기억하세요.)
vercel --prod 실행 후 Production 주소가 생성되면 전 세계 배포 완료입니다.주소에서 .html 지우기 — cleanUrls
기본 배포 주소는 .../habit.html처럼 끝에 확장자가 붙습니다. 이걸 .../habit으로 깔끔하게 바꾸고 싶다면, 프로젝트 폴더에 vercel.json 파일을 만들고 한 줄만 넣으면 됩니다. (이것도 에이전트에게 시키는 게 편합니다.)
{
"cleanUrls": true
}
"내 프로젝트 폴더에 vercel.json 파일을 만들어서 cleanUrls 옵션을 true로 설정해줘. 그러면 배포 주소 끝에 붙는 .html 확장자가 사라지게 하고 싶어. 그다음 변경사항을 다시 배포하는 방법도 알려줘."
💡 나만의 도메인(커스텀 도메인).
vercel.app주소 대신내회사.com같은 주소를 쓰고 싶다면, Vercel 프로젝트의 Settings → Domains에서 보유한 도메인을 입력하고 안내된 설정값을 도메인 구입처에 등록하면 됩니다. (도메인 구입 비용은 별도이며, 없어도vercel.app주소만으로 충분히 공유할 수 있습니다.)
6. 방법 B. GitHub Pages로 배포하기
새 도구 설치도, 추가 가입도 없이 내 깃허브 저장소(Repository) 설정만으로 정적 사이트를 띄워주는 기능입니다. 앞서 2번에서 코드를 이미 깃허브에 푸시해 뒀다면 절반은 끝났습니다.
★ 잠깐 — Vercel "경로 B(터미널 즉시 배포)"만 했다면 여기서 막힙니다. 경로 B는 깃허브를 거치지 않고 내 폴더를 곧장 올리는 길이라, 아직 내 코드가 깃허브 창고에 올라가 있지 않습니다. 그런데 GitHub Pages는 "깃허브 창고에 있는 코드"를 띄우는 기능이라, 창고가 비어 있으면 아래 Settings → Pages 단계가 아예 작동하지 않아요. 그러니 먼저 2번 섹션의 프롬프트로 코드를 깃허브에 올려야 합니다. 한 줄로 요약하면 — 에이전트에게 "내 코드를 깃허브에 올려줘(없으면 새 저장소 만들어서 커밋·푸시해줘)"라고 시킨 뒤 이어서 진행하세요.
코드를 GitHub에 Push: 메인 화면 파일은 반드시 소문자 index.html이어야 합니다. (2·3번에서 이미 정리·푸시했다면 통과)
Settings → Pages 이동: 내 깃허브 저장소 상단의 Settings 탭을 누른 뒤, 좌측 메뉴에서 Pages를 선택합니다.
Branch 및 폴더 설정: Build and deployment 섹션의 Source에서 Deploy from a branch를 고릅니다. 그 아래 Branch를 main(또는 master)으로, 폴더는 / (root)로 고른 뒤 Save를 클릭합니다. (무료 계정이면 저장소가 공개(public)여야 Pages 메뉴를 쓸 수 있어요.)
웹사이트 활성화: 약 1분 기다린 뒤 새로고침하면 같은 Pages 화면 맨 위에 https://<내-계정명>.github.io/<저장소명>/ 주소가 생기며 라이브로 작동합니다.
💡 주소가 바로 안 떠도 정상입니다 — 어디를 보면 되나요? Save 직후엔 같은 Pages 화면 맨 위에 회색으로 "Your site is live at … (지금 빌드 중)" 또는 "Your GitHub Pages site is currently being built"가 보일 수 있습니다. 이건 "지금 짓는 중"이라는 뜻이니 1분쯤 뒤 새로고침(F5)하세요. 다 되면 그 자리에 초록색으로 "Your site is live at https://…"와 Visit site 버튼이 나타납니다. 진행 상황을 더 자세히 보고 싶다면, 저장소 상단의 Actions 탭으로 가면 "pages build and deployment" 작업이 돌아가는 게 보이고, 줄 앞이 노란 점(진행 중) → 초록 체크(완료)로 바뀝니다. 초록 체크가 뜨면 Pages 화면을 새로고침하세요.
★ 하위 경로 배포 주의 (가장 흔한 실수): GitHub Pages 주소는
github.io/저장소명/처럼 저장소 이름이 중간에 끼는 하위 경로입니다. 그래서 코드 안에서/styles.css처럼 슬래시(/)로 시작하는 절대경로를 쓰면 파일을 못 찾아 화면이 깨집니다. 반드시styles.css또는./styles.css처럼 슬래시 없는 상대경로를 사용하세요. (Vercel은 루트 도메인이라 이 문제가 거의 없습니다.)
7. 막히면 이렇게 — 배포 트러블슈팅
배포는 거의 항상 "사소한 한 가지" 때문에 막힙니다. 아래 표만 점검하면 90%는 해결됩니다. 그래도 안 되면, 에이전트에게 증상을 그대로 한국어로 설명하세요.
| 증상 | 원인 & 해결 |
|---|---|
| gh auth login에서 코드 창이 안 보인다 / 메뉴가 헷갈린다 | 브라우저 코드 입력 페이지는 github.com/login/device입니다. 안 열렸으면 그 주소를 직접 입력하고, 터미널의 여덟 자리 코드를 붙여넣으세요. 그래도 막히면 gh auth status로 현재 로그인 상태를 확인하고, 화면을 캡처해 에이전트에게 물어보세요. |
| 404 / 빈 화면이 뜬다 | 메인 파일명이 정확히 소문자 index.html인지, 그리고 그 파일이 저장소의 맨 위(root)에 있는지 확인하세요. Index.html이나 main.html이면 안 됩니다. (3번 섹션 참고) |
| 글씨만 나오고 디자인·이미지가 깨진다 | GitHub Pages 하위 경로 문제입니다. 코드 속 경로가 /styles.css(절대경로)로 시작하면 깨집니다. styles.css 또는 ./styles.css(상대경로)로 바꾸세요. 아래 프롬프트로 에이전트에게 한 번에 맡길 수 있습니다. |
| 저장했는데 주소가 안 열린다 | GitHub Pages는 반영까지 약 1분 걸립니다. Settings → Pages 맨 위의 빌드 상태(또는 Actions 탭의 초록 체크)를 확인하고 1분 뒤 새로고침하세요. Vercel은 보통 30초~1분이면 끝납니다. |
| 화면이 옛날 버전 그대로다 | 브라우저가 옛 화면을 기억(캐시)하고 있을 수 있습니다. 강력 새로고침(맥 Cmd+Shift+R / 윈도우 Ctrl+Shift+R)을 해보세요. |
"내 사이트를 GitHub Pages에 배포했더니 글씨만 나오고 CSS 디자인과 이미지가 전부 깨져 보여. 코드 안에서 / 로 시작하는 절대경로들을 전부 상대경로로 바꿔서, github.io/저장소이름/ 같은 하위 경로에서도 깨지지 않게 고쳐줘. 어떤 파일의 어느 줄을 고쳤는지 한국어로 요약해줘."
💡 에러 로그는 그대로 복사해 주세요. 터미널이나 브라우저(F12 → Console)에 빨간 글씨가 떴다면, 그 메시지를 한 글자도 바꾸지 말고 통째로 복사해 에이전트에게 붙여넣으세요. "이런 에러가 떴는데 어떻게 고쳐?"가 가장 강력한 디버깅 프롬프트입니다.
8. 결과물 쇼케이스 & 상호 피드백
여러분이 배포한 Vercel 또는 GitHub Pages 주소를 소통 채널(패들릿/디스코드)에 공유하고 마음껏 자랑해 보세요. 다른 분들의 링크를 휴대폰으로 열어 모바일 화면에서 깨지는 곳, 반응형 레이아웃 오작동, 버튼 오류 등을 서로 모니터링해 주고받으면, 혼자서는 못 찾던 버그가 금방 드러납니다. "이 링크를 처음 보는 사람도 5초 안에 무슨 앱인지 이해되는가?"를 서로 점검해 주는 것도 큰 도움이 됩니다.
★ 미션 4-1 가이드: 1~3장에서 만든 웹앱 중 하나를 골라 실제 인터넷 주소로 배포하고, 그 링크를 미션 채널에 올리세요. 가능하다면 휴대폰에서도 열리는지 확인한 스크린샷을 함께 첨부하면 좋습니다. "내 노트북 밖으로 처음 나간 내 작품" — 이 한 번의 경험이 수료의 핵심 관문입니다.
배포 전에 딱 한 번 gh auth login으로 깃허브에 로그인(브라우저에서 여덟 자리 코드 입력)하고, 폴더 맨 위에 소문자 index.html을 두는 것 — 이 두 가지만 통과하면 나머지는 쉽습니다. git 명령어는 외울 필요 없이 에이전트에게 "깃에 올리고 배포까지 해줘"라고 맡기고, 경로는 상대경로로 쓰세요. 깔끔한 주소·자동 배포가 좋으면 Vercel, 가입 없이 끝내려면 GitHub Pages — 막히면 화면이나 에러 메시지를 그대로 복사해 에이전트에게 물어보세요.