vercel 404 오류 해결: Nextjs 배포에서 빠르게 복구하는 방법

vercel 404 오류 해결이 필요한 상황

vercel 404 오류 해결은 배포 후 특정 경로나 정적 페이지가 404를 반환할 때 즉시 원인을 파악하고 복구할 수 있게 도와줍니다. 이 글에서 얻을 내용은: 원인 분류(빌드/라우팅/정적파일), Next.js 및 vercel.json/next.config.js 설정 예제, 실무에서 바로 적용 가능한 체크리스트와 주의점입니다.

vercel 404 오류 해결 핵심 개념

Vercel에서 404가 발생하는 이유는 크게 빌드 산출물 누락, 라우팅 규칙 불일치, 정적 파일 경로 문제, 그리고 프레임워크(Next.js) 설정 미스매치로 나눌 수 있습니다. Next.js는 페이지 폴더 기반 라우팅과 getStaticPaths/getStaticProps에 의한 사전 생성(static generation) 규칙이 있고, Vercel은 이 빌드 산출물을 그대로 서빙합니다. 따라서 404 진단은 "빌드 시점에 파일이 생성되었는가"와 "배포 시 라우팅 규칙이 올바른가" 두 가지 축으로 진행합니다.

주요 진단 항목:

• 빌드 로그에서 페이지가 생성되었는지 확인
• getStaticPaths의 fallback 설정(fallback: false/true/'blocking') 확인
• next.config.js의 basePath, trailingSlash, exportPathMap 등 설정 확인
• vercel.json의 rewrites/redirects 확인
• 정적 파일(public 폴더) 경로 및 파일 존재 여부 확인

vercel 404 오류 해결 실무 예제

아래 예제는 Next.js 프로젝트에서 동적 경로로 생성한 페이지가 배포 후 404를 반환할 때의 해결 절차와 설정 예시입니다.

1. getStaticPaths 문제 확인

• getStaticPaths에서 모든 경로를 반환하지 않으면 fallback:false일 때 빌드 시 누락되어 404가 발생합니다.

예제: pages/posts/[id].js

// pages/posts/[id].js
export async function getStaticPaths() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json())
  const paths = posts.map(p => ({ params: { id: p.id.toString() } }))
  return { paths, fallback: false }
}

export async function getStaticProps({ params }) {
  const post = await fetch(`https://api.example.com/posts/${params.id}`).then(r => r.json())
  return { props: { post } }
}

export default function Post({ post }) {
  return <article><h1>{post.title}</h1></article>
}

2. vercel.json로 rewrites 설정이 필요한 경우

• SPA 또는 프론트엔드 라우팅이 서버 쪽 rewrite가 필요하면 vercel.json에 규칙을 추가합니다.

예제: vercel.json

{
  "rewrites": [
    { "source": "/app/:path*", "destination": "/index.html" }
  ]
}

3. next.config.js에서 basePath 또는 trailingSlash가 문제인 경우

// next.config.js
module.exports = {
  basePath: '/my-app',
  trailingSlash: false,
}

위 설정으로 인해 페이지 경로가 변경되면 배포 전에 경로를 맞춰주어야 합니다.

rewrites 설정과 catch-all 라우트로 404 회피 (sub_keywords: rewrites 설정, catch-all 라우트)

Vercel에서 SPA 형태의 라우팅(클라이언트 사이드 라우팅)을 사용하는 경우, 서버 측에서 모든 경로를 index.html이나 Next.js가 처리하도록 rewrite해야 합니다. Next.js의 경우 보통 필요 없지만, 정적 export 또는 커스텀 서버를 사용할 때 필요합니다.

예시: catch-all rewrite

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

하지만 Next.js에서 SSR/SSG를 이용하고 있다면 getStaticPaths와 fallback 전략을 먼저 점검해야 합니다.

비교: 404 원인 판단 기준표

이 표는 404 발생 시 빠르게 원인 축을 좁히는 데 사용합니다.

언제 쓰면 좋고 언제 피해야 할까

• 언제 쓰면 좋은가:

  • 정적으로 사전 생성하는 페이지가 많은 경우 getStaticPaths 정합성을 확인하고 복구할 때
  • SPA 라우팅을 정적 파일로 서빙할 때 모든 경로를 rewrite로 처리해야 할 때
  • 프로덕션 배포 후 일부 경로에서만 404가 날 때 원인 추적이 필요할 때

• 언제 피해야 하는가:

  • Next.js의 기본 라우팅을 따르고 있는 경우 불필요하게 global rewrite를 적용하면 오작동을 유발할 수 있습니다.
  • API 경로를 클라이언트 라우트로 강제 rewrite하면 API 호출이 실패할 수 있습니다.

실무 체크리스트

• 빌드 로그 확인: 페이지가 빌드 시 생성되었는가?
• getStaticPaths: 모든 필요한 경로를 반환하거나 fallback 전략이 적절한가?
• next.config.js: basePath, trailingSlash 등 경로 관련 설정 확인
• vercel.json: rewrites/redirects가 의도대로 동작하는가?
• public 파일: 정적 파일이 public/에 존재하는가?
• 테스트: 로컬 vercel dev 또는 vercel preview로 재현 가능한가?
• 캐시: CDN 캐시로 인한 오래된 404가 아닌가?

체크리스트(간단 버전):

• 빌드 로그 이상 여부
• getStaticPaths/fallback 점검
• vercel.json rewrites 확인
• next.config.js 경로 설정 확인
• public 파일 존재 여부
• CDN 캐시 무효화 필요 여부

성능·보안·운영 주의점

성능:

• 불필요한 rewrites는 Vercel의 라우팅 비용(추가 처리)을 증가시킬 수 있습니다. 가능한 경우 빌드 시점에 정적 파일로 생성해 서빙하세요.

보안:

• catch-all rewrite로 모든 경로를 index.html로 보내면 의도치 않게 API 경로가 노출되거나 CSRF/탐지 회피 이슈가 발생할 수 있습니다. API 경로는 명확히 분리하세요.

운영:

• 배포 후 404 발생 시 빠른 롤백 계획을 준비하세요. Vercel은 이전 배포로 롤백이 가능하니, 긴급 대응 시 사용하세요.
• 로그와 모니터링: Sentry, Logflare 등으로 404 트래픽을 모니터링하면 원인 파악이 빨라집니다.

예외 상황과 권장 대응

• 정적 export(export) 후 404: exportPathMap이나 vercel.json rewrite가 필요할 수 있음.
• 다국어 라우팅에서 404: i18n 설정과 basePath 조합을 확인하세요.

자주 묻는 질문

Q1: 배포 직후 일부 페이지에서만 404가 뜹니다. 원인 추적 순서는? A1: (1) 빌드 로그 확인(해당 페이지 생성 여부) (2) getStaticPaths/fallback 확인 (3) vercel.json rewrites 확인 (4) public 파일 존재 여부 (5) CDN 캐시 확인.

Q2: rewrites와 redirects 차이는 무엇인가요? 언제 rewrites를 써야 하나요? A2: rewrites는 내부 경로 매핑(브라우저 URL 변경 없음), redirects는 클라이언트에 3xx 응답을 보내 URL 변경을 유도합니다. 클라이언트 URL을 유지하면서 내부 자원 위치를 바꾸려면 rewrites를 사용하세요.

Q3: fallback: true나 'blocking'로 바꾸면 404가 해결되나요? A3: 경우에 따라 해결됩니다. fallback:false면 빌드 시 없는 경로는 404입니다. 동적 생성할 의도라면 fallback:true 또는 'blocking'을 사용해 런타임에 페이지를 생성하도록 할 수 있습니다. 단, 이러한 변경은 런타임 퍼포먼스 및 SEO 영향이 있을 수 있으니 검토하세요.

Q4: vercel.json을 적용했는데도 404가 지속됩니다. 어떤 추가 검사를 해야 하나요? A4: vercel.json이 루트에 있는지, 파일이 배포 컨텍스트에 포함되었는지 확인하세요. 또한 Vercel의 프로젝트 설정(Framework Preset)과 충돌이 없는지 확인하고, preview/production 환경에서 각각 테스트하세요.

정리

• vercel 404 오류 해결은 빌드 산출물 생성 여부와 라우팅 규칙 점검이 핵심이다.
• getStaticPaths와 fallback 전략을 먼저 확인하고 수정하라.
• vercel.json의 rewrites/redirects와 next.config.js 경로 설정을 점검하라.
• 실무 체크리스트를 사용해 원인 축을 빠르게 좁히고 CDN 캐시/배포 로그를 확인하라.
• 보안과 성능 영향을 고려해 rewrite를 남발하지 말고 필요 시에만 적용하라.