• HJ
    ActionMaskTech. Blog
Information
  • About
Blog
  • 전체
    14
  • AI
    3
  • Project
    5
  • Tip
    6
  • Tag
  • Github
  • RSS
  • ©2026 ActionMask. All Rights Reserved.
  1. Home

Vercel 배포 시 Serverless Function 250MB 제한 오류

Next.js 배포 시 Serverless Function의 용량이 과도하게 잡히는 문제
Tip
2025-06-28 21:54
8분

Information
Next.js 15+ 프로젝트를 배포하는 경우에 대한 안내입니다. 다른 플랫폼이나 환경에서는 다르게 적용될 수 있습니다.

개요

Next.js로 개발한 프로젝트를 Vercel에 배포할 때, 간혹 Serverless Function의 용량이 250MB를 초과하여 배포가 실패하는 경우가 있습니다.

이 문제는 실수로 이미지 파일이나 기타 정적 자원이 개발 시 import되어 포함되어 있을 때 발생합니다. Vercel은 Serverless Function의 크기를 250MB 제한하고 있기 때문에, 이 제한을 초과하면 오류가 발생하며 배포가 중단됩니다.

인터넷에 여러가지 해결 방안들이 올라와 있는데, 간단한 설정을 통해 이 문제를 해결할 수 있는 방법을 소개합니다.

All dependencies                               413.79 MB
Max serverless function size was exceeded for 8 functions
Created all serverless functions in: 3.172s
Collected
vercel
serverless
nextjs
react
webpack
cicd
tip
In this article
  • 개요
  • Vercel의 제한
  • 원인 분석
  • 해결 방법
  • 맺음말
  • 참고 자료
static
files
(public/,
static/,
.next/static
): 33.526ms
Build Completed in /vercel/output [59s]
Deploying outputs...
Error: A Serverless Function has exceeded the unzipped maximum size of 250 MB. : https://vercel.link/serverless-function-size
Exiting build container

Vercel의 제한

Vercel은 공식 문서에서 Serverless Function의 크기 제한에 대해 명시하고 있습니다. 이 문서에 따르면, Serverless Function의 최대 크기는 250MB이며, 이는 압축되지 않은 상태에서의 크기를 기준 (압축 후에는 약 50MB)으로 합니다. 즉, 배포 시 모든 코드와 종속성이 포함된 상태에서 250MB를 초과하면 오류가 발생합니다.

Warning
250MB 제한은 요금에 따라 다르게 적용되지 않고, 모두 동일하게 적용됩니다. 별도로 설정할 수 있는 옵션도 없습니다.

원인 분석

공식 문서에 따르면, 몇가지 유형별 문제 발생 원인을 다음과 같이 설명하고 있습니다.

  • 큰 의존성 또는 node_modules 폴더 포함: 가장 일반적인 원인은 매우 큰 node_modules 폴더입니다. 무거운 라이브러리나 많은 패키지에 의존하는 경우, 모두 함수에 번들링됩니다. 또한, 중복된 하위 종속성도 크기를 증가시킬 수 있습니다.
  • 불필요한 파일 포함: 런타임에 필요하지 않은 파일이 배포 번들에 실수로 포함될 수 있습니다. 이는 소스 맵, 문서, 테스트, 빌드 아티팩트 또는 캐시 등을 포함할 수 있습니다. 제대로 구성되지 않은 경우, 전체 디렉토리(예: .next 빌드 캐시, 테스트 디렉토리 또는 로컬 자산 등)를 Serverless Function의 일부로 업로드할 수 있습니다.
  • 정적 자산이 함수에 번들링됨: 큰 정적 파일(이미지, 비디오, JSON 데이터 등)은 Vercel의 CDN 또는 다른 CDN을 통해 제공되어야 하며, Serverless Function 코드 번들에 포함되어서는 안 됩니다. 서버 측 코드에서 자산을 실수로 가져오거나 포함하는 경우, 함수와 함께 패키징될 수 있습니다.
  • 과도한 서버 측 로직 또는 프레임워크 오버헤드: 서버 측에서 많은 코드를 끌어오는 프레임워크나 패턴을 사용하는 경우, 큰 번들이 생성될 수 있습니다. 예를 들어, 서버 측 렌더링 프레임워크가 큰 런타임 코드를 포함하거나, 서버에서 전체 UI 라이브러리를 가져오는 경우가 이에 해당합니다. 특히, 변수 경로로 동적 import 또는 require를 사용하는 경우, 번들러가 디렉토리의 모든 것을 포함하도록 혼란스러워질 수 있습니다.

해결 방법

해결 방안으로, 불필요한 의존성 제거, 트리 쉐이킹, 정적 자산 import 지양, 코드 스프리팅 등을 제안하기도 하는데, 이것들은 일반적인 경우 큰 도움이 되지 않습니다. 경험 있는 개발자는 이미 자신의 코드를 최적화하고 있기 때문에, 이러한 방법은 이미 반영이 되어 있는 경우가 많습니다.

대신, Vercel의 공식 문서에서도 처음으로 제안하듯이, 명시적으로 Serverless Function에 포함시키거나 제외시킬 파일이나 폴더를 설정하는 것입니다.

Next.js 프로젝트에서는 next.config.js 파일에 outputFileTracingExcludes 옵션을 사용하여 Serverless Function에 포함시키지 않을 파일이나 폴더를 지정할 수 있습니다. 이 설정을 통해 불필요한 파일이 번들에 포함되는 것을 방지할 수 있습니다. 이 설정을 통해 효과적으로 Serverless Function의 크기를 줄일 수 있습니다.

예시 설정은 다음과 같습니다.

next.config.ts
import type { NextConfig } from "next";
 
module.exports = {  
  outputFileTracingExcludes: {
    "/public": ["./**"], // public 폴더 및 그 하위 폴더 제외
    "/static": ["./**"], // static 폴더 및 그 하위 폴더 제외
    ".next": ["./**"], // .next 폴더 및 그 하위 폴더 제외
    "*.cache": ["./**"], // .cache 파일 제외
    "node_modules": ["./**"], // node_modules 폴더 및 그 하위 폴더 제외
  },
};
 
// ... 생략 ...

이 설정을 적용 후, Serverless Function의 크기를 다시 확인해보면, 불필요한 파일들이 제외되어 크기가 상당히 줄어든 것을 확인할 수 있습니다.

outputFileTracingExcludes 설정 적용 전후 비교outputFileTracingExcludes 설정 적용 전후 비교

맺음말

Vercel의 Serverless Function 크기 제한 문제를 해결하기 위해, 불필요한 파일이나 폴더를 명시적으로 제외하는 방법을 소개했습니다.

이 글에서 소개한 설정은 Next.js 프로젝트에 간단하게 적용할 수 있으며, Vercel의 공식 문서에서도 권장하는 방법입니다.

코드 최적화 등이 이미 프로젝트에 적용되어 있는 경우, 위 설정을 한번 적용해 보시기 바랍니다.

이 외에도 커뮤니티나 공식 문서에서 다양한 최적화 방법을 제시하고 있으니, 필요에 따라 참고하시기 바랍니다.

참고 자료

  • Vercel Serverless Function 크기 제한
  • Next.js outputFileTracingExcludes
  • Vercel 공식 문서
Tip 카테고리의 다른 글
Ubuntu 24.04 LTS에 r8125 랜카드 드라이버 설치
Ubuntu 24.04 LTS에 r8125 랜카드 드라이버 설치
Ubuntu 24.04 LTS에 r8125 랜카드 드라이버를 설치하는 방법을 알아봅니다.
2025-11-16 17:34
Next.js 프로젝트에서 MDX 코드 블럭 꾸미기
Next.js 프로젝트에서 MDX 코드 블럭 꾸미기
rehype-pretty-code 플러그인으로 MDX 코드 블럭을 꾸며보자.
2025-06-08 20:31
Python Flask를 위한 Gunicorn + NGINX 설정 방법
Python Flask를 위한 Gunicorn + NGINX 설정 방법
Ubuntu에서 Flask 어플리케이션을 Nginx와 Gunicorn을 이용해 서빙해보자.
2024-08-24 13:46
Ubuntu 설치 후 짜잘한 설정 팁
Ubuntu 설치 후 짜잘한 설정 팁
개인적으로 주로 하는 설정 작업을 정리해 보았습니다.
2023-03-02 11:36
Let's Encrypt 설치 및 자동 갱신 (feat. Cloudflare)
Let's Encrypt 설치 및 자동 갱신 (feat. Cloudflare)
무료 SSL 인증서를 설정하고 자동 갱신하자.
2022-02-16 17:34