개인 프로젝트나 사이드 프로젝트를 진행하다가 갑자기 "Error: Build completed timeout" 메시지를 보신 적 있나요? 처음엔 잘 배포되다가 프로젝트가 조금씩 커지면서 갑자기 배포가 실패하기 시작하죠. 특히 혼자 작업할 때는 이런 문제를 어디서부터 손대야 할지 막막할 수 있습니다. 오늘은 Vercel 빌드 시간 초과 오류를 해결하는 실전 팁들을 정리해보도록 할게요.
Vercel 빌드 시간 초과 원인과 증상
Vercel에서는 서버리스 구조로 동작하기 때문에 빌드시간에 제한이 있습니다. 무료 플랜기준으로 보자면 보통 45초에서 90초 정도입니다. 혼자 프로젝트를 진행하다 보면 이런 제약사항을 사전에 인지하지 못한 채 디플로이 에러를 마주하게 되면서 배포가를 실패하곤 합니다.
아래의 오류 메세지를 보셨다면 빌드 시간 초과 문제입니다. 대표적인 오류 메세지들을 적어보도록 할게요.:
- Error: Build completed timeout.
- Function crashed with timeout
- Build exceeded the maximum allowed duration
이 오류가 발생하는 주요 원인은 다음과 같아요:
- 프로젝트 규모 과대
- 의존성 최적화 실패
- Next.js 설정 미흡
- API 통신 지연
- 이미지 최적화 미흡
Vercel에서 빌드 시간 줄이는 핵심 방법
혼자 개발하면서도 안정적으로 배포를 하기 위해선 몇 가지 빌드 최적화 전략을 기억해두는 것이 좋습니다. 다음은 실전 꿀팁들 입니다.
- 외부 API 호출은 런타임으로 옮기기
외부 API호출은 빌드 때 하지 않는 것을 권합니다. getStaticProps나 getServerSideProps 안에서 외부 API를 호출하면 빌드할 때 그 응답을 기다려야 합니다. API가 느리면 빌드도 느려지는 거죠. 대신 클라이언트에서 데이터를 불러오거나, API Route를 만들어서 런타임에 처리하는 게 훨씬 빠릅니다. - 이미지 최적화
이미지 크기를 줄여야 합니다. next/image를 사용할 경우, 너무 큰 원본 이미지를 불러오면 빌드 시간이 급증할 수 있습니다. 1MB 넘는 이미지는 WebP 등으로 미리 변환하거나 unoptimized 설정을 고려하는 것을 추천합니다. - devDependencies와 dependencies 구분
개발용 패키지를 정리해야 합니다. 개발용 도구(예: eslint, prettier)는 devDependencies로, 실제 런타임에 필요한 모듈만 dependencies로 설정해 최적화된 패키지 트리를 구성해보세요. 이것만 잘 구분해도 빌드할 때 설치하는 패키지가 줄어듭니다. - 빌드 캐시 활용
Vercel에서는 최근 캐시 기능이 강화되어 일부 .vercel 폴더에 캐시를 유지합니다. 동일한 파일 구조를 유지하면 캐시 재활용이 가능하니 불필요하게 디렉터리를 옮기거나 이름을 바꾸는 건 피하는게 좋습니다. - 사용하지 않는 코드 제거
오래된 페이지, 미사용 컴포넌트, 테스트 코드 등을 정리하면 전체 트리셰이킹(tree-shaking) 최적화가 잘 작동하여 빌드 시간이 줄어듭니다.
무료 계정에서 빌드 초과 시 대처 방법
혼자 개발하면서 무료 Vercel 플랜을 사용할 경우, 아무래도 빌드 시간 제한에 자주 걸리게 됩니다. 무료 계정은 빌드 타임이 제한되어 있기 때문에 일정 이상 넘어가면 강제로 실패합니다.
이럴 때 취할 수 있는 방법은 다음과 같습니다:
- 빌드 타임을 줄이는 구조 리팩토링
- 이미지/정적 파일 외부 호스팅(Cloudinary나 AWS S3 같은 외부 스토리지에 올려두고 링크로만 불러오는 방법도 있음)
- Pro 플랜 고려하기
- 기능별 프로젝트 분리(예를 들어, 블로그와 관리자 페이지를 따로 배포하는 식)
Vercel은 혼자 개발할 때도 정말 편리한 플랫폼이지만, 빌드 시간 제한 때문에 가끔 답답할 때가 있습니다. 하지만 오늘 소개한 방법들만 잘 적용해도 무료 플랜으로도 충분히 안정적인 배포가 가능해요. 프로젝트가 점점 커진다면 유료 플랜이나 필요하다면 프로젝트 분리도 고민해보는 것을 추천드립니다. 작은 것부터 하나씩 개선해나가다 보면 어느새 빌드 시간 걱정 없는 쾌적한 개발 환경을 만들 수 있을 겁니다!