Next.js 16 마이그레이션 가이드 — 15에서 변경된 8가지와 dynamic 처리

핵심 요약

Next.js 16은 15와 호환을 깨는 변경이 적지 않다. 가장 큰 영향은 (1) dynamic API 검출 강화, (2) fetch 기본 캐싱 변경, (3) use cache 디렉티브 도입. 단순 버전 업그레이드만으로 동작이 달라질 수 있어 단계적 전환 필수.

• 출시: 2025-10 (Vercel)
• 변경 규모: 호환성 깨는 변경 8개, 신규 기능 12개
• 마이그레이션 도구: npx @next/codemod@latest upgrade
• 지원: React 19 필수, Node 20+ 필수

변경점 1 — dynamic API 검출 강화

15까지는 일부 컴포넌트가 cookies/headers를 호출해도 페이지가 부분 정적 렌더 가능했지만, 16에서는 정확한 위치를 컴파일 시점에 추적해 빌드 에러 또는 동적 마킹이 명확해진다.

# 빌드 시 정확한 dynamic 사유 출력
NEXT_DEBUG=1 npm run build 2>&1 | grep -A 3 "Dynamic API"

변경점 2 — fetch 기본 캐싱 = no-store

15까지는 fetch가 기본 force-cache. 16부터는 명시 안 하면 no-store. 캐시 활용하려면 명시:

const data = await fetch(url, {
  cache: 'force-cache',
  next: { revalidate: 3600 }
})

변경점 3 — use cache 디렉티브

함수 단위 캐싱 표준화. unstable_cache 대체.

async function ProductList() {
  'use cache'
  const products = await db.product.findMany()
  return ...
}

변경점 4 — Server Actions 호출 형식

16에서 Server Action은 명시적 타입 추론 강화. 'use server' 디렉티브 위치 검증 엄격해짐.

변경점 5 — Image 컴포넌트

quality 기본값 75 유지, 단 sizes 미명시 시 빌드 경고 발생. fill+sizes 조합이 사실상 필수.

변경점 6 — searchParams가 Promise

// 15까지
function Page({ searchParams }: { searchParams: { q: string } })

// 16부터
async function Page({ searchParams }: { searchParams: Promise<{ q: string }> }) {
  const { q } = await searchParams
}

변경점 7 — params도 Promise

동적 route param도 동일하게 Promise. await params 필수.

변경점 8 — Build Adapters API

호스팅 제공자가 자체 빌드 어댑터 작성 가능. Cloudflare·Netlify·AWS Amplify 등 자체 어댑터 발표.

마이그레이션 단계

1. Codemod 자동 변환 — npx @next/codemod@latest upgrade
2. 의존성 점검 — React 19+, Node 20+, TypeScript 5.4+
3. 빌드 디버그 — NEXT_DEBUG=1로 dynamic 사유 추적
4. fetch 호출 일괄 점검 — 캐시 옵션 명시
5. params/searchParams — Promise 적용
6. 점진적 use cache 도입 — 자주 호출되는 함수부터

실측 — 마이그레이션 후 효과

자주 묻는 질문

codemod가 모든 걸 자동으로 처리하나?

아니다. 90% 정도는 자동, 나머지 10%는 수동 (특히 Server Component 내 Context 사용 패턴).

15에서 16으로 단번에 가야 하나?

가능. 14→15→16 점프도 codemod가 처리. 단 큰 변경이 누적되므로 스테이징에서 충분히 검증.

App Router가 아닌 Pages Router는?

Pages Router는 16에서도 지원. 단 신규 기능은 App Router 전용. 점진적 전환 권장.