React 프로젝트 배포 방법 — Vercel과 Netlify로 링크 만들기 (비개발자 가이드)
React 프로젝트를 Vercel 또는 Netlify로 배포하는 방법을 단계별로 정리합니다. GitHub 연동부터 React Router 404 해결까지, 비개발자도 따라갈 수 있는 실전 가이드입니다.
React 배포는 “GitHub에 올리고, 플랫폼이 빌드해서, URL을 만들어주는 과정”입니다. React 배포 방법이 궁금해서 이 글을 열었다면, 코드는 이미 만들었는데 링크로 공유하는 단계에서 멈춘 것일 수 있습니다. 이 글 하나로 정리됩니다.
Figma Make로 코드를 뽑고, VS Code에서 수정까지 끝냈다면 이제 남은 단계는 하나입니다. 로컬에서만 돌아가는 프로젝트를 누구나 접속할 수 있는 URL로 바꾸는 것, 즉 React 배포입니다. 이 과정이 막연히 어렵게 느껴질 수 있지만, 구조를 딱 나누고 보면 생각보다 단순합니다. “서버를 직접 세팅해야 하나?”라는 걱정은 할 필요 없습니다. Vercel이나 Netlify 같은 플랫폼이 빌드와 호스팅을 전부 대행해주기 때문입니다.
Figma Make에서 코드를 내보내고 VS Code에서 작업하는 과정이 아직 익숙하지 않다면, Figma Make와 VS Code를 병렬로 쓰는 현실적인 방법을 먼저 참고하면 좋습니다.
React 배포 전체 흐름
React 배포의 기본 구조는 간단합니다.
- 로컬 프로젝트를 GitHub에 올린다
- Vercel 또는 Netlify가 자동으로 빌드한다
- URL이 발급된다
이 세 단계가 전부입니다. 복잡해 보이지만, 각 플랫폼이 대부분의 설정을 자동으로 처리해주기 때문에 실제로 직접 건드릴 부분은 많지 않습니다.
Vercel vs Netlify — 비개발자 기준 비교
두 플랫폼 모두 무료 플랜을 제공하고, React 배포에 적합합니다. 차이점은 다음과 같습니다.
| 항목 | Vercel | Netlify |
|---|---|---|
| GitHub 연동 | Import 한 번으로 자동 배포 | New site from Git으로 연결 |
| React 감지 | 자동 감지 후 기본값 설정 | 프레임워크 자동 감지 지원 |
| 설정 확인 | 대부분 자동, 최소한의 입력 | Build command와 Publish directory를 눈으로 확인 가능 |
| 심리적 부담 | 빠르지만 “뭐가 적용됐지?” 감이 덜 올 수 있음 | 설정을 직접 확인하며 진행할 수 있어 초반에 안심됨 |
| 배포 URL | *.vercel.app | *.netlify.app |
결론적으로, 둘 다 정답입니다. “한 번이라도 덜 막히는 쪽”으로 고르면 됩니다.
Vercel로 React 배포하는 법
GitHub에 프로젝트 올리기
먼저 GitHub에 새 repository를 만들고, 로컬 프로젝트를 커밋한 뒤 푸시합니다. 터미널에서 git init → git add . → git commit → git remote add → git push 순서로 진행하면 됩니다. GitHub Desktop을 쓰고 있다면 GUI로도 동일한 작업이 가능합니다. 여기까지가 “배포 준비”입니다. 이후부터는 버튼 몇 번이면 됩니다.
Vercel에서 Import → Deploy
- Vercel에 GitHub 계정으로 로그인합니다
- 대시보드에서 New Project를 클릭하고, 방금 올린 GitHub repository를 선택(Import)합니다
- Vercel은 React 프로젝트를 자동 감지하고, 빌드 커맨드와 출력 디렉토리를 알아서 설정합니다
- Deploy 버튼을 누르면 빌드가 시작되고, 완료 후 *.vercel.app 주소가 바로 발급됩니다
Vercel 공식 문서에서도 “React를 감지하고 올바른 설정을 자동 적용한다”고 안내하고 있습니다. 별도 설정 없이 Import만 하면 배포가 진행되는 구조입니다. 이후 GitHub에 코드를 푸시할 때마다 자동으로 재배포됩니다.
Netlify로 React 배포하는 법
New site from Git으로 시작
- Netlify에 로그인합니다
- New site from Git → GitHub 연결을 선택합니다
- 배포할 repository를 고릅니다
Build command와 Publish directory 설정
여기서 가장 많이 실수하는 부분이 Publish directory입니다. 프로젝트에서 사용하는 도구에 따라 값이 다릅니다.
| 도구 | Build Command | Publish Directory |
|---|---|---|
| Vite | npm run build | dist |
| Create React App | npm run build | build |
Netlify는 프레임워크를 자동 감지해서 권장값을 제시하지만, 값이 맞는지 한 번 확인하는 습관이 필요합니다. package.json을 열어서 vite가 보이면 dist, react-scripts가 보이면 build로 설정하면 됩니다. 설정 후 Deploy site를 누르면 URL이 발급됩니다. Vercel과 마찬가지로 이후 GitHub에 코드를 푸시하면 자동 재배포가 이루어집니다.
React Router 새로고침 404 문제 해결
React Router(BrowserRouter)를 사용하는 프로젝트는 배포 후 /about 같은 경로에서 새로고침하면 404 에러가 발생할 수 있습니다. React Router 자체의 설정이 아직 안 되어 있다면 피그마에서 만든 React 코드, 뒤로가기가 안 된다면 React Router를 설정하세요를 먼저 확인합니다. 이유는 간단합니다. React는 클라이언트 측에서 라우팅을 처리하지만, 서버는 해당 경로에 실제 파일이 있는지 찾으려 합니다. /about이라는 폴더나 파일이 서버에 없으니 404를 반환하는 것입니다. 해결 방법은 “모든 요청을 index.html로 돌려보내라”는 규칙을 추가하는 것이고, 플랫폼별로 한 줄 설정이면 충분합니다.
Vercel — vercel.json 추가
프로젝트 루트(package.json과 같은 위치)에 vercel.json 파일을 만들고 아래 내용을 넣습니다.
{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }
모든 경로 요청을 index.html로 돌려보내는 설정입니다. Vercel 공식 문서에서 rewrites는 vercel.json으로 정의한다고 안내합니다.
Netlify — _redirects 파일 추가
public 폴더 안에 _redirects 파일을 만들고 아래 한 줄을 작성합니다.
/* /index.html 200
Netlify에서 200 상태 코드를 지정하면 redirect가 아니라 rewrite로 동작합니다. 빌드 시 이 파일이 자동으로 출력 폴더(dist 또는 build)에 복사됩니다.
React 배포 시 자주 하는 실수와 트러블슈팅
React 배포에서 막히는 대부분의 문제는 아래 네 가지에 해당합니다.
배포는 성공인데 화면이 하얗다
Publish directory가 실제 빌드 출력 폴더와 다르게 설정된 경우입니다. Vite 프로젝트라면 dist, Create React App이라면 build가 맞는지 확인합니다. Netlify 대시보드의 Deploy settings에서 Publish directory 값을 다시 한번 점검합니다. 간혹 프로젝트 구조가 모노레포인 경우, 기본 경로가 루트가 아닐 수 있으므로 Base directory도 함께 확인합니다.
빌드 실패 — 로컬에서는 되는데 배포에서 깨진다
배포 전에 로컬에서 npm run build를 직접 실행해서 통과하는지 먼저 확인합니다. 로컬 빌드가 실패하면 배포에서도 그대로 깨집니다. 타입 에러, import 경로 오류, 사용하지 않는 변수 경고가 에러로 처리되는 경우가 흔한 원인입니다. CSS 충돌로 화면이 깨지는 경우도 있는데, 이때는 Figma Make 코드 수정 후 화면이 깨질 때: globals.css·index.css 충돌부터 점검하세요를 참고합니다. 특히 Vite는 빌드 시 TypeScript 타입 검사를 생략하는 반면, 일부 설정에서는 엄격하게 체크할 수 있으므로 로컬 빌드 테스트는 필수입니다.
환경변수(.env) 때문에 API가 안 붙는다
.env 파일은 GitHub에 올라가지 않으므로, 배포 환경에도 자동으로 반영되지 않습니다. Vercel이나 Netlify 대시보드의 Environment Variables 메뉴에서 동일한 값을 직접 입력해야 합니다.
프레임워크마다 환경변수 접두사도 다릅니다. Vite는 VITE_, Create React App은 REACT_APP_으로 시작하는 변수만 클라이언트에서 접근할 수 있습니다. 접두사가 없는 변수는 빌드 시 무시되므로, 배포 후 API 키가 undefined로 찍힌다면 변수명부터 확인합니다. Vercel에서는 대시보드 Settings → Environment Variables에서, Netlify에서는 Site configuration → Environment variables에서 설정할 수 있습니다.
React Router 새로고침 404
vercel.json 또는 _redirects 파일 누락이 원인의 대부분입니다. 위의 React Router 섹션을 참고해서 파일을 추가하면 해결됩니다.
마무리
여기까지 따라왔다면 “코드가 있는 상태”에서 “공유 가능한 URL이 있는 상태”로 바뀐 것입니다. GitHub에 올리고, 플랫폼이 빌드하고, URL을 발급받는 세 단계가 React 배포의 전부입니다.
처음 React 배포를 할 때 가장 많이 막히는 지점은 Publish directory 설정과 React Router 404 문제입니다. 이 두 가지만 잡으면 나머지는 플랫폼이 알아서 해줍니다. Vercel이든 Netlify든 본인이 편한 쪽을 골라서 한 번 시도해보면, 다음부터는 5분이면 끝납니다. 배포가 되는 순간, 프로젝트는 “내 컴퓨터 안의 코드”에서 “링크 하나로 보여줄 수 있는 서비스”가 됩니다. React 배포, 한 번 해보면 별거 아닙니다.