Vercel 배포 시 빌드 에러 해결 방법

Introduction

Vercel에 프로젝트를 배포할 때 빌드 에러가 발생하는 경우가 많습니다. 이번 포스트에서는 흔한 빌드 에러와 그 해결 방법을 살펴보겠습니다.

Environment

# Vercel CLI
vercel --version
# 33.0.0

node --version
# v20.11.0

npm list next
# next@14.1.0

Problem

Vercel 배포 시 다음과 같은 빌드 에러가 발생했습니다:

# 빌드 에러 로그
Error: > Build optimization failed: found an unexpected option '--turbo'

# 또는
Error: Module not found: Can't resolve 'fs'

# 또는
Build error occurred
Error: Cannot find module 'next/dist/server/require-hook'

Analysis

흔한 빌드 에러 유형

에러 유형	원인	빈도
Module not found	모듈 미설치 또는 경로 오류	높음
Memory limit	빌드 메모리 초과	중간
Node.js 버전	호환성 문제	중간
설정 오류	next.config.js 등	높음

Solution

1. next.config.js 최적화

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
    reactStrictMode: true,
    swcMinify: true,

    // 빌드 최적화
    experimental: {
        optimizePackageImports: ['lodash', 'date-fns'],
    },

    // 모듈 분석
    modularizeImports: {
        'lodash': {
            transform: 'lodash/{{ member }}',
        },
    },

    // 번들 분석 (선택)
    bundleAnalyzer: process.env.ANALYZE === 'true',
};

module.exports = nextConfig;

2. 빌드 메모리 확장

{
    "scripts": {
        "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
    }
}

3. Vercel 환경 설정

// vercel.json
{
    "buildCommand": "npm run build",
    "outputDirectory": ".next",
    "framework": "nextjs",
    "installCommand": "npm install",
    "regions": ["iad1"],
    "env": {
        "NODE_OPTIONS": "--max-old-space-size=4096"
    }
}

4. Node.js 버전 설정

// package.json
{
    "engines": {
        "node": ">=18.0.0",
        "npm": ">=9.0.0"
    }
}

5. 빌드 스크립트 수정

{
    "scripts": {
        "build": "next build",
        "postbuild": "echo Build completed"
    }
}

6. Vercel CLI 로컬 빌드 테스트

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

# 프로덕션 빌드
$ vercel build --prod

# 빌드 로그 확인
$ vercel logs

Lessons Learned

로컬 테스트: 배포 전 반드시 로컬에서 빌드를 테스트하세요
메모리 관리: 큰 프로젝트에서는 빌드 메모리를 확장하세요
환경 설정: Vercel 대시보드에서 환경 변수를 올바르게 설정하세요
버전 고정: Node.js와 npm 버전을 명시적으로 고정하세요
에러 로그 분석: 빌드 에러 로그를 주의 깊게 분석하세요

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