DEV WIKI
프론트엔드 · 기술

Next.js 빌드 산출물

Next.js 빌드 산출물은 정적 HTML과 자산 또는 서버 실행에 필요한 메타데이터와 추적 파일이며, 선택한 output 방식과 배포 환경에 따라 사용 경로가 달라집니다.

적용 범위
Next.js 빌드 산출물의 개념·동작을 확인해야 하는 공개 웹 환경문맥: 바이브 코딩
출처
Next.js
출처 확인일
2026-07-22
최종 검토
2026-07-23
오류·수정 제보 (새 창에서 열림)

정상 동작 조건

요약

Next.js에서 output을 export로 설정하면 공개 가능한 정적 파일은 out 디렉터리에 생성됩니다. 서버 실행 배포는 .next의 서버 메타데이터와 추적 파일을 사용하므로, 호스팅 설정이 어떤 산출물을 요구하는지 먼저 확인해야 합니다.

확인 절차

Next.js의 output: "export"는 빌드 시 경로별 HTML을 생성하고 공개용 결과를 out 디렉터리에 만듭니다. 서버 실행 배포는 .next 아래의 서버 메타데이터와 파일 추적 결과를 사용합니다.

AWS Amplify Hosting은 Next.js 14 이상 정적 배포와 서버 실행 배포 모두에 .next를 산출물 기준 경로로 안내하므로, 일반 정적 호스팅의 out 경로와 Amplify의 프레임워크 계약을 구분해야 합니다.

관련 플랫폼

AWS Amplify Hosting

Git 저장소의 변경을 기준으로 웹 애플리케이션을 빌드하고 정적 또는 서버 실행 방식으로 배포하는 AWS 서비스입니다.

GitHub Actions

GitHub 저장소의 이벤트를 기준으로 빌드, 테스트와 배포 작업을 실행하는 자동화 플랫폼입니다.

Vercel

Git 저장소의 프론트엔드와 서버 실행 코드를 빌드하고 배포하는 플랫폼입니다.

관련 오류·증상

Addressing "App Container Deprecated" Error in Next.js | Next.js

Next.js 공식 원문에 표시된 Addressing "App Container Deprecated" Error in Next.js | Next.js 항목의 문구를 확인하는 문서입니다.

CustomerError: Can't find required-server-files.json in build output directory

Next.js 빌드는 성공했지만 AWS Amplify가 배포 산출물에서 서버 실행 메타데이터 파일을 찾지 못해 배포가 중단된 상태입니다.

Addressing "App Container Deprecated" Error in Next.js

Next.js 공식 원문에 표시된 Addressing "App Container Deprecated" Error in Next.js 항목의 문구를 확인하는 문서입니다.

Cannot access `cookies()` or `headers()` in `"use cache"`

Next.js 공식 원문에 표시된 Cannot access `cookies()` or `headers()` in `"use cache"` 항목의 문구를 확인하는 문서입니다.

Cannot access `cookies()` or `headers()` in `"use cache"` | Next.js

Next.js 공식 원문에 표시된 Cannot access `cookies()` or `headers()` in `"use cache"` | Next.js 항목의 문구를 확인하는 문서입니다.

Cannot load project settings

Vercel 공식 원문에 표시된 Cannot load project settings 항목의 문구를 확인하는 문서입니다.

Client components cannot be async functions.

Next.js 공식 원문에 표시된 Client components cannot be async functions. 항목의 문구를 확인하는 문서입니다.

Command not found in vercel dev

Vercel 공식 원문에 표시된 Command not found in vercel dev 항목의 문구를 확인하는 문서입니다.

Docs Errors Addressing "App Container Deprecated" Error in Next.js

Next.js 공식 원문에 표시된 Docs Errors Addressing "App Container Deprecated" Error in Next.js 항목의 문구를 확인하는 문서입니다.

Docs Errors Cannot access `cookies()` or `headers()` in `"use cache"`

Next.js 공식 원문에 표시된 Docs Errors Cannot access `cookies()` or `headers()` in `"use cache"` 항목의 문구를 확인하는 문서입니다.

Docs Errors Failed to find Server Action

Next.js 공식 원문에 표시된 Docs Errors Failed to find Server Action 항목의 문구를 확인하는 문서입니다.

Docs Errors Missing Suspense boundary with useSearchParams

Next.js 공식 원문에 표시된 Docs Errors Missing Suspense boundary with useSearchParams 항목의 문구를 확인하는 문서입니다.

Docs Errors Module Not Found

Next.js 공식 원문에 표시된 Docs Errors Module Not Found 항목의 문구를 확인하는 문서입니다.

Docs Errors `next/dynamic` has deprecated loading multiple modules at once

Next.js 공식 원문에 표시된 Docs Errors `next/dynamic` has deprecated loading multiple modules at once 항목의 문구를 확인하는 문서입니다.

Docs Errors `url` is deprecated

Next.js 공식 원문에 표시된 Docs Errors `url` is deprecated 항목의 문구를 확인하는 문서입니다.

Failed to find Server Action

현재 빌드에서 요청된 Server Action을 찾지 못했다는 Next.js 오류 메시지입니다.

Failed to find Server Action | Next.js

Next.js 공식 원문에 표시된 Failed to find Server Action | Next.js 항목의 문구를 확인하는 문서입니다.

Failed to install builder dependencies

Vercel 공식 원문에 표시된 Failed to install builder dependencies 항목의 문구를 확인하는 문서입니다.

FALLBACK_BODY_TOO_LARGE

ISR 응답이 20 MB를 초과하면 프로덕션에서 페이지가 렌더링되지 않으며 FALLBACK_BODY_TOO_LARGE 오류가 발생합니다.

GitHub app installation not found

Vercel 공식 원문에 표시된 GitHub app installation not found 항목의 문구를 확인하는 문서입니다.

Invalid Edge Config connection string

Vercel 공식 원문에 표시된 Invalid Edge Config connection string 항목의 문구를 확인하는 문서입니다.

Invalid route destination segment

Vercel 공식 원문에 표시된 Invalid route destination segment 항목의 문구를 확인하는 문서입니다.

Invalid route source pattern

Vercel 공식 원문에 표시된 Invalid route source pattern 항목의 문구를 확인하는 문서입니다.

Missing build script

Vercel 공식 원문에 표시된 Missing build script 항목의 문구를 확인하는 문서입니다.

Missing public directory

Vercel 공식 원문에 표시된 Missing public directory 항목의 문구를 확인하는 문서입니다.

Missing Suspense boundary with useSearchParams

Next.js 공식 원문에 표시된 Missing Suspense boundary with useSearchParams 항목의 문구를 확인하는 문서입니다.

Missing Suspense boundary with useSearchParams | Next.js

Next.js 공식 원문에 표시된 Missing Suspense boundary with useSearchParams | Next.js 항목의 문구를 확인하는 문서입니다.

Module Not Found | Next.js

Next.js 공식 원문에 표시된 Module Not Found | Next.js 항목의 문구를 확인하는 문서입니다.

`next/dynamic` has deprecated loading multiple modules at once

Next.js 공식 원문에 표시된 `next/dynamic` has deprecated loading multiple modules at once 항목의 문구를 확인하는 문서입니다.

`next/dynamic` has deprecated loading multiple modules at once | Next.js

Next.js 공식 원문에 표시된 `next/dynamic` has deprecated loading multiple modules at once | Next.js 항목의 문구를 확인하는 문서입니다.

Dynamic server usage: Route used cookies() or headers()

Dynamic server usage: Route used cookies() or headers() 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.

Next.js encountered uncached data in generateMetadata()

Cache Components가 활성화된 Next.js에서 generateMetadata()가 캐시되지 않은 데이터를 읽어 메타데이터가 프리렌더링을 막는 오류입니다.

Next.js encountered URL data outside of Suspense

Client-side navigation 중 Server Component가 <Suspense> 경계 밖에서 params 또는 searchParams를 읽을 때 표시되는 Next.js 오류입니다.

Invariant: attempted to hard navigate to the same URL

Invariant: attempted to hard navigate to the same URL 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.

Invalid src prop: hostname is not configured under images in your next.config.js

Next.js `Image`의 외부 이미지 호스트가 `images.remotePatterns`에 정확히 등록되지 않았는지 확인합니다.

The module you're trying to import has a different casing

파일명과 import 경로의 대소문자가 다르면 대소문자를 구분하는 환경에서 빌드가 실패할 수 있습니다.

NEXT_NOT_FOUND

NEXT_NOT_FOUND 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.

NEXT_REDIRECT

NEXT_REDIRECT 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.

No HTML link for pages

Next.js 내부 경로 이동에 일반 `<a>`를 사용해 전체 페이지 새로고침이 발생하는지 확인합니다.

Page changed from / to /_error

Page changed from / to /_error 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.

Next.js encountered the unstable value Math.random() while prerendering

prerendering 중 Server Component가 <Suspense> 밖에서 Math.random()을 호출하면 발생하는 Next.js 오류입니다.

`url` is deprecated

Next.js 공식 원문에 표시된 `url` is deprecated 항목의 문구를 확인하는 문서입니다.

Production deployment cannot be redeployed

Vercel 공식 원문에 표시된 Production deployment cannot be redeployed 항목의 문구를 확인하는 문서입니다.

return NextResponse.json({ message: 'Auth required' }, { status: 401 })

Next.js 공식 원문에 표시된 return NextResponse.json({ message: 'Auth required' }, { status: 401 }) 항목의 문구를 확인하는 문서입니다.

height={500}

Next.js 공식 원문에 표시된 height={500} 항목의 문구를 확인하는 문서입니다.

SSL certificate deletion denied

Vercel 공식 원문에 표시된 SSL certificate deletion denied 항목의 문구를 확인하는 문서입니다.

`url` is deprecated | Next.js

Next.js 공식 원문에 표시된 `url` is deprecated | Next.js 항목의 문구를 확인하는 문서입니다.

Yarn dynamic require of "util" is not supported

Vercel 공식 원문에 표시된 Yarn dynamic require of "util" is not supported 항목의 문구를 확인하는 문서입니다.

참고 자료

Next.js · 공식 자료 (새 창에서 열림)

확인 범위: static-export-configuration, out-directory · 확인일: 2026-07-22

Next.js · 공식 자료 (새 창에서 열림)

확인 범위: output-file-tracing, server-build-files · 확인일: 2026-07-22