정적 호스팅 배포

이번 장에서는 리액트 SPA(Single Page Application) 배포에서 가장 흔히 쓰는 방식 중 하나인 정적 호스팅 서비스(Static Hosting Service) 배포 흐름을 정리합니다.

정적 호스팅 서비스란?

정적 호스팅 서비스는 HTML, CSS, JavaScript, 이미지 등과 같은 정적인 파일(Static Files)을 저장하고 웹을 통해 제공하는 서비스입니다.

리액트와 같은 SPA는 빌드 과정을 거치면 결과적으로 이러한 정적 파일들의 집합이 되기 때문에, 정적 호스팅 서비스에 배포하기에 매우 적합합니다.

• 간편한 배포: 대부분 Git 저장소(GitHub, GitLab, Bitbucket 등)와 연동하여 자동 배포(CI/CD)를 쉽게 설정할 수 있습니다.
• 비용 선택: 서비스별 요금·사용량 한도·기능 조건을 확인해 프로젝트에 맞는 플랜을 선택합니다. 무료라는 이유만으로 제한 없이 운영할 수 있다고 가정하지 않습니다.
• 빠른 로딩 속도: CDN(Content Delivery Network)을 사용하여 사용자에게 가장 가까운 서버에서 파일을 제공하므로 로딩 속도가 빠릅니다.
• 운영 부담 분담: 파일 제공 인프라는 서비스가 운영합니다. 사용량 한도·장애·외부 API 지연까지 없어지는 것은 아니므로 자신의 요청 경로를 확인합니다.
• 확장성: 별도의 서버 관리 없이도 쉽게 확장 가능합니다.

다양한 정적 호스팅 서비스가 있지만, 리액트 개발자들에게 인기 있는 몇 가지를 소개합니다.

이 장에서는 Netlify를 중심으로 배포 과정을 설명합니다.

먼저 빌드 산출물, 배포할 브랜치, 출력 경로를 정합니다. 계정별 요금·사용량·권한과 화면의 버튼 이름은 바뀔 수 있으므로 실제 대시보드에서 확인합니다. 아래 UI 이름은 설정 항목을 찾기 위한 예시입니다.

Netlify를 이용한 배포 (GitHub 연동)

Netlify를 사용하여 React 앱을 배포하는 과정은 매우 간단하며, 대부분의 단계가 자동화되어 있습니다.

Netlify 배포 전 준비

Netlify를 통한 배포 과정

자동 배포 (Continuous Deployment)

Netlify의 가장 큰 장점 중 하나는 자동 배포(Continuous Deployment) 기능이에요.

• 한 번 설정해 두면, 여러분이 지정한 브랜치(main 등)에 코드를 푸시할 때마다 Netlify가 이를 감지하여 자동으로 빌드하고 배포를 시작합니다.
• 자동 시작 뒤에도 빌드·배포의 성공 여부와 실제 주소의 응답은 확인합니다. 별도의 테스트 통과를 배포 조건으로 삼으려면 그 의존 관계도 구성해야 합니다.

아래 그림은 배포 이후 요청을 분류하는 운영 설계입니다. 뒤의 간단한 wildcard rewrite 예제보다 엄격하게 앱 경로와 누락 자산을 나누려면 호스트 규칙을 별도로 구성해야 합니다.

커스텀 도메인 설정

임의의 Netlify URL 대신 자체 도메인(예: www.myawesomeapp.com)을 연결할 수 있습니다.

라우팅 문제 해결 (SPA Fallback)

리액트 SPA는 클라이언트 측 라우팅(예: React Router)을 사용합니다.

즉, /about이나 /products/123처럼 클라이언트 라우터가 소유한 앱 경로는 직접 요청해도 index.html을 받을 수 있어야 합니다. 실제 자산과 API 경로는 별도로 처리합니다.

하지만 웹 서버는 기본적으로 요청된 경로에 해당하는 파일이 없으면 404 Not Found 에러를 반환합니다.

이 문제를 해결하기 위해 Netlify와 같은 정적 호스팅 서비스에서는 리다이렉트 규칙을 설정하여 모든 유효하지 않은 경로 요청을 index.html로 fallback 시키는 기능을 제공합니다.

Netlify에서는 프로젝트의 public 폴더 안에 _redirects 파일을 생성하여 이 규칙을 추가할 수 있습니다.

/* /index.html   200

이 기본 규칙은 실제 배포 파일이 있으면 그 파일을 우선 제공하고, 나머지는 URL을 유지한 채 index.html을 200으로 응답하는 rewrite입니다. 누락된 JS·CSS 요청과 앱 밖 경로도 HTML 200으로 가릴 수 있으므로, 그림의 엄격한 404 분기는 이 한 줄만으로 구현되지 않습니다.

이렇게 하면 React Router가 경로를 처리할 수 있게 됩니다.

주의: 이 파일은 public 폴더에 있어야 빌드 시 dist 폴더로 복사됩니다.

파일 요청과 앱 경로를 따로 확인하기

Netlify rewrite의 공식 설명에서 200 rewrite는 원 URL을 유지한 채 다른 파일 내용을 응답하는 동작입니다. 다른 주소로 브라우저를 이동시키는 3xx redirect와 구별합니다. 위 wildcard는 실제 파일을 우선하는 기본 동작이지만, 파일이 없는 나머지 요청을 모두 앱 HTML로 바꿀 수 있습니다.

예시

배포 HTML이 assets/app.js를 참조하고 라우터에 /about이 있다고 가정합니다. 브라우저 Network에서 다음 네 요청의 URL·상태·Content-Type·첫 응답 내용을 나란히 확인합니다. 파일 이름은 실제 빌드에 맞춰 바꿉니다.

이 표는 실제 운영 응답을 이미 확인했다는 보고가 아니라 독자가 수행할 확인 방법입니다. 정적 호스팅은 회원가입 API나 로컬 json-server를 자동으로 실행해 주지 않습니다. API를 쓰는 앱은 브라우저가 접근할 수 있는 별도 API 주소·권한·CORS 조건도 확인합니다.

하위 경로 배포를 독립적으로 판단하기

사이트를 https://example.test/learn/ 아래에 배포했고, 자산 app.js가 /learn/assets/app.js에 있다고 가정합니다. HTML이 /assets/app.js를 요청하면 어디를 찾나요? Vite base를 /learn/에 맞추면 BrowserRouter의 basename과 /learn/about 직접 열기도 자동으로 해결될까요?

기타 정적 호스팅 서비스의 배포 (간략)

다른 주요 정적 호스팅 서비스들도 Netlify와 유사한 배포 과정을 가집니다.

• Vercel
  • Netlify와 거의 동일한 흐름으로 Git 저장소 연동 및 자동 배포를 지원합니다.
  • vercel CLI 도구를 사용하면 명령줄에서도 쉽게 배포할 수 있습니다. (vercel 명령 후 dist 폴더를 선택).
• GitHub Pages
  • 프로젝트의 main (또는 gh-pages) 브랜치에 dist 폴더의 내용을 배포합니다.
  • Vite 프로젝트는 gh-pages 패키지와 vite.config의 base 설정을 함께 사용하면 안정적으로 배포할 수 있습니다.

    {
      "name": "my-react-app",
      "scripts": {
        "dev": "vite",
        "build": "vite build",
        "preview": "vite preview",
        "predeploy": "npm run build",
        "deploy": "gh-pages -d dist"
      },
      "devDependencies": {
        "gh-pages": "^6.3.0"
      }
    }

    vite.config.ts에서 base: '/<YOUR_REPO_NAME>/'를 설정한 뒤 npm run deploy를 실행합니다. base는 자산 경로 설정이며 BrowserRouter의 basename이나 GitHub Pages의 깊은 경로 새로고침 문제까지 자동으로 해결하지는 않습니다.
• Firebase Hosting
  • Firebase CLI를 설치하고 firebase init으로 프로젝트를 초기화한 후, firebase deploy 명령어로 배포합니다.
  • firebase.json 설정 파일에서 public 디렉터리를 dist로, rewrites 규칙을 index.html로 설정하여 SPA 라우팅 문제를 해결합니다.

정적 호스팅에서는 사용자의 URL 요청이 어떤 과정을 거쳐 React Router로 넘어가는지도 함께 이해해야 합니다.

배포 절차 정리와 다음 학습 포인트

이제는 React 앱을 빌드하고, Netlify와 같은 강력하고 편리한 정적 호스팅 서비스를 사용하여 전 세계 사용자에게 배포하는 방법을 익히셨습니다.

• 정적 호스팅 서비스는 React SPA 배포에 가장 적합한 옵션 중 하나입니다.
• Netlify 예제에서는 Git 연동 빌드, 출력 폴더, rewrite와 실제 요청을 연결했습니다. 추가 기능과 비용은 사용하는 계정의 현재 조건을 확인합니다.
• _redirects 파일 설정을 통해 SPA 라우팅 문제를 해결하는 것이 중요합니다.

이제 사용자는 배포된 웹 애플리케이션에 접근해 상호작용할 수 있습니다.