본문 바로가기
Q&A해결2026년 4월 21일1분 읽기

Next.js 16에서 dynamic = 'force-static'이 무시되고 매번 재빌드됩니다

주
주니어풀스택
조회 732댓글 1

Next.js 16 App Router로 정적 페이지를 만들고 있습니다. 페이지 상단에 export const dynamic = 'force-static'를 명시했는데도 빌드 로그에 매번 (Dynamic) 으로 표시되고 SSR로 동작합니다.

fetch는 { cache: 'force-cache' }로 명시했고, cookies()·headers()는 호출하지 않습니다. 무엇이 페이지를 동적으로 만드는지 모르겠습니다.

댓글 1

김김영삼7개월 전

Next.js 16에서 정적/동적을 결정하는 규칙이 15와 미묘하게 달라졌습니다. 강제 정적이 무시되는 원인은 거의 항상 다음 중 하나입니다.

1) 자식 컴포넌트 어딘가에서 동적 API 호출

본인 페이지가 아니라 import한 컴포넌트 트리에서 cookies()·headers()·searchParams·noStore()가 한 번이라도 호출되면 페이지 전체가 동적으로 떨어집니다.

# 빌드 로그에서 정확한 원인 확인
NEXT_DEBUG=1 npm run build 2>&1 | grep -A 3 "Dynamic API"

16부터는 어느 컴포넌트에서 어떤 API를 호출했는지 정확한 위치를 출력합니다.

2) fetch 호출이 cache 옵션을 못 받는 케이스

16에서 fetch의 기본 캐시 정책이 변경됐습니다. 명시적으로 옵션을 줘야 합니다.

// 명시 안 하면 'no-store'로 떨어짐 (16부터)
const data = await fetch(url, {
cache: 'force-cache',
next: { revalidate: 3600 }
})

3) 페이지 자체보다 layout이 동적일 때

page.tsx가 force-static이라도 상위 layout.tsx에서 동적 API 호출 시 그 하위 전체가 동적 렌더링됩니다. layout 트리도 함께 점검해야 합니다.

실무 진단 순서:

  1. NEXT_DEBUG=1 next build 로 정확한 동적 사유 확인
  2. page → layout → 자식 컴포넌트 순서로 동적 API 사용 추적
  3. 의심되는 컴포넌트에 임시로 'use cache'를 붙여 격리 테스트
  4. generateStaticParams 누락 여부 확인 (dynamic route)

새로운 'use cache' 디렉티브 (16에서 안정화)

// 컴포넌트 단위 캐시
async function ProductList() {
'use cache'
const products = await db.product.findMany()
return ...
}

이 디렉티브가 붙은 함수는 자체적으로 캐시되며, 호출자에게 동적 사유를 전파하지 않습니다.

주의:

  • force-static는 "정적이어야 한다"는 강제이지 "정적으로 만든다"는 뜻이 아닙니다 — 동적 API를 만나면 빌드 에러가 납니다 (16부터)
  • ISR 효과를 원하면 revalidate를 함께 명시하세요
  • Middleware에서 NextResponse.next()의 헤더 변경도 페이지를 동적으로 만들 수 있습니다

대부분 사례는 "내가 안 썼는데 라이브러리가 썼다" 입니다. 인증 라이브러리·analytics·feature flag 라이브러리가 cookies/headers를 호출하는지 점검하세요.

Ctrl+Enter로 등록