Next.js App Router: 'Dynamic server usage' 정적 빌드 에러 원인과 export const dynamic 지시어 해결법

Next.js App Router Dynamic server usage 에러 원인 및 static dynamic 페이지 구분법
3초 요약: 이렇게 고치세요
  • 원인: Next.js는 기본적으로 페이지를 정적으로 빌드하려 하는데, cookies()·headers()·searchParams처럼 요청 시점에만 알 수 있는 값을 빌드 타임에 읽으려 해서 발생
  • 해결: 페이지 전체가 동적이면 export const dynamic = 'force-dynamic' / 클라이언트 컴포넌트의 useSearchParams는 <Suspense>로 감싸기
  • 주의: 단순 UI 인터랙션에 쿼리 스트링을 쓰고 있었다면, 애초에 useState로 바꿔서 빌드 최적화를 방해하지 않게 재설계하는 것도 방법
export const dynamic = 'force-dynamic'; // 이 라우트는 매 요청마다 렌더링
↓ 왜 이런 에러가 나는지 원리 보기

Next.js App Router로 배포 빌드를 실행하다 'Dynamic server usage' 에러를 만나는 경우가 있습니다. 로컬 개발 환경에서는 문제없이 동작하던 페이지가 빌드 단계에서만 실패하는 이유는 요청 시점에만 알 수 있는 값(쿠키, 헤더, 쿼리 등)을 정적 빌드 시점에 미리 읽으려 하기 때문입니다. 원인과 해결 코드, 정적/동적 페이지를 구분하는 기준을 함께 정리합니다.

'Dynamic server usage' 에러의 근본적인 원인

Next.js App Router는 기본적으로 특별한 동적 기능이 감지되지 않으면 모든 페이지를 정적 페이지(Static Route)로 빌드하려고 시도합니다. 정적으로 빌드된 페이지는 서버 부하를 줄이고 CDN을 통해 초고속으로 전송할 수 있기 때문입니다. 하지만 정적 빌드가 진행되는 도중(Build Time), 코드 내부에서 동적 API 또는 함수를 사용하면 빌드 타임에 값을 결정할 수 없으므로 Next.js가 강제로 빌드를 차단하며 Dynamic server usage 에러를 발생시킵니다. 로그인 여부에 따라 다른 내용을 보여주려고 쿠키를 읽는 페이지에서 이 에러를 가장 자주 마주치게 됩니다.

이 에러를 유발하는 대표적인 동적 함수는 네 가지입니다. HTTP 헤더 정보에 접근하는 headers(), 쿠키를 읽고 쓰는 cookies(), 클라이언트에서 쿼리를 읽는 useSearchParams(), 그리고 서버 컴포넌트에서 쿼리에 접근하는 searchParams props가 여기에 해당합니다. 이 함수들은 모두 요청이 들어오는 시점에만 값을 알 수 있기 때문에, 빌드 시점에 미리 정적 HTML을 만들려는 Next.js의 기본 동작과 충돌합니다.

에러를 해결하는 3가지 실전 솔루션

솔루션 1: 해당 서버 컴포넌트를 동적 렌더링(Dynamic Rendering)으로 강제 전환

에러가 발생한 페이지나 레이아웃 파일 최상단에 Route Segment Config인 dynamic 옵션을 선언하여 Next.js 엔진에게 "이 페이지는 빌드 시점이 아니라, 매 요청마다 서버에서 실시간으로 렌더링해야 해"라고 알려주는 방법입니다. 

// app/dashboard/page.tsx
import { cookies } from 'next/headers';

// Route Segment Config 추가: 페이지를 Dynamic 렌더링으로 강제 지정
export const dynamic = 'force-dynamic';

export default async function DashboardPage() {
  const cookieStore = await cookies();
  const theme = cookieStore.get('theme')?.value || 'light';

  return (
    <div>
      <h2>대시보드</h2>
      <p>현재 설정된 테마: {theme}</p>
    </div>
  );
}

솔루션 2: 클라이언트 컴포넌트 내 useSearchParams를 <Suspense>로 감싸기

클라이언트 컴포넌트("use client") 내부에서 URL 파라미터를 읽기 위해 useSearchParams()를 호출할 때 발생하는 정적 빌드 에러는, 해당 호출부를 <Suspense> 경계로 감싸서 해결합니다. 

// app/search/SearchBox.tsx
"use client";

import { useSearchParams } from 'next/navigation';
import { Suspense } from 'react';

// 1. searchParams를 사용하는 컴포넌트 분리
function SearchInput() {
  const searchParams = useSearchParams();
  const query = searchParams.get('q') || '';
  return <div>검색어: {query}</div>;
}

// 2. 부모 컴포넌트에서 Suspense로 래핑하여 Export
export default function SearchBox() {
  return (
    <Suspense fallback={<div>검색창 로딩 중...</div>}>
      <SearchInput />
    </Suspense>
  );
}

솔루션 3: 동적 데이터가 불필요한 영역은 렌더링 분리

단순히 특정 탭 전환이나 UI 인터랙션을 위해 쿼리 스트링을 남발하고 있었다면, searchParams 대신 React State(useState)나 클라이언트 사이드 Router를 활용하여 해당 컴포넌트가 빌드 최적화 흐름을 방해하지 않도록 구조를 재설계해야 합니다.

정적으로 배포하려던 소개 페이지 하나에 로그인 여부만 확인하려고 cookies()를 가볍게 가져다 썼다가, 페이지 전체가 정적 빌드에서 빠지는 걸 뒤늦게 알아챈 적이 있습니다. 로그인 배지 하나 때문에 페이지 전체가 매 요청마다 서버 렌더링되고 있었던 셈이라, 그 부분만 클라이언트 컴포넌트로 떼어내고 나서야 나머지는 다시 정적으로 빌드됐습니다.

요약: Next.js Static / Dynamic 구분 기준

Next.js App Router가 최적화를 위해 페이지를 분류하는 기준입니다.

구분 항목 정적 렌더링 (Static Rendering) 동적 렌더링 (Dynamic Rendering)
렌더링 시점 빌드 시점(Build Time) 또는 백그라운드 재검증 시 매 요청 시점(Request Time) 실시간 서버 연산
트리거 조건 기본 설정 상태, 캐싱된 데이터 요청 headers(), cookies(), searchParams 사용 시
추천 대상 공통 소개 페이지, 일반 블로그 포스트 개인 대시보드, 마이페이지, 세션 체크 영역
공식 참고 레퍼런스

Next.js 공식 문서의 렌더링 최적화 규칙과 빌드 옵션 Segment 명세는 아래 문서에서 확인할 수 있습니다.

호마다의 웹개발 팁

정적/동적 렌더링 중 어느 쪽이 맞을지 애매하다면, 페이지 전체보다 일부 컴포넌트만 동적으로 분리하는 것도 방법입니다. 캐싱과 렌더링 전략 자체가 낯설다면 [호마다의 IT 개발 입문 블로그] 도 같이 보셔도 좋습니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

TypeScript: Unknown vs Any 타입 차이점과 안전한 타입 가드(Type Guard)

이미지
3초 요약: 이렇게 고치세요 원인: any 는 타입 검사 자체를 포기하는 선언이라, 잘못된 속성 접근이 컴파일 시점엔 통과했다가 런타임에 터짐 해결: 외부 API 응답처럼 타입을 확신할 수 없는 데이터는 unknown 으로 받고, data is T 형태의 타입 가드로 검증한 뒤에만 사용 주의: 타입 가드 내부에서 as Record<string, unknown> 같은 임시 캐스팅으로 속성을 하나씩 검사하는 절차를 생략하면 unknown 을 쓰는 의미가 없어짐 function isUserProfile(data: unknown): data is UserProfile { ... } ↓ 왜 any가 위험한지 원리 보기 실무에서 대규모 TypeScript 프로젝트를 마이그레이션하거나, 외부 API 또는 레거시 라이브러리를 통합하다 보면 필연적으로 "타입을 확신할 수 없는 데이터"를 다루게 됩니다. 이때 많은 개발자들이 급한 마음에 가장 손쉬운 탈출구인 any 를 사용하곤 합니다. 하지만 이는 TypeScript의 가장 큰 무기인 타입 안정성을 스스로 내려놓는 행위이자, 미래의 나에게 런타임 에러라는 시한폭탄을 던지는 것과 같습니다. any 가 왜 위험한지, TypeScript 3.0에서 도입된 unknown 이 이를 어떻게 막아주는지, 그리고 실무에서 바로 써먹을 수 있는 사용자 정의 타입 가드(User-Defined Type Guards) 작성 패턴을 정리합니다. any의 위험성과 unknown의 등장 프로덕션 환경에서 발생한 실제 에러 로그를 분석해 보면, 꽤 많은 비율이 TypeError: Cannot read properties of undefined 에서 시작합니다. 그리고 그 이면에는 높은 확률로 any 타입이 자리 잡고 있죠. any: 타입...
자세한 내용 보기

Next.js 하이드레이션 오류 원인과 해결법 완벽 정리

이미지
3초 요약: 이렇게 고치세요 원인: 서버가 렌더링한 초기 HTML과 브라우저가 처음 그린 HTML 구조가 서로 달라서 발생 — React는 둘이 같을 거라 믿고 결합을 시도하다가 실패함 해결: 잘못된 태그 중첩이면 마크업 수정 / window · localStorage 참조면 useEffect 로 이동 / 시간·랜덤값처럼 매번 달라지는 값이면 ssr: false 로 분리 주의: suppressHydrationWarning 은 경고를 숨길 뿐 원인을 고치는 게 아니라서, 불가피한 텍스트 불일치(타임스탬프 등)에만 제한적으로 써야 함 const [isMounted, setIsMounted] = useState(false); useEffect(() => setIsMounted(true), []); if (!isMounted) return null; // 서버와 첫 클라이언트 렌더는 항상 동일하게 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js를 쓰다 보면 콘솔에 "Hydration failed because the initial UI does not match..."라는 붉은 에러가 뜰 때가 있습니다. 빌드는 멀쩡히 끝났는데 화면이 그려진 직후에 갑자기 나는 에러라서 처음 보면 당황스럽습니다. 원인은 대부분 서버와 클라이언트가 그린 첫 화면이 미묘하게 다르기 때문이고, 패턴이 정해져 있어서 하나씩 짚어보면 금방 잡힙니다. 하이드레이션(Hydration), 정확히 어떤 과정인가 Next.js의 핵심 기능은 서버 사이드 렌더링(SSR)입니다. 서버는 먼저 사용자에게 정적인 HTML 뼈대를 빠르게 그려서 브라우저에 내려보내 줍니다. 그 후, 브라우저(클라이언트)가 이 정적인 HTML 위에 React의 자바스크립트 코드와 이벤트 리스너를 결합하여 ...
자세한 내용 보기

Next.js App Router에서 getServerSideProps 대체 및 데이터 페칭법

이미지
3초 요약: 이렇게 고치세요 원인: App Router는 서버 컴포넌트에서 직접 async/await를 쓸 수 있어 getServerSideProps / getStaticProps 가 아예 없어짐 해결: 빌드 시 캐싱(SSG) → 기본 fetch / 매 요청 최신화(SSR) → { cache: 'no-store' } / 주기 갱신(ISR) → { next: { revalidate: N } } 주의: getServerSideProps 안에 있던 인증 체크 로직은 이제 컴포넌트 함수 내부나 미들웨어로 옮겨야 함 const res = await fetch(url, { cache: 'no-store' }); // SSR과 동일하게 매번 재요청 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js 13 이상에서 App Router가 표준이 되면서, Pages Router에서 쓰던 getServerSideProps 와 getStaticProps 가 더 이상 동작하지 않습니다. 두 함수가 사라진 설계적 이유와, 이를 대체하는 데이터 패칭 방식을 정리했습니다. 왜 getServerSideProps와 getStaticProps가 사라졌을까 과거 Next.js는 페이지 컴포넌트 내부에서만 특정 정적 함수( getServerSideProps 등)를 실행하여 데이터를 미리 받아온 뒤, 이를 컴포넌트의 props 로 넘겨주는 복잡한 직렬화 구조를 가졌습니다. 이로 인해 컴포넌트 간 깊이가 깊어지면 'Props Drilling(프로퍼티 대물림)'이 심해져 코드 관리가 몹시 까다로웠습니다. App Router 환경에서는 서버 컴포넌트(Server Component)가 표준이 됨에 따라 컴포넌트 내에서 직접 비동기 함수(async/await)를 작성할 수 있게 되었습...
자세한 내용 보기