AWS Amplify에서 Next.js 배포가 완료되지 않아요
AWS Amplify의 Next.js 빌드가 성공한 뒤 required-server-files.json 누락 오류로 배포되지 않을 때 확인 문서로 이동합니다.
#빌드 산출물
빌드 결과 파일과 배포 대상 경로에 관련된 문서입니다.
문제 해결 가이드
3개 문서Next.js 또는 Node.js 빌드 로그에 모듈 오류가 보여요
Next.js 또는 Node.js 빌드·실행 로그에 대소문자 불일치, ERR_MODULE_NOT_FOUND, ERR_INVALID_URL이 표시될 때 원문 메시지로 확인 문서를 고릅니다.
Vite 환경 변수가 undefined로 보여요
Vite에서 import.meta.env 값이 undefined이거나 비어 있을 때 변수 접두사·실행 mode·재빌드 여부를 확인합니다.
오류·증상
15개 문서CustomerError: Can't find required-server-files.json in build output directory
Next.js 빌드는 성공했지만 AWS Amplify가 배포 산출물에서 서버 실행 메타데이터 파일을 찾지 못해 배포가 중단된 상태입니다.
Dynamic server usage: Route used cookies() or headers()
Dynamic server usage: Route used cookies() or headers() 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.
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 항목의 문구를 확인하는 문서입니다.
import.meta.env.VITE_* is undefined
Vite 애플리케이션에서 import.meta.env의 환경 변수가 undefined로 보일 때 변수 이름·모드·빌드 시점을 확인합니다.
Missing Env Value
Next.js 공식 원문에 표시된 Missing Env Value 항목의 문구를 확인하는 문서입니다.
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 항목의 문구를 확인하는 문서입니다.
NEXT_NOT_FOUND
NEXT_NOT_FOUND 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.
Next.js encountered the unstable value Math.random() while prerendering
prerendering 중 Server Component가 <Suspense> 밖에서 Math.random()을 호출하면 발생하는 Next.js 오류입니다.
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 오류입니다.
No Duplicate Head
pages/_document.js의 하나의 custom document에서 <Head />가 둘 이상 사용된 상태입니다.
return NextResponse.json({ message: 'Auth required' }, { status: 401 })
Next.js 공식 원문에 표시된 return NextResponse.json({ message: 'Auth required' }, { status: 401 }) 항목의 문구를 확인하는 문서입니다.
The module you're trying to import has a different casing
파일명과 import 경로의 대소문자가 다르면 대소문자를 구분하는 환경에서 빌드가 실패할 수 있습니다.
체크리스트
1개 문서Amplify Next.js 배포 산출물 확인
AWS Amplify에 Next.js 애플리케이션을 다시 배포하기 전에 출력 방식과 모노리포 경로 설정을 확인하는 체크리스트입니다.
플랫폼
2개 문서GitHub Actions
GitHub 저장소의 이벤트를 기준으로 빌드, 테스트와 배포 작업을 실행하는 자동화 플랫폼입니다.
Vercel
Git 저장소의 프론트엔드와 서버 실행 코드를 빌드하고 배포하는 플랫폼입니다.
기술
3개 문서Docker
애플리케이션과 실행 환경을 이미지와 컨테이너로 패키징하고 실행하는 도구입니다.
Next.js 빌드 산출물
Next.js가 빌드 과정에서 생성하는 정적 파일과 서버 실행용 메타데이터를 배포 방식에 맞게 구분한 결과물입니다.
Vite
개발 서버와 프로덕션 번들 생성을 제공하는 프론트엔드 빌드 도구입니다.