[TIL-0516] Vercel 배포 오류 해결

🌟 Vercel 배포 후 404 에러

Vercel에서 React(특히 React Router를 사용하는 SPA)를 배포했을 때 특정 라우트에서 404 NOT_FOUND가 발생하는 경우가 있다.
이 에러는 vercel.json 파일을 프로젝트 루트에 추가해서 리다이렉트 설정을 해주면 해결된다.

---

🌟 문제 상황: /travel-plan 경로 접근 시 404 발생

1. React Router는 클라이언트 사이드 라우터

   React Router는 브라우저 내부에서 JavaScript로 동작하는 클라이언트 라우팅 시스템이다.

   • 사용자가 /travel-plan 경로로 이동하면, React Router는 그 URL을 감지해서 브라우저를 새로 고침하지 않고 해당 컴포넌트를 렌더링 해준다.
   • 예를 들어, App.tsx 안에서 이런 식으로 라우팅을 정의했다고 하면,

     <Routes>
       <Route path="/travel-plan" element={<TravelPlanPage />} />
     </Routes>

     ➡️ 이건 브라우저가 React 앱을 실행 중일 때만 작동한다.

2. 브라우저 새로고침 시 서버는 URL을 직접 해석

   하지만 /travel-plan 경로를 브라우저 주소창에 직접 입력하거나 새로고침하면

   • 브라우저는 서버(Vercel)에게 "/travel-plan이라는 HTML 파일 줘"라고 요청한다.
   • 그런데 Vercel 서버에는 실제로 travel-plan.html 같은 물리적인 파일이 없다.
   • 그 결과, 서버는 404 NOT FOUND를 반환한다.

---

🌟 해결 방법: vercel.json의 리다이렉트 설정

프로젝트 루트에 아래와 같은 vercel.json 파일을 추가한다.

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

• 설정 의미

  설정 항목	설명
  "source": "/(.*)"	모든 경로(/, /travel-plan, /about 등)를 감지
  "destination": "/index.html"	전부 index.html 파일로 리다이렉트

• 즉, Vercel 서버가 /travel-plan 요청을 받아도 404로 처리하지 않고, 대신 index.html을 반환한다.

• 그 결과 React 앱이 정상적으로 로드되고, React Router가 다시 라우팅을 처리하게 된다.

• 이 파일을 추가한 후, vercel에 다시 배포(push)하면 https://your-vercel-app.vercel.app/travel-plan 같은 주소로 직접 접속해도 에러 없이 화면이 뜨게 된다.

---

🌟 .vercelignore 설정

.vercelignore 파일은 Vercel이 배포 시 무시할 파일/폴더를 지정하는 파일이다.
기능적으로는 Git의 .gitignore와 매우 유사하다.

반드시 필요한 것은 아니지만, 배포 속도 최적화나 불필요한 파일 누락에 유리하다.

• .vercelignore 추천 내용
  Vite + TypeScript 기반 프론트엔드 프로젝트에서 .vercelignore에 추가하면 좋은 항목들이다.

   # 개발 도구 설정 파일
   .vscode
   *.log
   *.tsbuildinfo
  
   # 빌드 결과물 (Vercel에서 자체 빌드하기 때문에 업로드 불필요)
   dist/
  
   # 환경 변수 파일 (보안상 제외)
   .env
   .env.* 
  
   # 테스트/커버리지
   coverage/
   __tests__/
   __mocks__/
  
   # 기타 불필요한 파일
   README.md

  • 이유 설명

    항목	이유
    .vscode, *.log	로컬 개별 환경 설정, 로그는 배포에 불필요
    dist/	Vercel이 직접 빌드하므로 사전 빌드 결과물은 무시
    .env, .env.local	민감한 정보 포함 가능. 서버에 올리면 보안 위험
    README.md	문서 파일로 배포에 필요 없음
    coverage/, __tests__/	테스트 결과물이나 테스트용 코드 폴더

• node_modules는 .vercelignore에 추가할 필요 없다.

  • 이유 1: Vercel은 node_modules를 자동으로 무시한다.

    • Vercel은 package.json과 package-lock.json 기반으로 빌드 시 npm install을 실행해서 필요한 의존성을 설치한다.
    • node_modules는 빌드 결과물이 아니라 빌드 과정에서 생기는 중간 산물이므로, 올릴 필요도 없고 올려도 쓰지 않는다.

  • 이유 2: .vercelignore에 넣어도 효과가 없다.

    • 사실 .vercelignore에 node_modules를 넣어도 이미 무시되고 있으므로 중복 설정이다.
    • 즉, node_modules는 Vercel이 무시하고 있어서 굳이 다시 쓰지 않아도 된다.

  • 이유 3: Vercel에 node_modules가 포함되면 오히려 문제가 된다.

    • 용량이 매우 커서 배포 속도가 저하된다.
    • OS/환경 차이로 인해 충돌 가능성이 있다.