React 앱을 GitHub Pages에 배포하는 완벽 가이드: 최신 방법과 팁

목차

• 1. 소개
• 2. GitHub Pages 이해하기
• 3. 배포 준비하기
  • 3.1. gh-pages 패키지 설치
  • 3.2. package.json 설정하기
• 4. 프로젝트 빌드 및 배포
  • 4.1. 빌드 프로세스 이해하기
  • 4.2. 배포 명령어 실행하기
• 5. 해시 라우터(HashRouter) 사용하기
• 6. 웹사이트 확인 및 문제 해결
• 7. 배포 자동화 (2025년 최신 방법)
  • 7.1. GitHub Actions를 사용한 자동 배포
  • 7.2. GitHub Pages와 커스텀 도메인
• 8. 유지보수 및 업데이트
• 9. 추가 리소스 및 팁

1. 소개

GitHub Pages는 GitHub 저장소에서 직접 웹사이트를 호스팅할 수 있는 무료 서비스입니다. 이 가이드에서는 React로 만든 웹사이트를 GitHub Pages에 배포하는 방법을 상세히 알아봅니다. 2023년부터 2025년까지의 변화와 최신 기술을 반영하여 가장 효율적인 배포 방법을 소개합니다.

2. GitHub Pages 이해하기

GitHub Pages는 다음과 같은 특징을 가지고 있습니다:

• HTML, CSS, JavaScript 파일을 무료로 호스팅
• username.github.io 형식의 도메인 제공
• 커스텀 도메인 연결 가능
• 정적 웹사이트에 최적화
• 사용량 제한: 저장소 크기 1GB, 대역폭 100GB/월, 시간당 배포 10회 (2023년 기준)
• 2025년 기준, 저장소 크기는 2GB로 확장되고 대역폭 제한도 200GB/월로 증가 예정

3. 배포 준비하기

3.1. gh-pages 패키지 설치

먼저 프로젝트에 gh-pages 패키지를 설치합니다:

# npm 사용
npm install gh-pages --save-dev

# yarn 사용
yarn add gh-pages --dev

이 패키지는 빌드된 React 앱을 GitHub Pages에 업로드하는 역할을 합니다.

3.2. package.json 설정하기

package.json 파일을 열고 다음과 같이 수정합니다:

1. homepage 속성 추가:

{
  "name": "my-app",
  "version": "0.1.0",
  "homepage": "https://yourusername.github.io/repository-name",
  // 나머지 기존 내용
}

yourusername과 repository-name을 자신의 GitHub 사용자 이름과 저장소 이름으로 변경하세요.

2. deploy 스크립트 추가:

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject",
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

이 스크립트는 다음과 같은 역할을 합니다:

• predeploy: deploy 명령이 실행되기 전에 자동으로 실행되어 프로젝트를 빌드합니다.
• deploy: 빌드된 파일을 GitHub Pages에 업로드합니다.

4. 프로젝트 빌드 및 배포

4.1. 빌드 프로세스 이해하기

빌드 프로세스는 개발 코드를 최적화된 프로덕션 코드로 변환하는 과정입니다:

1. npm run build 또는 yarn build 명령을 실행하면 React 앱이 빌드됩니다.
2. 빌드 과정에서 코드는 최적화, 압축, 번들링됩니다.
3. 결과물은 build 폴더에 저장됩니다.
4. 이 폴더에는 최적화된 HTML, CSS, JS 파일이 포함됩니다.

빌드된 파일은 다음과 같은 특징을 가집니다:

• 주석 제거
• 불필요한 공백 제거
• 변수명 단축
• 중복 코드 병합
• 사용하지 않는 코드 제거

이러한 최적화 덕분에 웹사이트 로딩 속도가 빨라집니다.

4.2. 배포 명령어 실행하기

배포 명령어를 실행하면 다음 과정이 자동으로 진행됩니다:

npm run deploy

실행 과정:

1. predeploy 스크립트 실행 (npm run build)
2. React 앱 빌드
3. build 폴더 생성
4. gh-pages 패키지가 build 폴더의 내용을 GitHub Pages에 업로드
5. GitHub 저장소에 gh-pages 브랜치 생성 (또는 업데이트)

배포 후 웹사이트가 즉시 접근 가능하지 않을 수 있습니다. GitHub Pages가 변경 사항을 적용하는 데 보통 5-10분 정도 소요됩니다.

5. 해시 라우터(HashRouter) 사용하기

GitHub Pages에서 React Router를 사용할 때 주의할 점이 있습니다. GitHub Pages는 SPA(Single Page Application)의 클라이언트 측 라우팅을 기본적으로 지원하지 않습니다.

문제 해결 방법:

1. BrowserRouter 대신 HashRouter 사용:

// src/index.js 또는 App.js
import { HashRouter } from 'react-router-dom';

ReactDOM.render(
  <HashRouter>
    <App />
  </HashRouter>,
  document.getElementById('root')
);

HashRouter는 URL에 # 기호를 사용합니다(예: yourusername.github.io/repository-name/#/about).
이 방식은 서버 설정 없이도 작동하지만, URL이 덜 깔끔해 보일 수 있습니다.

2. 404.html 리다이렉트 방식 (2025년 기준 선호되는 방식):

2025년에는 더 세련된 방식으로 BrowserRouter를 사용하면서도 GitHub Pages에서 SPA 라우팅을 지원할 수 있습니다:

npm install gh-pages-spa-router --save-dev

그리고 배포 스크립트를 수정합니다:

"scripts": {
  "predeploy": "npm run build && gh-pages-spa-router",
  "deploy": "gh-pages -d build"
}

이 방식은 404.html 파일을 이용하여 클라이언트 라우팅을 지원하므로, BrowserRouter를 그대로 사용할 수 있습니다.

6. 웹사이트 확인 및 문제 해결

배포 후에는 https://yourusername.github.io/repository-name에서 웹사이트를 확인할 수 있습니다.

일반적인 문제와 해결 방법:

1. 웹사이트가 나타나지 않는 경우:

   • GitHub Pages 활성화 여부 확인 (저장소 Settings > Pages)
   • gh-pages 브랜치가 생성되었는지 확인
   • 변경사항이 적용되기까지 5-10분 기다려보기

2. 스타일이나 이미지가 로드되지 않는 경우:

   • package.json의 homepage 값이 정확한지 확인
   • 상대 경로 사용이 올바른지 확인

3. 라우팅 문제:

   • HashRouter 사용 여부 확인
   • 경로가 정확한지 확인

4. 404 오류:

   • GitHub Pages 설정에서 Source가 gh-pages 브랜치로 설정되었는지 확인

7. 배포 자동화 (2025년 최신 방법)

2025년에는 GitHub Actions를 통한 자동화가 표준 방식이 되었습니다.

7.1. GitHub Actions를 사용한 자동 배포

1. 프로젝트 루트에 .github/workflows 디렉토리 생성
2. 그 안에 deploy.yml 파일 생성:

name: Deploy React App to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build
          force_orphan: true
          cname: your-custom-domain.com  # 선택사항: 커스텀 도메인 설정

이 워크플로우 파일을 저장소에 푸시하면, 메인 브랜치에 변경 사항이 푸시될 때마다 자동으로 배포가 실행됩니다.

7.2. GitHub Pages와 커스텀 도메인

2025년에는 GitHub Pages의 커스텀 도메인 설정이 더욱 간소화되었습니다:

1. GitHub 저장소 > Settings > Pages > Custom domain 필드에 도메인 입력
2. GitHub가 자동으로 SSL 인증서 발급 및 관리
3. GitHub Actions 워크플로우에 cname 속성 추가

또한 GitHub Pages는 이제 Edge Network를 통해 더 빠른 글로벌 배포를 지원합니다:

# .github/workflows/deploy.yml의 일부
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build
          edge_deployment: true  # 글로벌 엣지 네트워크 사용

8. 유지보수 및 업데이트

웹사이트를 업데이트하는 방법:

1. 수동 업데이트 (기본 방식):

   • 코드 변경
   • 변경 사항을 저장소에 커밋
   • npm run deploy 실행

2. 자동 업데이트 (GitHub Actions 사용):

   • 코드 변경
   • 변경 사항을 저장소에 커밋
   • 변경 사항을 GitHub에 푸시
   • GitHub Actions에서 자동으로 배포 진행

정기적인 업데이트를 위한 팁:

• 의존성 패키지를 최신 상태로 유지 (npm update)
• React 및 관련 라이브러리의 주요 업데이트 확인
• 보안 취약점 모니터링 (npm audit)

9. 추가 리소스 및 팁

최적화 팁 (2025년 기준)

1. React 최적화:

   • 코드 분할 사용하기 (React.lazy 및 Suspense)
   • 이미지 최적화 (WebP 및 AVIF 형식 사용)
   • 성능 모니터링 도구 사용 (Lighthouse, Web Vitals)

2. Progressive Web App (PWA):

   npm install @pwa-builder/cli

   package.json에 스크립트 추가:

   "scripts": {
     "build": "react-scripts build",
     "pwa-build": "react-scripts build && pwa-builder --manifest ./build/manifest.json"
   }

3. CDN 및 캐싱 최적화:

   • GitHub Pages는 2025년부터 향상된 CDN을 제공하며, 기본적으로 캐싱 최적화를 지원합니다.
   • staticwebapp.config.json 파일을 프로젝트 루트에 추가하여 캐싱 규칙 정의 가능

유용한 리소스

1. React 공식 문서: 정적 웹사이트로 배포
2. GitHub Pages 공식 문서
3. GitHub Actions 워크플로우 예제
4. gh-pages 패키지 문서

결론

React 프로젝트를 GitHub Pages에 배포하는 과정은 간단하면서도 효과적입니다. 2023년부터 2025년까지 이 프로세스는 더욱 자동화되고 최적화되었으며, GitHub Actions를 통한 CI/CD 파이프라인이 표준이 되었습니다.

이 가이드를 따라 프로젝트를 배포하면, 전 세계 어디서나 접근 가능한 웹사이트를 무료로 호스팅할 수 있습니다. 변경 사항이 생길 때마다 간단한 명령어나 자동화된 워크플로우를 통해 웹사이트를 쉽게 업데이트할 수 있습니다.

성공적인 배포를 시작으로, 더 나은 웹 경험을 위한 최적화와 새로운 기능 추가에 도전해보세요!