Next.js 업그레이드 프로토콜은(는) 무엇을 하나요?
Next.js 버전 업그레이드(예: v14 → v15)를 위한 자동화 및 수동 마이그레이션 단계입니다.
우선순위: P1 (운영)
구현 지침
- 업그레이드 감지: 항상 **
package.json**에서next,react,react-dom버전을 확인합니다. - 계획: 주요 버전 점프(v13에서 v15)의 경우 증분 업그레이드(v13 -> v14, 그 다음 v14 -> v15)를 수행합니다. 공식 Next.js 마이그레이션 가이드를 따릅니다.
- 자동화된 Codemod: **
npx @next/codemod@latest <transform> <path>**를 사용하여 구문 마이그레이션을 자동화합니다. - 주요 변경 사항(v15):
next-async-request-api변환에 응답하여params,searchParams,cookies(), **headers()**가 await되도록 합니다. - React 버전 일치: **
react**와 **react-dom**을 Next.js의 피어 의존성에 맞게 업그레이드합니다(예: Next.js 15의 경우 React 19). - 검증: 각 증분 단계 후 **
next dev**와 **next build**를 실행합니다. 콘솔 오류에서 하이드레이션 경고를 확인합니다. - 보고: 모든 codemod 실패 또는 필요한 수동 수정 사항을 팀에 보고합니다.
3. 의존성 업데이트
Next.js 및 피어 의존성을 동기화하여 업그레이드합니다:
# npm 사용
npm install next@latest react@latest react-dom@latest
# Types 업데이트
npm install --save-dev @types/react@latest @types/react-dom@latest
4. 수동 검증 규칙
- 비동기 컨텍스트:
cookies(),headers()및 라우트params의 모든 사용이 이제 await되었는지 확인합니다. - 메타데이터:
generateMetadata타입이 새로운 비동기params시그니처와 일치하는지 확인합니다. - 캐싱: v15 이상에서
fetch는 기본적으로{ cache: 'no-store' }입니다. 이전 동작이 필요하면 명시적으로{ cache: 'force-cache' }를 설정합니다.
5. 빌드 테스트
- codemod 및 패키지 업데이트 직후
npm run build를 실행합니다. --turbo사용 시 "Hydration failed" 또는 "Turbopack" 호환성 오류가 있는지 확인합니다.
안티 패턴
- 주요 버전 건너뛰기 금지: 한 번에 하나의 주요 버전씩 업그레이드합니다(13→14, 그 다음 14→15).
- 수동 주요 변경 사항 수정 금지: 항상 먼저
npx @next/codemod@latest변환을 실행합니다. - 업그레이드 후 캐싱 동작 가정 금지: v15는 기본적으로
no-store입니다. 모든fetch호출을 감사합니다. - Pages Router에서 비동기 페이지 함수 금지:
export default async function Page()는 치명적입니다.