[🍎코딩애플 강의요약]React 사이트 build 및 GitHub Pages 배포하기

🌈 KJ·2025년 5월 17일

codingapple

목록 보기

14/23

빌드 및 배포의 필요성 🧩

왜 빌드가 필요한가요? 📋

웹브라우저는 HTML, CSS, JS만 해석 가능 💻
React의 JSX, state 등은 브라우저가 직접 이해할 수 없음 ❌
빌드 과정을 통해 브라우저 친화적인 파일로 변환 필요 🔄
변환된 파일을 서버에 올려야 사용자가 접근 가능 🌐

배포 전 체크사항 ✅

프로젝트 확인 📝

콘솔/터미널에 에러가 없어야 함 (경고는 무시 가능) ⚠️
하위 경로 배포 시 추가 설정 필요 📂

하위 경로 배포 설정 🛠️

create-react-app 프로젝트

// package.json
{
  "homepage": "/blog", // 배포할 경로 추가
  // 기타 설정...
}

React Router 사용 시 basename 속성 추가 권장 🔄

Vite 프로젝트

// vite.config.js
export default defineConfig({
  // 기타 설정...
  base: '/blog' // 또는 base: './'
})

/blog/ 경로는 절대 경로, ./는 상대 경로로 CSS 파일 참조 🔗

빌드 작업 과정 🏗️

브라우저 호환 파일 생성 🔄

터미널에서 프로젝트 폴더로 이동
npm run build 명령어 실행
dist 또는 build 폴더에 변환된 파일 생성
index.html이 메인 페이지 📄

GitHub Pages로 배포하기 🚀

리포지토리 생성 📁

GitHub 로그인 후 New Repository 클릭
Repository 이름을 사용자명.github.io로 설정 (중요!) 📛
README 파일 생성 체크 후 리포지토리 생성

빌드 파일 업로드 📤

생성된 리포지토리로 이동
dist 또는 build 폴더 내부 파일을 드래그앤드롭으로 업로드 (폴더 자체가 아닌 내용물만!)
초록색 Commit 버튼 클릭
약 5분 후 https://사용자명.github.io로 접속하여 배포 확인 🌐

다른 이름의 리포지토리 사용하기 (선택사항) 🔄

빌드 전 하위 경로 설정 (0번 항목 참고)
새 리포지토리 생성 (이름 자유롭게 설정)
빌드 파일 업로드
리포지토리 Settings → Pages에서 Source를 None에서 main으로 변경
사용자명.github.io/리포지토리이름으로 접속 가능

자주 묻는 질문 (FAQ) ❓

404 오류가 발생할 때 🚫

배포 후 5분 이상 기다려보기 ⏱️
Ctrl + Shift + R로 강력 새로고침 시도 🔄
리포지토리 이름이 사용자명.github.io 형식인지 확인 🔍

업데이트 방법 🔄

코드 수정 후 다시 npm run build 실행
생성된 파일을 다시 업로드하면 됨
빌드할 때마다 CSS, JS 파일명이 자동 변경되어 캐시 문제 해결 🧹

파일 이름 유지하기 📂

public 폴더에 넣은 파일은 빌드 후에도 이름과 경로 유지
개발 시 /경로로 import 가능

일부 파일이 로드되지 않을 때 🔍

빌드 에러 여부 확인
하위 폴더 배포 설정 확인
개발자 도구에서 파일 경로 확인

라우팅 관련 404 오류 🔀

GitHub Pages는 SPA 라우팅에 제한이 있음
해결책:
- 서버 설정 (GitHub Pages에서는 불가능) ❌
- HashRouter 사용 (# 기호가 URL에 추가됨) ✅

추가 정보 및 팁 💡

사용자 정의 도메인 연결하기 🔗

도메인 제공업체에서 도메인 구매
GitHub 리포지토리 → Settings → Pages에서 Custom domain 설정
DNS 제공업체에서 다음 설정 추가:
- A 레코드: @ → 185.199.108.153 (GitHub IP)
- CNAME 레코드: www → 사용자명.github.io
리포지토리에 CNAME 파일 추가 (내용은 도메인명만)
설정 완료 후 HTTPS 적용 체크

SPA 라우팅 문제 해결하기 ⚡

<!-- 404.html 예시 -->
<!DOCTYPE html>
<html>
<head>
  <script>
    sessionStorage.redirect = location.href;
  </script>
  <meta http-equiv="refresh" content="0;URL='/'">
</head>
</html>

<!-- index.html에 추가 -->
<script>
  (function(){
    let redirect = sessionStorage.redirect;
    delete sessionStorage.redirect;
    if (redirect && redirect != location.href) {
      history.replaceState(null, null, redirect);
    }
  })();
</script>

이 방식으로 SPA 라우팅 문제를 해결할 수 있음 (HashRouter 대안) 🔀

환경변수 활용하기 🌿

// .env 파일
REACT_APP_API_URL=https://api.example.com

// .env.production 파일
REACT_APP_API_URL=https://production-api.example.com

// 코드에서 사용
const apiUrl = process.env.REACT_APP_API_URL;

개발/배포 환경에 따라 다른 설정 사용 가능 🔄
API 주소, 기능 플래그 등을 환경별로 관리 🛠️

CI/CD 자동화 설정하기 🤖

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      - run: npm run build
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: build # 또는 dist

GitHub Actions를 활용한 자동 배포 설정
main 브랜치에 푸시하면 자동으로 빌드 및 배포 🚀

🌈 KJ

이전 포스트

[🍎코딩애플 강의요약]React의 Class 컴포넌트: 옛날 문법 알아보기 📚

다음 포스트

[🍎코딩애플 강의요약]React 사이트 build 및 GitHub Pages 배포하기

codingapple

빌드 및 배포의 필요성 🧩

왜 빌드가 필요한가요? 📋

배포 전 체크사항 ✅

프로젝트 확인 📝

하위 경로 배포 설정 🛠️

create-react-app 프로젝트

Vite 프로젝트

빌드 작업 과정 🏗️

브라우저 호환 파일 생성 🔄

GitHub Pages로 배포하기 🚀

리포지토리 생성 📁

빌드 파일 업로드 📤

다른 이름의 리포지토리 사용하기 (선택사항) 🔄

자주 묻는 질문 (FAQ) ❓

404 오류가 발생할 때 🚫

업데이트 방법 🔄

파일 이름 유지하기 📂

일부 파일이 로드되지 않을 때 🔍

라우팅 관련 404 오류 🔀

추가 정보 및 팁 💡

사용자 정의 도메인 연결하기 🔗

SPA 라우팅 문제 해결하기 ⚡

환경변수 활용하기 🌿

CI/CD 자동화 설정하기 🤖

[🍎코딩애플 강의요약]React의 Class 컴포넌트: 옛날 문법 알아보기 📚

[🍎코딩애플 강의요약]Bootstrap 사용하기 🚀

0개의 댓글