React 빌드 결과물을
바로 공개하세요
Vite, Create React App, React SPA의 프로덕션 빌드 폴더를 업로드하고 새로고침에 안전한 라우팅, HTTPS, 커스텀 도메인까지 한 흐름으로 준비하세요.
어떤 폴더를 올려야 하나요?
React 도구마다 결과물 폴더 이름이 다를 수 있습니다.
Vite React
Vite의 기본 정적 결과물은 dist입니다. vite.config.js에서 build.outDir 또는 base를 바꿨다면 실제 결과물 폴더와 자산 URL을 확인하세요.
Create React App
CRA는 프로덕션 파일을 build에 만듭니다. 하위 경로에서 열릴 사이트라면 homepage 설정이 생성된 자산 경로에 영향을 줍니다.
커스텀 React 설정
index.html, JS 번들, CSS, 이미지, 폰트가 정적 파일로 생성된다면 같은 방식으로 게시할 수 있습니다.
React 정적 사이트 배포 방식
React 앱은 빌드 결과물이 기준입니다
React 프로젝트를 그대로 올리는 것이 아니라, 브라우저가 바로 읽을 수 있는 HTML, JavaScript, CSS, 이미지가 들어 있는 빌드 결과물을 올립니다.
DeployPages는 그 정적 파일을 공개 링크로 게시하고, SPA 라우트가 새로고침되어도 index.html로 이어지도록 처리합니다.
흰 화면과 404가 자주 나는 이유
React 배포 문제의 대부분은 잘못된 자산 경로, 누락된 번들 파일, 또는 SPA fallback 설정 누락에서 시작됩니다.
index.html만 올리면 첫 화면은 있어 보여도 CSS와 JS가 빠져 실제 사이트는 비어 보일 수 있습니다.
DeployPages가 맡는 부분
전체 결과물 폴더를 업로드하면 DeployPages가 파일 전송, 공개 링크, HTTPS, 라우트 fallback을 배포 단위로 묶어 처리합니다.
나중에 커스텀 도메인을 붙여도 같은 정적 결과물을 기준으로 운영할 수 있습니다.
정적 React 호스팅
소스 프로젝트가 아니라 배포 가능한 정적 결과물을 안정적으로 공개하는 흐름입니다.
공개 전 확인할 것
React 정적 사이트는 빌드 시점 설정이 그대로 배포에 반영됩니다.
자산 경로
JS나 CSS가 다른 URL에서 로드되면 화면이 비어 보일 수 있습니다. Vite base와 CRA homepage를 먼저 확인하세요.
라우트 새로고침
/login, /pricing, /dashboard처럼 공유될 수 있는 경로를 직접 열고 새로고침해 봅니다.
API와 비밀값
정적 React 앱은 브라우저에서 외부 API를 호출할 수 있지만 백엔드 코드를 실행하지 않습니다. 비밀 키는 프런트엔드 번들에 넣지 마세요.
환경 변수
대부분의 React 빌드 도구는 공개 환경값을 빌드 시점에 번들에 넣습니다. 업로드 후 값을 바꾸려면 다시 빌드해야 하는 경우가 많습니다.
React 앱 배포 절차
프로덕션 빌드 실행
로컬에서 빌드 명령을 실행해 React, CSS, 자산이 하나의 배포용 정적 폴더로 묶이게 합니다.
결과물 폴더 확인
index.html과 생성된 자산 폴더가 함께 있는지 확인합니다. Vite는 보통 dist, CRA는 보통 build입니다.
폴더 전체 업로드
dist 또는 build 폴더 전체를 DeployPages에 업로드합니다. index.html만 올리면 스타일과 스크립트가 빠질 수 있습니다.
딥링크 새로고침 테스트
중첩 라우트를 직접 열고 새로고침해도 호스팅 404가 아니라 React 화면이 유지되는지 확인합니다.
React 배포 문제 해결
배포 후 흰 화면만 보입니다
브라우저 개발자 도구에서 JS/CSS 404를 확인하고, base 또는 homepage 설정과 업로드한 폴더 구조를 다시 점검하세요.
새로고침하면 404가 나옵니다
React Router history mode를 쓰는 경우 SPA fallback이 필요한 경로인지 확인하고, 결과물 폴더 전체를 다시 게시하세요.
이미지나 폰트가 보이지 않습니다
public 자산과 빌드된 자산 폴더가 함께 업로드되었는지 확인합니다. 상대 경로가 하위 경로 기준으로 깨질 수도 있습니다.
API 호출이 동작하지 않습니다
브라우저 CORS, 공개 API URL, 환경 변수의 빌드 시점 반영 여부를 확인하세요. 서버 전용 코드는 별도 백엔드가 필요합니다.
자주 묻는 질문
Q:React 앱이 배포 후 흰 화면으로 보이는 이유는 무엇인가요?
대부분은 자산 경로가 맞지 않거나 번들 파일이 빠진 경우입니다. Vite는 base, CRA는 homepage를 확인하고 생성된 자산이 포함된 폴더 전체를 업로드하세요.
Q:nginx나 redirect를 직접 설정해야 하나요?
아니요. DeployPages가 없는 라우트를 index.html로 이어주는 SPA fallback을 처리하므로 직접 서버 rewrite를 관리할 필요가 없습니다.
Q:프로젝트 폴더와 dist 폴더 중 무엇을 올려야 하나요?
소스 프로젝트가 아니라 프로덕션 결과물 폴더를 올립니다. Vite는 보통 dist, Create React App은 보통 build입니다.
Q:환경 변수를 사용할 수 있나요?
가능하지만 로컬에서 빌드할 때 값이 반영됩니다. DeployPages는 최종 정적 결과물을 호스팅하므로 서버 런타임에서 값을 주입하는 방식은 이 흐름에 포함되지 않습니다.
Q:배포된 React 앱이 API를 호출할 수 있나요?
네. 정적 React 앱은 브라우저에서 외부 API를 호출할 수 있습니다. 다만 프런트엔드 코드에 들어간 값은 사용자에게 보이므로 비밀값은 백엔드에 두어야 합니다.
Q:Next.js도 여기서 배포할 수 있나요?
정적 사이트로 export한 경우 가능합니다. output: 'export'를 사용하고 생성된 out 폴더를 업로드하세요. 서버 렌더링이 필요한 Next.js 라우트는 별도 런타임이 필요합니다.
Q:나중에 커스텀 도메인을 붙일 수 있나요?
네. 사이트 게시 후 콘솔에서 도메인을 추가하고 DNS 안내를 따르면 됩니다. 레코드가 확인되면 DeployPages가 HTTPS를 자동으로 준비합니다.