Vercel 배포가 안 될 때 빌드 로그부터 보는 법

로컬에서는 잘 돌아가는데 Vercel 배포만 실패하면, 화면에 보이는 마지막 줄보다 빌드 로그의 첫 오류가 중요합니다.

Vercel 대시보드에서 프로젝트를 고른 뒤 Deployments로 들어가 빨간 표시가 붙은 배포를 엽니다. Deployment Details의 Building을 펼치면 로그가 보입니다. 맨 아래의 exited with 1은 실패했다는 결과일 뿐이므로, 위로 올라가 처음 나온 Error를 찾으세요. 이 문구가 무엇인지에 따라 손볼 곳이 달라집니다.

로컬에서도 배포용 빌드가 실패하는지 확인

먼저 프로젝트 폴더에서 다음 명령을 실행합니다.

npm run build

여기서 같은 오류가 난다면 Vercel 설정 문제가 아니라 코드의 타입이나 문법 문제일 가능성이 큽니다. 개발 서버에서는 지나갔던 오류가 배포용 빌드의 타입 검사에서 드러날 수 있습니다. 로그의 첫 오류를 고친 뒤 다시 빌드하고 push하세요.

.env.local의 값이 Vercel에 없는 경우

.env.local은 보통 Git에 올라가지 않기 때문에 Vercel이 로컬 환경변수를 자동으로 알 수 없습니다. 프로젝트의 Settings > Environment Variables에는 배포에 필요한 변수만 등록하고 적용 환경을 맞추세요.

환경변수를 바꿔도 이미 만들어진 배포에는 소급 적용되지 않습니다. 값을 추가하거나 수정한 뒤에는 Redeploy가 필요합니다. 브라우저에 공개해도 되는 값만 NEXT_PUBLIC_ 접두사를 붙이세요. 이 값은 빌드 때 클라이언트 번들에 포함되므로 API 비밀키나 서버 토큰에는 절대 붙이면 안 됩니다.

로컬과 Node.js 버전이 다른 경우

패키지가 특정 Node.js 버전에서만 동작하면 로컬에서는 통과하고 Vercel에서만 깨질 수 있습니다. Vercel이 현재 지원하는 버전은 20.x, 22.x, 24.x이고 새 프로젝트의 기본값은 24.x입니다.

node -v로 로컬 버전을 확인한 뒤 Settings > Build and Deployment > Node.js Version과 맞추세요. package.json에 다음처럼 메이저 버전을 지정해 두었다면 이 값이 대시보드 설정보다 우선합니다.

{"engines":{"node":"22.x"}}

Module not found가 파일명에서 생기는 경우

맥의 기본 파일시스템은 대소문자를 구분하지 않지만 Vercel의 리눅스 빌드 환경은 구분합니다. 실제 파일이 Button.tsx인데 코드에서 ./button을 불러오면 로컬에서는 되고 배포에서만 실패할 수 있습니다. 오류에 나온 import 경로와 파일명을 글자 단위로 비교해 대소문자를 맞추세요.

패키지 이름이 Cannot find module 'xxx'에 나온다면 package.json도 봐야 합니다. 로컬 node_modules에만 있고 dependencies에 기록되지 않은 패키지는 Vercel의 새 설치 환경에 들어오지 않습니다. npm install 패키지명으로 다시 설치하고 변경된 package-lock.json까지 함께 커밋하세요.

앱이 저장소의 하위 폴더에 있는 경우

앱이 frontend/ 같은 하위 폴더에 있는데 Vercel이 저장소 최상위에서 빌드하면 package.json이나 Next.js를 찾지 못합니다. 로그에 No Next.js version detected와 비슷한 문구가 보인다면 Settings > Build and Deployment > Root Directory에 실제 앱 폴더를 지정하세요. 이 설정은 다음 배포부터 적용됩니다.

배포는 됐지만 특정 요청만 504가 나는 경우

FUNCTION_INVOCATION_TIMEOUT은 빌드 실패가 아니라 함수 실행 시간이 한도를 넘었다는 504 오류입니다. 현재 기본 설정인 Fluid compute에서는 기본 실행 시간이 300초이고, Hobby 플랜은 300초가 최대입니다.

Settings > Functions에서 Fluid compute가 켜져 있는지, Max Duration을 기본값보다 짧게 설정하지 않았는지 확인하세요. Fluid가 꺼진 오래된 프로젝트는 기본 한도가 훨씬 짧을 수 있습니다.

Pro와 Enterprise의 일반 최대는 800초입니다. Next.js App Router의 해당 route 파일에는 다음처럼 선언할 수 있습니다.

export const maxDuration = 800;

Node.js·Python 함수는 800초 초과 1800초까지 베타로 설정할 수 있으며, Next.js App Router에서도 export const maxDuration = 1800;으로 지정합니다. 다른 런타임이나 프레임워크는 vercel.json 설정이 필요할 수 있습니다. Hobby에서 300초보다 오래 걸리는 작업이라면 시간만 늘릴 수 없으므로 Workflows나 Queue 같은 비동기 구조로 나눠야 합니다.

빌드가 시작되기 전에 실패하면 Building 로그가 없을 수도 있습니다. vercel.json 설정 오류처럼 화면에 문구만 나오는 경우에는 그 메시지를 그대로 확인하세요. 도움이 필요하다면 첫 Error, package.json, 폴더 구조를 함께 전달해야 로컬과 Vercel의 차이를 빠르게 좁힐 수 있습니다.