배포하기
지금까지 만든 Three.js 페이지는 내 컴퓨터에서만 볼 수 있습니다. localhost:5173 같은 주소는 내 컴퓨터 안에서만 동작하는 주소이기 때문입니다.
배포(Deploy) 는 내 컴퓨터에 있는 코드를 인터넷상의 서버에 올려, 누구나 URL로 접속할 수 있게 만드는 과정입니다. 우리가 만든 Three.js 페이지는 HTML, CSS, JavaScript 파일로만 이루어진 정적 사이트이기 때문에, 별도의 서버 프로그램 없이 파일만 올려두면 됩니다. 이런 정적 사이트를 무료로 호스팅해 주는 대표적인 서비스가 GitHub Pages입니다.
배포 과정에서 막히면 에러 메시지를 그대로 Claude Code에게 보여주세요. "GitHub Pages에 배포했는데 화면이 하얗게 나와"처럼 상황을 설명하면 대부분의 문제를 함께 해결할 수 있습니다.
1. 내 프로젝트는 어떤 방식인가요?
우리는 강의에서 Three.js 프로젝트를 두 가지 방식으로 만들었습니다. 어떤 방식으로 만들었는지에 따라 배포 방법이 달라지기 때문에, 먼저 내 프로젝트를 확인해야 합니다.
| CDN 방식 | npx 방식 (Vite) | |
|---|---|---|
| 만든 방법 | HTML 파일 하나에 <script> 태그로 Three.js를 불러옴 | AI에게 요청해 npm create vite@latest로 프로젝트 생성 |
| 실행 방법 | HTML 파일을 브라우저로 열기 (또는 Live Server) | npm run dev |
| 프로젝트 구조 | index.html 중심의 단순한 구조 | package.json, node_modules 폴더가 있음 |
| 배포 전 준비 | 없음. 파일 그대로 올리면 됨 | 빌드 필요 (npm run build) |
| 배포 방법 | Deploy from a branch | GitHub Actions (CI/CD) |
구분이 헷갈린다면 프로젝트 폴더에 package.json 파일이 있는지 확인하세요. 있다면 npx 방식입니다. Claude Code에게 "이 프로젝트는 CDN 방식이야, npm 방식이야? GitHub Pages에는 어떻게 배포해야 해?"라고 물어봐도 됩니다.
npx 방식은 파일을 그대로 올려도 배포가 되지 않는 이유는 npm install로 설치한 Three.js가 node_modules 폴더 안에 있는데, 이 폴더는 GitHub에 올리지 않기 때문입니다(.gitignore에 등록되어 있죠). 그래서 빌드라는 과정을 거쳐, 내 코드와 Three.js를 하나로 합친 배포용 파일(dist 폴더)을 만들어야 합니다.
2. 배포 전 준비하기
GitHub Pages로 배포하려면 먼저 코드가 GitHub 저장소에 올라가 있어야 합니다.
# 아직 저장소를 만들지 않았다면
git init
git add .
git commit -m "feat: Three.js 상품 소개 페이지 완성"
# GitHub에서 새 저장소를 만든 뒤 연결
git remote add origin https://github.com/<username>/<repository-name>.git
git push -u origin main
이 과정도 Claude Code에게 "이 프로젝트를 GitHub에 올리고 싶어"라고 요청하면 명령어를 안내받을 수 있습니다.
- 저장소의 Settings 탭으로 이동합니다.
- 좌측 메뉴에서 Pages를 선택합니다.
- Source를
Deploy from a branch로 설정합니다. - Branch를
main(또는master), 폴더를/ (root)로 선택합니다. - Save 버튼을 클릭합니다.
몇 분 후 https://<username>.github.io/<repository-name>/ 주소로 접속할 수 있습니다.
3. CI/CD 설정하기
npx(Vite) 방식으로 만든 상품 소개 페이지는 "빌드 → 배포"를 거쳐야 하는데, 수정할 때마다 이걸 손으로 반복하면 귀찮습니다. 그래서 CI/CD를 설정합니다. 코드를 GitHub에 올리기만 하면(push) 빌드와 배포가 자동으로 이어지는 장치입니다. GitHub가 제공하는 자동화 기능인 GitHub Actions를 사용합니다.
설정은 Claude Code에게 맡깁니다.
프롬프트 예시
이 Vite 프로젝트를 GitHub Actions로 GitHub Pages에 자동 배포되게 설정해줘.
- main 브랜치에 push할 때마다 자동으로 빌드하고 배포하게 해줘
- GitHub Pages 경로에서도 페이지가 깨지지 않게 base 경로도 설정해줘
- 내가 GitHub 저장소에서 직접 해야 하는 설정이 있다면 순서대로 알려줘
Claude Code가 하는 일은 크게 두 가지입니다.
.github/workflows/폴더에 배포 자동화 설계도(워크플로우 파일)를 만듭니다. "push가 오면 → 빌드하고 → Pages에 올려라"는 지시서입니다.vite.config파일에 base 경로(/저장소이름/)를 설정합니다. 이게 빠지면 배포 후 화면이 하얗게 나옵니다.
그리고 여러분이 할 일은 하나입니다. 저장소 Settings → Pages에서 Source를 GitHub Actions로 선택하세요. (CDN 방식에서 썼던 Deploy from a branch가 아닙니다!)
이제 확인해 봅시다.
> 지금까지 작업한 내용 커밋하고 push해줘
저장소의 Actions 탭을 열면 노란 점(진행 중) → 초록 체크(완료)로 바뀌는 과정이 보입니다. 완료되면 https://<username>.github.io/<repository-name>/ 주소로 접속! 이제부터는 수정 후 "커밋하고 push해줘" 한마디면 자동으로 새 버전이 배포됩니다.
| 증상 | 해결 |
|---|---|
| 배포된 페이지가 하얗게 나옴 | "base 경로 문제 같아. vite.config 확인해줘"라고 요청 |
| 3D 모델만 안 보임 | "배포 환경에서 GLB 파일 경로가 맞는지 확인해줘"라고 요청 |
| Actions에 빨간 X가 뜸 | 실패 로그를 복사해 Claude Code에게 그대로 붙여넣기 |
공개 전 체크리스트
배포된 페이지는 전 세계 누구나 볼 수 있습니다. 자기소개 페이지의 이메일·전화번호 등 공개하기 부담스러운 정보는 빼거나 버튼 뒤로 숨기세요. 무료 모델을 썼다면 라이선스 조건(CC-BY 등)에 따라 출처를 페이지 하단에 표기하세요.
4. 도전: 자기소개 페이지도 배포하기
상품 페이지는 npx 방식으로 배포했으니, 이번엔 CDN 방식인 자기소개 페이지를 Deploy from a branch 방식으로 직접 배포해 보세요. 위의 "배포 전 준비하기" 순서 그대로입니다. 두 방식을 모두 경험하면 어떤 프로젝트를 만나도 배포할 수 있습니다.
완료했다면 여러분은 지금 인터넷에 공개된 페이지 2개를 가진 사람입니다. URL을 프로필에 걸거나, QR코드로 만들어 공유해 보세요.
5. Part 2를 마치며
- 배포 = 내 코드를 인터넷에 올려 URL로 공개하는 것
- CDN 방식은 파일 그대로(Deploy from a branch), npx 방식은 빌드가 필요하니 GitHub Actions(CI/CD) 로
- 배포 후 수정은 "커밋하고 push해줘" 한마디로 자동 반영
Part 3에서는 지금까지 배운 모든 것을 합쳐 게임을 만듭니다. 캐릭터도, 음악도, 게임 규칙도 전부 AI와 함께 만듭니다.