GitHub 페이지에 Vite/React 애플리케이션을 배포하는 것은 흥미로운 이정표이지만, 특히 이미지와 자산을 처리할 때 프로세스에서 예상치 못한 문제가 발생할 수 있습니다. 이 블로그 게시물은 초기 배포부터 일반적인 문제 해결 및 효과적인 솔루션 도달까지 전체 프로세스를 안내합니다.

초심자이든 경험이 있는 사람이든 이 가이드는 일반적인 함정을 피하고 모든 자산이 올바르게 렌더링된 Vite/React 앱을 성공적으로 배포하는 데 도움이 될 것입니다.

전제 조건

자세히 알아보기 전에 다음 사항을 확인하세요.

• Vite/React 프로젝트: 이 가이드에서는 Vite를 빌드 도구로 사용하고 React를 프레임워크로 사용하여 프로젝트를 설정했다고 가정합니다.
• GitHub 저장소: 배포를 위해 애플리케이션을 푸시할 기존 GitHub 저장소가 있어야 합니다.
• GitHub 페이지 활성화: 배포를 위해 저장소 설정에서 GitHub 페이지가 활성화되어 있는지 확인하세요.

1단계: 프로젝트 및 GitHub 페이지 배포 초기화

먼저 Vite/React 애플리케이션이 적절하게 초기화되고 로컬 호스트에서 작동하는지 확인하세요. 다음과 같이 기본 Vite 프로젝트를 생성할 수 있습니다:

npm create vite@latest

종속성 설치:

npm install

로컬에서 프로젝트를 실행하여 모든 것이 제대로 작동하는지 확인하세요.

npm run dev

프로젝트가 준비되면 GitHub 저장소에 푸시하세요.

GitHub 페이지용 vite.config.js 생성

GitHub 페이지는 애플리케이션이 일반적으로 저장소 이름인 특정 기본 URL에서 제공될 것으로 예상합니다. 다음 사항을 반영하도록 vite.config.js 파일을 업데이트하세요.

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

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

기본 옵션은 애플리케이션이 배포될 때 올바른 기본 경로를 사용하도록 보장합니다.

2단계: 프로젝트 빌드 및 배포

배포를 처리하려면 gh-pages 패키지를 설치해야 합니다.

npm install gh-pages --save-dev

package.json에 다음 스크립트를 추가하여 배포 프로세스를 자동화하세요.

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

배포 실행:

npm run deploy

이 시점에서 프로젝트는 https://.github.io//에 게시되어야 하지만, 나와 같다면 몇 가지 문제가 발생할 수 있습니다. 앱이 제대로 렌더링되지 않거나 이미지가 표시되지 않습니다.

3단계: 일반적인 문제 및 해결 방법

문제 1: 배포 후 빈 페이지

배포 후 앱이 빈 페이지를 로드하는 것을 볼 수 있습니다. 이는 라우팅 문제로 인해 발생하는 경우가 많습니다. 기본적으로 서버 측 라우팅에 의존하는 반응 라우터-dom의 BrowserRouter가 사용되지만 GitHub 페이지는 정적 파일을 제공하고 클라이언트 측 경로를 처리하지 않습니다.

해결책: HashRouter 사용

이 문제를 해결하려면 index.js 또는 main.jsx 파일에서 BrowserRouter를 HashRouter로 전환하세요.

참고: 내 프로젝트에서 자주 사용하는 편리한 UI 라이브러리일 뿐이므로 반드시 가질 필요는 없습니다.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

HashRouter는 URL에 해시 기호(#)를 사용하여 탐색 상태를 추적하므로 GitHub 페이지가 404를 반환하지 않고도 다양한 경로를 적절하게 제공할 수 있습니다.

문제 2: 새로 고침 또는 기타 경로에서 404 오류

빈 페이지 문제를 해결한 후 직면할 수 있는 또 다른 문제는 앱이 홈페이지에서 작동하지만 다른 경로로 이동할 때, 특히 /blogs 또는 /projects와 같은 경로에 직접 액세스하는 경우 404 오류가 표시되는 것입니다.

이는 GitHub 페이지가 index.html 파일을 제공하는 방법만 알고 React Router가 관리하는 경로를 인식하지 못하기 때문에 발생합니다.

해결책: GitHub 페이지 설정에서 404 오류 처리

이 문제를 해결하려면 public/ 폴더에 404.html 파일을 만들어야 합니다. 이 파일은 GitHub 페이지가 인식하지 못하는 모든 경로에 대해 index.html 파일을 제공하여 React Router가 라우팅을 처리할 수 있도록 합니다:

1. index.html을 404.html이라는 새 파일에 복사합니다.
2. 이 파일을 public/ 폴더에 넣으세요.
3. 프로젝트를 다시 빌드하고 재배포합니다.

문제 3: 프로덕션에서 이미지가 로드되지 않음

가장 일반적인 배포 문제 중 하나는 이미지가 올바르게 로드되지 않는 것입니다. localhost에서는 제대로 작동하지만 GitHub 페이지에 배포한 후 이미지 링크가 끊어지는 것을 볼 수 있습니다.

예를 들어 구성요소에서 다음과 같은 이미지를 참조할 수 있습니다.

문제: 잘못된 이미지 경로

여기서 문제는 앱이 하위 디렉터리(예: /your-repo-name/)에 배포될 때 절대 경로(/로 시작하는)가 제대로 작동하지 않는다는 것입니다. GitHub 페이지는 https://.github.io/your-repo-name/Images/myImage.png 대신 https://.github.io/Images/myImage.png에서 이미지를 찾으려고 합니다. , 404 오류가 발생합니다.

해결책: BASE_URL 사용

이 문제를 해결하려면 모든 이미지를 공개/이미지로 이동하세요. 이는 선택 사항이지만 그렇게 하는 것이 좋습니다. 환경에 따라 이미지 경로에 BASE_URL을 동적으로 추가합니다.

1. 환경에 따라 달라지는 BASE_URL 상수를 정의합니다.

   const BASE_URL = import.meta.env.BASE_URL;

1. 이미지 참조 시 다음 BASE_URL을 사용하세요.

참고: 이미지 앞의 /를 제거하는 것을 잊지 마십시오. 그렇지 않으면 BASE_URL에서 하나, 제거하는 것을 잊은 /Images에서 하나를 두 배로 갖게 됩니다.

이렇게 하면 개발(localhost)과 프로덕션(GitHub 페이지) 모두에서 올바른 경로가 사용됩니다.

4단계: 최종 배포

라우팅 및 이미지 경로에 대한 수정 사항을 구현한 후 애플리케이션을 다시 빌드하고 다시 배포하세요.

npm run build
npm run deploy

이제 모든 이미지가 올바르게 렌더링되고 모든 경로가 올바르게 처리되어 Vite/React 애플리케이션이 완전히 배포되어야 합니다.

요약:

1. 라우팅 문제: GitHub 페이지와 같은 정적 배포에서 적절한 라우팅을 위해 HashRouter를 사용하세요.
2. 경로의 404 오류: GitHub 페이지가 앱을 올바르게 제공하도록 404.html 파일을 만듭니다.
3. 이미지가 로드되지 않음: 모든 이미지를 공개/이미지로 이동하고 BASE_URL을 자산 경로에 동적으로 추가하여 개발 및 프로덕션 환경을 모두 처리합니다.

이 단계를 수행하면 Vite/React 앱이 GitHub 페이지에서 원활하게 작동하고 활성화되어야 합니다. 즐거운 코딩과 배포를 즐겨보세요!