Vercel은 프론트엔드 애플리케이션을 위한 클라우드 플랫폼으로, Vite 같은 최신 빌드 도구와 원활히 통합되어 빠른 배포를 제공합니다.
Vite 기반 React 프로젝트는 npm run build로 생성된 정적 파일을 Vercel에 연결된 Git 리포지토리나 CLI를 통해 자동으로 배포할 수 있습니다.
환경 변수는 대시보드나 vercel env CLI로 쉽게 관리할 수 있으며, 별도로 구매한 도메인은 Vercel 대시보드에서 DNS 설정을 통해 간편히 연결할 수 있습니다.
Vercel은 프론트엔드 배포에 최적화된 클라우드 플랫폼으로, 전 세계 엣지 네트워크(CDN) 위에서 정적 및 동적 콘텐츠를 서빙합니다.
Git 통합을 통해 커밋 단위로 Preview 배포가 자동 생성되며, 팀원 간 실시간 협업이 가능합니다.
npm run buildVite는 dist/ 폴더에 최적화된 정적 자산을 생성합니다.
Vercel은 package.json과 vite.config.js를 분석해 Vite 프로젝트임을 자동으로 인식합니다.
Build Command: npm run build
Output Directory: dist
를 지정한 뒤 배포를 트리거하면, Vercel이 백엔드 없이 정적 파일을 전 세계에 배포합니다.
배포가 완료되면 your-project.vercel.app 도메인이 자동으로 할당되며, 커밋마다 새로운 Preview URL이 생성됩니다.
Vercel 대시보드의 Project Settings > Environment Variables에서 키-값 형식으로 설정할 수 있으며, 값은 암호화되어 안전하게 저장됩니다.
대시보드의 Settings > Domains 메뉴에서 소유 도메인을 입력하고 “Add” 버튼을 클릭합니다.
A 레코드: Vercel에서 제공하는 IP로 설정
CNAME 레코드: cname.vercel-dns.com으로 지정
정상 연결 후 DNS가 전파되면 yourdomain.com으로 애플리케이션을 접근할 수 있습니다.
이를 방지하기 위해 vercel.json에
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}위와 같은 rewrites 설정을 추가하면, 모든 요청이 index.html로 redirect 되어 React Router가 경로를 처리하도록 할 수 있습니다.
좀 더 자세히 알아보면 다음과 같습니다.
Vercel은 배포된 빌드 결과물의 정적 파일을 URL 경로에 매핑하여 서빙합니다. 예를 들어 /about 경로로 요청이 들어오면, Vercel은 루트 디렉터리에 about.html이나 about/index.html 파일이 있는지 찾습니다.
만약 해당 파일이 존재하지 않으면, 내장된 404 페이지를 반환하면서 “Not Found” 오류가 발생합니다.
React Router, Wouter 같은 클라이언트 라우팅 라이브러리는 브라우저의 History API를 이용해 URL 변경을 감지하고, 해당 경로에 맞는 컴포넌트를 렌더링합니다. 서버에는 이 경로에 대응하는 물리적 파일이 없기 때문에, 브라우저에서 직접 새로고침하거나 링크로 접근할 때 서버는 “해당 파일 없음”으로 간주하여 404를 반환합니다.
vercel.json의 rewrites 설정Vercel은 SPA를 지원하기 위해 요청 URL을 다른 파일로 내부적으로 매핑하는 rewrites 기능을 제공합니다.
json
복사편집
{ "rewrites": [ { "source": "/(.*)", "destination": "/index.html" } ] }source: 정규표현식 /(.*)는 모든 경로를 의미합니다.
destination: 모든 요청을 루트의 index.html로 리라이트합니다.
이렇게 설정하면, /contact, /dashboard 등 클라이언트 경로로 직접 접근해도 항상 index.html이 서빙되고, 그 후 React Router가 올바른 컴포넌트를 렌더링합니다.
/profile로 요청을 보냄.vercel.json의 rewrites 규칙에 따라 /profile 요청을 내부적으로 /index.html로 바꿈./index.html 파일이 반환되고, React 애플리케이션이 로드됨./profile)을 읽어 해당 컴포넌트를 렌더링함.Vite 기반 React SPA를 Vercel에 배포할 때 발생하는 404 오류는 서버가 클라이언트 라우팅 경로를 정적 파일로 착각하여 처리하지 못하기 때문에 발생합니다.
vercel.json에 모든 경로를 index.html로 리라이트하도록 설정하면, 서버는 항상 index.html을 반환하고, 이후 클라이언트 라우터가 URL을 해석하여 적절한 화면을 보여주므로 문제를 깔끔하게 해결할 수 있습니다.