2026. 6. 17.

Vercel 배포 실패한 Next.js 초보가 3분 만에 확인할 5가지

로컬에서는 되는데 Vercel 배포만 실패할 때는 코드를 다시 만들기보다 로그, 빌드 재현, 환경변수, Suspense, 정적 생성 순서로 좁히면 됩니다.

4 min read
Vercel 배포 실패한 Next.js 초보가 3분 만에 확인할 5가지 대표 이미지

Vercel 배포 화면에 빨간 실패 표시가 뜨면 초보자는 코드를 전부 다시 만들어야 한다고 느끼기 쉽습니다. 특히 AI 코딩 도구로 빠르게 만든 Next.js 앱은 로컬 화면이 멀쩡해도 배포에서만 막히는 일이 있습니다. 이때 필요한 것은 더 긴 설명이 아니라, 실패 원인을 3분 안에 줄이는 순서입니다.

Vercel 배포 실패를 로그, 환경변수, 로컬 빌드, 재배포 순서로 좁히는 작업 보드

이 글은 Build Failed를 처음 본 사람을 기준으로 작성했습니다. 목표는 한 번에 모든 오류를 고치는 것이 아니라, AI나 동료에게 정확히 물어볼 수 있을 만큼 원인을 좁히는 것입니다.

1분째에는 배포 로그의 첫 번째 빨간 줄만 찾습니다

vercel.com 공식 문서는 빌드 실패가 발생하면 Deployments 페이지에서 오류 메시지를 확인해 원인을 조사하라고 안내합니다. 여기서 초보자가 가장 많이 하는 실수는 로그 전체를 복사하거나, 마지막 줄의 exited with 1만 보는 것입니다. 마지막 줄은 결과일 때가 많고, 실제 단서는 그보다 위에 있습니다.

먼저 실패한 Deployment를 열고 Build Logs에서 빨간색 오류가 처음 등장하는 줄을 찾습니다. Vercel 로그 문서에 따르면 빌드 로그에는 빌드 과정의 경고와 오류가 표시되고, 특정 로그 줄 링크도 공유할 수 있습니다. 그러니 아래 세 가지만 복사합니다.

  • 처음 등장한 빨간 오류 줄
  • 그 위아래 10줄
  • 실패한 명령어 한 줄

예를 들어 Command "npm run build" exited with 1만 복사하면 AI도 원인을 추측해야 합니다. 반대로 Module not found, useSearchParams() should be wrapped in a suspense boundary, Failed to collect page data, process.env.API_KEY is undefined처럼 앞쪽 오류를 함께 주면 바로 다음 행동이 정해집니다.

2분째에는 로컬에서 같은 빌드를 재현합니다

로컬 개발 서버가 뜬다는 사실은 배포가 성공한다는 뜻이 아닙니다. next dev는 개발용이고, Vercel 배포는 보통 프로덕션 빌드 과정에서 실패합니다. 프로젝트 루트에서 먼저 이 명령을 실행합니다.

npm run build

같은 오류가 로컬에서도 나오면 Vercel 문제가 아니라 코드나 설정 문제일 가능성이 큽니다. 이 경우에는 오류 메시지를 기준으로 파일을 고치면 됩니다. 로컬은 성공하고 Vercel만 실패한다면 환경변수, Node 버전, 빌드 명령, 프로젝트 설정 차이를 의심합니다.

Vercel CLI를 쓰는 프로젝트라면 공식 문서의 vercel pull 또는 vercel env pull 흐름도 확인할 수 있습니다. vercel pull은 프로젝트 설정과 환경변수를 로컬 캐시에 저장해 vercel build나 vercel dev에 활용합니다. vercel env pull [file]은 개발 환경 변수를 로컬 파일로 내보내는 명령입니다. 단, 민감한 키를 채팅창이나 공개 문서에 붙여 넣으면 안 됩니다.

초보자가 배포 실패를 확인할 때 따라가는 5단계 체크리스트

환경변수 오류는 이름과 환경부터 봅니다

배포에서만 undefined가 나오면 환경변수부터 확인합니다. Vercel 환경변수 문서는 환경변수가 코드 밖에서 관리되는 키-값 설정이며, Development, Preview, Production 같은 환경별로 달라질 수 있음을 전제로 설명합니다. 초보자는 로컬 .env.local에 값이 있다는 이유로 Production에도 값이 있다고 생각하기 쉽습니다.

확인 순서는 단순합니다.

  1. Vercel Project Settings의 Environment Variables에 같은 이름이 있는지 봅니다.
  2. Production 배포라면 Production 환경에 체크되어 있는지 봅니다.
  3. 브라우저 코드에서 읽는 값이라면 이름이 NEXT_PUBLIC_으로 시작하는지 봅니다.
  4. 서버 코드에서만 쓰는 비밀값은 NEXT_PUBLIC_을 붙이지 않습니다.
  5. 환경변수를 바꾼 뒤에는 새 배포가 필요합니다.

nextjs.org 공식 문서는 기본적으로 환경변수가 서버에서만 사용 가능하고, 브라우저에 노출하려면 NEXT_PUBLIC_ 접두사가 필요하다고 설명합니다. 또 NEXT_PUBLIC_ 값은 next build 시점에 번들에 포함됩니다. 그래서 이미 빌드된 배포에서 값을 바꾸는 것만으로 브라우저 코드가 즉시 바뀐다고 기대하면 안 됩니다.

useSearchParams 오류는 Suspense 경계를 먼저 봅니다

Next.js App Router에서 검색 파라미터를 읽는 페이지가 배포에서 막히는 경우가 있습니다. 공식 오류 문서는 useSearchParams()를 Suspense 경계 없이 읽으면 해당 클라이언트 컴포넌트 트리가 클라이언트 렌더링으로 전환될 수 있다고 설명합니다.

배포 로그에 useSearchParams() should be wrapped in a suspense boundary가 보이면 다음 순서로 봅니다.

  • useSearchParams()를 쓰는 컴포넌트가 어디인지 찾습니다.
  • 그 컴포넌트가 클라이언트 컴포넌트인지 확인합니다.
  • 해당 컴포넌트를 사용하는 위치에서 <Suspense fallback={...}>로 감쌉니다.
  • 페이지 전체를 무리하게 클라이언트 컴포넌트로 바꾸지 않습니다.

예시는 이런 형태입니다.

import { Suspense } from "react";
import SearchPanel from "./search-panel";

export default function Page() {
  return (
    <Suspense fallback={<div>검색 조건을 불러오는 중입니다.</div>}>
      <SearchPanel />
    </Suspense>
  );
}

이 코드는 정답 템플릿이라기보다 방향입니다. 실제 프로젝트에서는 SearchPanel 안에서 useSearchParams()를 쓰고 있는지, 그 파일 상단에 "use client"가 필요한지 함께 봐야 합니다.

Failed to collect page data는 빌드 중 실행되는 코드를 의심합니다

Failed to collect page data나 페이지 데이터 수집 시간 초과가 나오면 해당 페이지가 빌드 중 실행하는 코드가 문제일 수 있습니다. Next.js 공식 문서는 페이지 데이터 수집 시간 초과의 해결 방향으로 무한 루프, resolve 또는 reject되지 않는 Promise, 너무 긴 네트워크 요청, staticPageGenerationTimeout 설정 확인을 제시합니다.

초보자가 바로 볼 수 있는 지점은 네 가지입니다.

  • 빌드 중 외부 API를 호출하는 코드가 있는지
  • API 주소가 환경변수 누락으로 빈 값이 되었는지
  • 서버에서만 가능한 객체를 정적 생성 중에 실행하고 있지 않은지
  • 실패한 경로가 로그에 함께 표시되는지

여기서 중요한 것은 "Vercel이 이상하다"로 시작하지 않는 것입니다. 먼저 로그에 나온 경로를 열고, 그 페이지가 빌드 시점에 무엇을 가져오는지 봅니다. 외부 API가 느리거나, 인증키가 없거나, 브라우저 전용 객체를 서버 빌드에서 읽으면 로컬 개발 중에는 지나가던 문제가 배포에서 드러날 수 있습니다.

AI에게 넘길 배포 오류 정보 묶음 템플릿

AI에게는 오류 전체가 아니라 재현 묶음을 줍니다

배포 실패를 AI에게 물어볼 때는 "이거 왜 안 돼?"보다 아래 묶음이 훨씬 빠릅니다.

상황: Next.js 앱을 Vercel에 배포했는데 빌드가 실패했습니다.
로컬 결과: npm run build 실행 시 같은 오류가 납니다 또는 로컬은 성공합니다.
첫 오류 줄: 여기에 Build Logs의 첫 빨간 줄을 붙입니다.
주변 로그: 오류 위아래 10줄을 붙입니다.
관련 파일: 로그에 나온 page.tsx, layout.tsx, component 파일 경로를 적습니다.
이미 확인한 것: 환경변수 이름, Production 체크 여부, NEXT_PUBLIC_ 필요 여부를 적습니다.
원하는 답: 원인 후보를 3개로 좁히고, 가장 먼저 바꿀 코드 한 곳을 알려주세요.

이렇게 물으면 AI가 전체 코드를 다시 만들 가능성이 줄어듭니다. 배포 오류 해결은 많은 코드를 새로 쓰는 일이 아니라, 빌드가 실제로 멈춘 지점을 좁히는 일입니다.

마지막으로 지금 할 일은 하나입니다. 실패한 Deployment의 Build Logs를 열고 첫 번째 빨간 줄부터 복사하세요. 그 줄이 환경변수인지, Suspense인지, 페이지 데이터 수집인지 확인하면 다음 수정은 훨씬 작아집니다.

참고 출처

다음으로 읽을 기사

같은 흐름으로 이어 읽기 좋은 기사만 추려 보여줍니다.

AI가 만든 코드가 안 돌아갈 때 30초 오류 프롬프트

댓글 0

이 글을 읽은 독자들의 생각을 나눠보세요.

비밀번호(선택)

첫 번째 댓글을 남겨보세요

여러분의 생각이 다른 독자에게 도움이 됩니다.