Vercel 배포 후 404 에러 해결 방법

Introduction

Vercel에 프로젝트를 배포한 후 404 에러가 발생하는 경우가 많습니다. 이번 포스트에서는 404 에러의 원인과 해결 방법을 살펴보겠습니다.

Environment

vercel --version
# 33.0.0

node --version
# v20.11.0

# 프로젝트 구조
my-app/
├── pages/
│   ├── index.js
│   └── api/
│       └── users.js
└── vercel.json

Problem

배포 후 특정 경로에서 404 에러가 발생했습니다:

# 브라우저 에러
404: NOT_FOUND
Code: NOT_FOUND

# API 응답
{
    "error": "The deployment could not be found on Vercel",
    "code": "DEPLOYMENT_NOT_FOUND"
}

Analysis

404 에러 유형

유형	설명	해결책
페이지 404	라우트 미정의	페이지 생성
API 404	API 미구현	API 라우트 생성
정적 파일 404	파일 누락	파일 배포
설정 404	라우팅 설정 오류	vercel.json 수정

Solution

1. 라우트 설정 확인

// vercel.json
{
    "rewrites": [
        {
            "source": "/old-path",
            "destination": "/new-path"
        },
        {
            "source": "/api/:path*",
            "destination": "/api/:path*"
        }
    ],
    "redirects": [
        {
            "source": "/legacy",
            "destination": "/modern",
            "permanent": true
        }
    ]
}

2. 동적 라우트 설정

// pages/blog/[slug].js
export async function getStaticPaths() {
    const posts = await fetchPosts();

    const paths = posts.map((post) => ({
        params: { slug: post.slug },
    }));

    return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
    const post = await fetchPost(params.slug);

    return {
        props: { post },
    };
}

export default function BlogPost({ post }) {
    return (
        
            {post.title}
            {post.content}
        
    );
}

3. API 라우트 설정

// pages/api/users/[id].js
export default function handler(req, res) {
    const { id } = req.query;

    const user = users.find(u => u.id === id);

    if (!user) {
        return res.status(404).json({ error: 'User not found' });
    }

    res.status(200).json(user);
}

4. 정적 파일 배포

// next.config.js
const nextConfig = {
    output: 'standalone',

    async rewrites() {
        return [
            {
                source: '/assets/:path*',
                destination: '/public/assets/:path*',
            },
        ];
    },
};

module.exports = nextConfig;

5. 404 페이지 커스터마이징

// pages/404.js
export default function Custom404() {
    return (
        
            404 - Page Not Found
            The page you are looking for does not exist.
            Go back home
        
    );
}

6. 빌드 후 검증

# 로컬에서 빌드 테스트
$ npm run build

# 빌드 결과 확인
$ ls .next/server/pages

# Vercel CLI로 배포 테스트
$ vercel --prod

Lessons Learned

라우트 검증: 배포 전 로컬에서 모든 라우트가 작동하는지 확인하세요
vercel.json 설정: 리라이트와 리다이렉트를 올바르게 설정하세요
동적 라우트: getStaticPaths에서 fallback 설정을 확인하세요
에러 페이지: 커스텀 404 페이지를 제공하여 사용자 경험을 개선하세요
빌드 검증: 배포 전 반드시 빌드를 테스트하세요

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.