Vite/React 애플리케이션 배포 및 이미지 관리 완벽 가이드

Vite/React 애플리케이션 배포 개요

Vite와 React를 사용하여 개발한 애플리케이션을 GitHub Pages에 배포하는 것은 멋진 이정표지만, 이미지와 자산을 다루면서 예상치 못한 문제에 직면할 수 있습니다. 이번 글에서는 Vite/React 애플리케이션을 성공적으로 배포할 수 있도록 초기 배포부터 일반적인 문제 해결까지 모든 과정을 자세히 설명하겠습니다.

사전 준비 사항

배포를 시작하기 전에 다음 사항을 확인해 주세요:

1. Vite/React 프로젝트: Vite를 빌드 도구로 사용하고 React를 프레임워크로 설정한 프로젝트가 필요합니다.
2. GitHub 저장소: 애플리케이션을 배포하기 위해 이미 존재하는 GitHub 저장소가 있어야 합니다.
3. GitHub Pages 활성화: 저장소 설정에서 GitHub Pages가 활성화되어 있는지 확인합니다.

1단계: 프로젝트 초기화 및 GitHub Pages 배포 설정

먼저 Vite/React 애플리케이션이 제대로 초기화되어 로컬호스트에서 작동하는지 확인해야 합니다. 기본적인 Vite 프로젝트를 만드는 방법은 다음과 같습니다:

npm create vite@latest

종속성을 설치합니다:

npm install

로컬에서 프로젝트를 실행하여 모든 기능이 정상적으로 작동하는지 확인합니다:

npm run dev

프로젝트가 준비되면 이제 GitHub 저장소에 푸시합니다.

GitHub Pages를 위한 vite.config.js 생성하기

GitHub Pages는 애플리케이션이 특정 기본 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()],
})

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

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://<your-username>.github.io/<your-repo-name>/에서 라이브로 제공되어야 하지만, 애플리케이션이 제대로 렌더링되지 않거나 이미지가 표시되지 않는 문제에 직면할 수 있습니다.

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

문제 1: 배포 후 빈 페이지

배포 후 애플리케이션이 빈 페이지로 로드될 수 있습니다. 이는 라우팅 문제로 인해 발생하는 경우가 많습니다. 기본적으로 react-router-dom의 BrowserRouter를 사용하므로 서버 측 라우팅을 필요로 하지만, GitHub Pages는 정적 파일을 제공하며 클라이언트 측 경로를 처리하지 않습니다.

해결책: HashRouter 사용

이 문제를 해결하려면 index.js 또는 main.jsx 파일에서 BrowserRouter를 HashRouter로 변경합니다.

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

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <ChakraProvider>
      <HashRouter>
        <App />
      </HashRouter>
    </ChakraProvider>
  </StrictMode>
);

HashRouter는 URL에 해시 기호(#)를 사용하여 내비게이션 상태를 추적하므로 GitHub Pages가 서로 다른 경로를 적절하게 제공할 수 있습니다.

문제 2: 새로 고침하거나 다른 경로에서 404 오류

빈 페이지 문제를 해결한 후, 애플리케이션이 홈페이지에서만 작동하고 다른 경로로 이동할 때 404 오류가 발생할 수 있습니다. 이는 GitHub Pages가 index.html 파일만 제공되며 React Router가 관리하는 경로를 인식하지 못하기 때문에 발생합니다.

해결책: GitHub Pages 설정에서 404 오류 처리

이 문제를 해결하기 위해 public/ 폴더에 404.html 파일을 생성해야 합니다. 이 파일은 GitHub Pages가 인식하지 못하는 경로에 대해 index.html 파일을 제공하도록 보장합니다:

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

문제 3: 프로덕션에서 이미지 로딩 문제

가장 일반적인 배포 문제 중 하나는 이미지가 올바르게 로딩되지 않는 것입니다. 로컬에서는 잘 작동했지만, GitHub Pages에 배포한 후에는 깨진 이미지 링크를 발견할 수 있습니다.

예를 들어, 컴포넌트에서 이미지를 다음과 같이 참조할 수 있습니다:

<Image
  objectFit='cover'
  src="/Images/myImage.png"
  alt="thumbnail"
/>

문제: 이미지 경로 오류

절대 경로(앞에 /가 붙은)는 서브디렉토리(예: /your-repo-name/)에 배포될 때 잘 작동하지 않습니다. GitHub Pages는 이미지를 https://<username>.github.io/Images/myImage.png에서 찾으려고 시도하므로 404 오류가 발생합니다.

해결책: BASE_URL 사용

이 문제를 해결하려면 모든 이미지를 Public/Images로 이동해야 하며, 환경에 따라 동적으로 BASE_URL을 이미지 경로에 추가합니다:

const BASE_URL = import.meta.env.BASE_URL;

이미지를 참조할 때 이 BASE_URL을 사용합니다:

<Image
  objectFit='cover'
  src={BASE_URL + "Images/myImage.png"}
  alt="thumbnail"
/>

주의: Images 앞의 /를 삭제하는 것을 잊지 마세요. 그렇지 않으면 BASE_URL과 /Images로 인해 경로가 이중으로 생성됩니다.

이렇게 하면 개발 환경(로컬호스트)과 프로덕션(GitHub Pages) 모두에서 올바른 경로가 사용됩니다.

4단계: 최종 배포

라우팅 및 이미지 경로에 대한 수정 사항을 적용한 후, 애플리케이션을 다시 빌드하고 배포하십시오:

npm run build
npm run deploy

이제 Vite/React 애플리케이션이 모든 이미지가 올바르게 렌더링되고 모든 경로가 적절하게 처리된 상태로 배포되어야 합니다.

요약

• 라우팅 문제: 정적 배포(예: GitHub Pages)에서 적절한 라우팅을 위해 HashRouter를 사용하세요.
• 경로에서 404 오류: 404.html 파일을 생성하여 GitHub Pages가 애플리케이션을 올바르게 제공하도록 합니다.
• 이미지 로딩 문제: 모든 이미지를 Public/Images로 이동하고 asset 경로에 BASE_URL을 동적으로 추가하여 개발 및 프로덕션 환경을 처리합니다.

이 단계를 따르면 Vite/React 애플리케이션이 GitHub Pages에 성공적으로 배포될 것입니다. 프로그래밍과 배포를 즐기세요!

참고 URL

• Vite 공식 문서
• React Router 문서
• GitHub Pages 공식 문서

도움이 될 다른 자료

• Vite에서의 이미지 관리
• React를 활용한 정적 사이트 생성