[GitHub Pages] 리액트 사이트 GitHub Pages 배포, 404 에러 해결까지 완벽 가이드

1. 프로젝트 초기 생성 (Terminal)

가장 먼저 Vite를 이용해 리액트 타입스크립트 환경을 구축합니다. Vite는 기존 Webpack보다 빌드 속도가 압도적으로 빨라 최근 표준으로 자리 잡고 있습니다.

💡 터미널 입력:

# 1. 프로젝트 생성 (원하는 프로젝트명을 입력하세요)
npm create vite@latest sjdev-portfolio -- --template react-ts

# 2. 프로젝트 폴더로 이동
cd sjdev-portfolio

# 3. 필요한 기본 의존성 설치
npm install

---

2. GitHub 레포지토리 연결 및 소스 업로드

로컬에서 만든 프로젝트를 GitHub에 먼저 올려야 합니다. GitHub Desktop보다는 터미널을 이용하는 것이 협업과 자동화 측면에서 더 유리합니다.

💡 터미널 입력:

# 1. Git 초기화
git init

# 2. 원격 레포지토리 연결 (본인의 레포 주소로 변경)
git remote add origin https://github.com/c189021/sjdev-portfolio.git

# 3. 현재까지의 작업물 커밋 및 푸시
git add .
git commit -m "feat: initial commit for portfolio"
git push -u origin main

---

3. 배포를 위한 핵심 설정 (Config)

GitHub Pages는 정적 호스팅 서비스이므로, 리액트 앱이 서브 경로에서도 잘 작동하도록 추가 설정이 필요합니다.

① vite.config.ts 수정

Vite는 기본적으로 루트(/) 경로를 참조합니다. 하지만 GitHub Pages 주소는 https://유저명.github.io/레포명/ 형태이므로 base 경로를 레포지토리 이름으로 지정해 주어야 합니다.

TypeScript

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  // 레포지토리 이름이 sjdev-portfolio인 경우 아래와 같이 설정합니다.
  base: '/sjdev-portfolio/',
})

② gh-pages 패키지 설치 및 스크립트 등록

배포 전용 브랜치를 자동으로 관리해 주는 패키지를 설치합니다.

💡 터미널 입력:

npm install gh-pages --save-dev

이후 package.json의 scripts 영역을 다음과 같이 수정합니다.

JSON

"scripts": {
  "dev": "vite",
  "build": "tsc -b && vite build",
  "predeploy": "npm run build", 
  "deploy": "gh-pages -d dist"
},

• predeploy: 배포 전 최신 코드를 빌드(dist 폴더 생성)합니다.
• deploy: 생성된 dist 폴더를 GitHub의 gh-pages 브랜치로 업로드합니다.

---

4. [중요] 빌드 시 발생하는 TypeScript 에러 해결

배포 명령어(npm run deploy)를 실행했을 때, 타입스크립트의 엄격한 검사 때문에 빌드가 실패할 수 있습니다. 제가 겪었던 주요 에러와 해결책은 다음과 같습니다.

① RefObject 타입 임포트 에러

TypeScript 5.0 이상에서는 타입을 임포트할 때 type 키워드를 명시해야 하는 경우가 있습니다.

• 수정 전: import { RefObject } from "react";
• 수정 후: import { type RefObject } from "react";

② Generic Type 할당 문제

RefObject<T | null> 타입을 RefObject<T>에 할당하려고 할 때 발생하는 오류입니다. 인터페이스 정의 시 null을 명시적으로 허용해야 합니다.

---

5. 최종 배포 및 GitHub 설정 (Deployment)

모든 수정이 완료되었다면 다시 배포 명령을 내립니다.

💡 터미널 입력:

npm run deploy

터미널에 **Published**라는 문구가 뜨면 성공입니다!

GitHub Pages 브랜치 설정 (마지막 단계)

이제 GitHub 웹사이트에서 배포 브랜치를 지정해야 합니다.

1. 레포지토리의 Settings > Pages 탭으로 이동합니다.
2. Branch 설정을 main에서 **gh-pages**로 변경하고 Save를 클릭합니다.
3. 1~2분 뒤 사이트가 Live 상태로 변하면 주소로 접속합니다.

---

6. 마치며: 404 에러가 여전하다면?

설정을 다 했는데도 404가 뜬다면 브라우저 캐시 문제일 확률이 높습니다. **Ctrl + F5**를 눌러 강력 새로고침을 시도해 보세요.

소프트웨어융합학과에서 웹 개발을 배우며 가장 크게 깨달은 점은, **"완성보다 배포가 더 어려울 때도 있다"**는 것입니다. 하지만 이 과정을 통해 프로젝트의 빌드 구조와 서버 경로에 대해 깊이 이해할 수 있었습니다. 여러분의 배포도 성공하시길 바랍니다!