Vercel 배포 환경에서 vite‐plugin‐ssr 적용 시 404 오류 해결 과정 - clappingmin/asterum_traveler GitHub Wiki

문서 목적

이 문서는 Vite 기반 React 프로젝트에서 vite-plugin-ssr을 적용한 후, Vercel 배포 환경에서 발생한 404 오류 문제를 해결한 과정을 정리한 기술 기록이다. 로컬 개발 환경에서는 정상적으로 SSR 페이지가 렌더링되었으나, Vercel 배포 후에는 404 오류가 발생하였고, 이를 해결하기 위한 설정 및 서버 핸들러 구성을 다룬다.

도입 배경

기존 React 프로젝트는 Vite를 기반으로 구성되어 있었으며, 검색 엔진 최적화(SEO)와 초기 렌더링 속도 향상을 위해 vite-plugin-ssr을 도입하였다.

  • 개발 환경에서는 SSR이 정상적으로 동작하며 모든 페이지가 잘 렌더링되었음
  • 그러나 Vercel에 배포한 후, 새로고침 혹은 특정 경로 직접 접근 시 404 NOT_FOUND 오류가 발생함

이 문제는 CSR에서 SSR 구조로 변경하면서 클라이언트 라우팅이 아닌 서버 라우팅이 vercel에 이를 알리지 않음으로 발생했다.

문제 원인 분석

Vercel의 기본 설정은 정적 파일 중심의 라우팅 시스템을 사용한다.
그러나 SSR을 사용하는 애플리케이션은 모든 요청을 하나의 서버 핸들러로 받아 처리해야 한다.

즉, 다음과 같은 상황이 문제의 핵심이다.

  • 사용자가 /report, /schedule 등의 경로에 직접 접근하면, Vercel은 해당 경로에 해당하는 정적 파일을 찾음
  • 해당 정적 파일이 존재하지 않기 때문에 404 오류를 반환함
  • vite-plugin-ssr은 모든 경로를 처리할 수 있는 서버 핸들러로 요청이 전달되어야 SSR이 작동함

해결 방법

이를 해결하기 위해 다음 두 가지 설정을 적용하였다.

1. vercel.json 파일 설정

{
  "rewrites": [
    {
      "source": "/((?!assets/).*)",
      "destination": "/api/ssr.js"
    }
  ]
}
  • 이 설정은 /assets/ 경로를 제외한 모든 요청을 /api/ssr.js로 rewrite한다
  • 즉, 사용자가 어떤 경로로 접근하든 서버 핸들러(/api/ssr.js)로 요청이 도달하게 함

2. api/ssr.js 핸들러 작성

import { renderPage } from 'vite-plugin-ssr/server';

/**
 * @param {import('@vercel/node').VercelRequest} req
 * @param {import('@vercel/node').VercelResponse} res
 */
export default async function handler(req, res) {
  const { url } = req;
  console.log('Request to url:', url);
  if (url === undefined) throw new Error('req.url is undefined');

  const pageContextInit = { urlOriginal: url };
  const pageContext = await renderPage(pageContextInit);
  const { httpResponse } = pageContext;
  console.log('httpResponse', !!httpResponse);

  if (!httpResponse) {
    res.statusCode = 200;
    res.end();
    return;
  }

  const { body, statusCode, headers } = httpResponse;
  res.statusCode = statusCode;
  headers.forEach(([name, value]) => res.setHeader(name, value));
  res.end(body);
}
  • renderPage()는 SSR 렌더링을 수행하며, 클라이언트 라우팅이 아닌 서버 라우팅을 가능하게 함
  • 응답 객체(httpResponse)에 따라 헤더 설정과 상태 코드를 지정하고 결과 HTML을 응답으로 전송함

해결 결과

  • 로컬 개발 환경과 동일하게 Vercel에서도 SSR 페이지가 정상적으로 렌더링됨
  • 새로고침, 직접 URL 접근 등 클라이언트 외부 요청에서도 404 오류 없이 정상 동작
  • SSR을 위해 필요한 서버 라우팅 경로를 적절히 우회시킴으로써 Vercel의 정적 라우팅 제한을 해결함

정리

vite-plugin-ssr을 사용한 SSR 환경에서는, Vercel 배포 시 클라이언트 라우팅이 아닌 서버 라우팅 처리를 위한 설정이 필수적이다.
vercel.json의 rewrite 설정과 api/ssr.js 서버 핸들러를 통해, SSR 구조가 올바르게 동작하도록 수정함으로써 운영 환경에서도 개발 환경과 동일한 SSR 결과를 얻을 수 있었다.