29강. GitHub Pages로 정적 사이트 배포하기

이번 강의의 결과물은 GitHub 저장소의 기본 브랜치에서 배포되어 공개 URL로 접속할 수 있는 정적 웹 페이지입니다.

?1. 이번 강의에서 해결할 문제

로컬 서버의 localhost 주소는 내 컴퓨터 안에서만 사용할 수 있습니다. 포트폴리오를 다른 사람에게 보여 주려면 HTML, CSS, JavaScript 파일을 인터넷에서 응답하는 호스팅 환경에 배포해야 합니다.

✓학습 목표

• 로컬 서버의 localhost 주소는 내 컴퓨터 안에서만 사용할 수 있습니다. 포트폴리오를 다른 사람에게 보여 주려면 HTML, CSS, JavaScript 파일을 인터넷에서 응답하는 호스팅 환경에 배포해야 합니다.
• 핵심 개념을 코드 예시와 짧은 실습에 적용하고 결과를 설명합니다.

◇2. 핵심 개념

• 배포: 개발한 결과물을 사용자가 접근할 수 있는 환경에 올리는 과정
• 정적 사이트: 서버에서 코드를 실행해 매번 HTML을 만들지 않고 준비된 파일을 전달하는 사이트
• 호스팅: 웹 파일을 저장하고 HTTP로 제공하는 서비스
• 배포 소스: GitHub Pages가 공개 파일을 읽을 브랜치와 폴더
• 프로젝트 사이트: 보통 https://사용자명.github.io/저장소명/ 경로에 배포되는 사이트. 이 교재의 계정 예시는 https://baggu4402.github.io/portfolio-site/

GitHub Pages의 브랜치 배포는 선택한 브랜치의 루트(/) 또는 /docs 폴더를 게시할 수 있습니다. 메뉴와 지원 범위는 바뀔 수 있으므로 실제 설정 전 GitHub Pages 게시 소스 공식 문서를 확인합니다.

이 강의에서는 학습 저장소 전체가 아니라 포트폴리오 파일만 루트에 둔 별도 저장소를 사용합니다. 그러면 복잡한 자동화 없이 main의 루트를 바로 배포할 수 있습니다.

</>3. 코드 예시

로컬 프로젝트 위치 예시: D:\WebProject\portfolio-site

배포할 저장소의 파일 구조:

portfolio-site/
├─ index.html
├─ css/
│  └─ styles.css
├─ data/
│  └─ projects.json
└─ js/
   └─ main.js

프로젝트 사이트에서는 /css/styles.css처럼 /로 시작하는 경로보다 다음과 같은 상대 경로를 사용합니다.

파일명: index.html

<link rel="stylesheet" href="./css/styles.css">
<script type="module" src="./js/main.js"></script>

파일명: js/main.js

const response = await fetch("./data/projects.json");

저장소를 준비하고 GitHub 원격에 올리는 명령 예시:

cd D:\WebProject\portfolio-site
git init
git branch -M main
git add .
git commit -m "feat: publish initial portfolio"
git remote add origin https://github.com/baggu4402/portfolio-site.git
git push -u origin main

GitHub 저장소에서 다음 순서로 설정합니다.

Settings → Pages
Build and deployment → Source → Deploy from a branch
Branch → main / (root) → Save

배포 전 로컬 실행 위치: D:\WebProject\portfolio-site

python -m http.server 5500

→4. 코드가 동작하는 이유

1. push한 커밋에 배포할 정적 파일과 index.html이 포함됩니다.
2. GitHub Pages가 설정한 main 브랜치의 루트를 게시 소스로 읽습니다.
3. Pages 서버가 공개 URL의 요청에 저장소 파일을 응답합니다.
4. ./ 상대 경로는 프로젝트 사이트의 저장소 경로 아래에서 CSS, JavaScript, JSON을 찾습니다.
5. 이후 main에 새 커밋을 push하면 Pages가 변경을 다시 게시합니다.
6. 배포 상태와 실패 원인은 저장소의 Actions 또는 Pages 설정에서 확인할 수 있습니다.

배포는 git push와 같은 뜻이 아닙니다. push는 커밋을 원격 저장소로 전송하고, Pages 게시 과정은 그 커밋의 파일을 웹에서 제공하도록 만듭니다.

!5. 자주 하는 실수

• 저장소 루트에 index.html이 없음
• 파일명의 대소문자가 실제 경로와 다름
• /css/styles.css 같은 루트 절대 경로를 사용해 프로젝트 사이트에서 깨짐
• 로컬에만 있는 파일을 커밋하거나 push하지 않음
• Pages 배포가 끝나기 전에 공개 URL을 반복해서 새로 고침
• 저장소 공개 여부와 계정 요금제에 따른 Pages 지원 조건을 확인하지 않음
• API 키나 비밀번호를 JavaScript에 넣고 배포함

GitHub Pages에 게시된 파일은 방문자가 내려받아 볼 수 있습니다. 비밀 정보는 프론트엔드 저장소에 넣지 않습니다.

✎6. 짧은 실습 과제

1. GitHub에 정적 사이트용 저장소를 하나 준비합니다.
2. index.html, CSS, JavaScript를 저장소 루트 기준으로 배치합니다.
3. 모든 내부 파일 경로가 ./ 상대 경로인지 확인합니다.
4. 로컬 HTTP 서버에서 Network 오류가 없는지 확인합니다.
5. 변경을 커밋하고 main에 push합니다.
6. Pages에서 main / (root)를 게시 소스로 선택합니다.
7. 공개 URL에서 화면, 필터 버튼, JSON 요청을 확인합니다.

완료 기준은 다른 기기에서도 공개 URL을 열 수 있고, 개발자 도구 Network 탭에서 핵심 파일이 모두 성공 상태인 것입니다.

?7. 이해 점검 질문 3개

1. git push와 웹사이트 배포는 어떤 점이 다른가요?
2. 프로젝트 사이트에서 /css/styles.css보다 ./css/styles.css가 안전한 이유는 무엇인가요?
3. GitHub Pages 같은 정적 호스팅에 API 키를 넣으면 안 되는 이유는 무엇인가요?

■핵심 요약

• 이번 강의의 핵심 개념을 코드의 구조와 실행 결과에 연결했습니다.
• 코드 예시를 직접 바꾸는 짧은 실습으로 핵심 동작을 확인했습니다.
• 이해 점검 질문에 답하며 다음 강의에 필요한 기준을 정리했습니다.