Next.js 앱에서 모든 페이지를 Static 페이지로 설정하여 풀 라우트 캐시(Full Route Cache)를 최대한 활용하고자 할 때, 페이지를 구성하는 모든 컴포넌트들을 일일이 점검해야 한다.
동적 함수(searchParams, headers, cookies)를 사용하거나, 캐싱되지 않는 데이터 페칭을 수행하는 컴포넌트가 있다면 해당 페이지는 자동으로 Dynamic 페이지로 설정되기 때문이다.
그러나 이러한 작업은 컴포넌트의 수가 많아질수록 복잡하고 시간이 많이 소요될 수 있다.
이를 해결하기 위해 Next.js는 특정 페이지의 동작을 강제로 Static 또는 Dynamic으로 설정하거나, Revalidate 타임을 강제로 지정할 수 있는 라우트 세그먼트 옵션(Route Segment Options)을 제공한다.
이번 포스트에서는 이 옵션을 살펴보고, 가장 자주 사용되는 dynamic 옵션을 중심으로 정리해보려고 한다.
➡️ 라우트 세그먼트 옵션이란?
라우트 세그먼트 옵션은 특정 페이지의 동작을 강제적으로 설정할 수 있는 옵션이다.
이를 통해 다음과 같은 것들을 지정할 수 있다.
- 캐싱 설정
- Revalidate 타임
- 서버 region
- 페이지 렌더링 유형 (Static / Dynamic)
이전 포스트에서 book 페이지를 Static 페이지로 설정할 때 사용했던 dynamicParams 옵션도 이러한 라우트 세그먼트 옵션 중 하나이다.
✅ dynamicParams 옵션
export const dynamicParams = false;dynamicParams: falsegenerateStaticParams에서 반환된 경로 외의 URL 요청은 모두 404 페이지로 리다이렉트
dynamicParams: true(기본값)generateStaticParams외의 경로도 실시간으로 생성
이번에는 또 다른 라우트 세그먼트 옵션인 dynamic 옵션을 자세히 살펴보자.
✨ dynamic 옵션 (페이지 유형 강제 설정)
dynamic 옵션은 특정 페이지를 강제로 Static 또는 Dynamic 페이지로 설정할 수 있는 옵션이다.
기본적으로 Next.js는 다음을 기준으로 페이지 유형을 자동 설정한다.
- 동적 함수 사용 여부
- 데이터 페칭의 캐싱 설정
하지만 dynamic 옵션을 사용하면 이러한 기본 동작을 무시하고 강제로 페이지 유형을 지정할 수 있다.
📌 dynamic 옵션의 값
| 값 | 설명 |
|---|---|
auto | 기본값. 페이지 구성에 따라 자동 설정 |
force-dynamic | 무조건 Dynamic 페이지로 설정 |
force-static | 무조건 Static 페이지로 설정 |
error | Static으로 설정하되, 불가능하면 빌드 오류 발생 |
🧪 실습 (dynamic 옵션 사용)
1️⃣ auto (기본값)
export const dynamic = "auto"; // 기본값 (생략 가능)
export default async function Page({ searchParams }) {
const data = await fetch(`${process.env.API_URL}/data?q=${searchParams.q}`);
return <div>{data}</div>;
}동작 원칙
- 동적 함수 사용 또는
cache: "no-store"사용 시 → Dynamic 페이지 - 그렇지 않다면 → Static 페이지
Next.js의 기본 전략을 그대로 따르는 모드이다.
2️⃣ force-dynamic (무조건 Dynamic 페이지)
export const dynamic = "force-dynamic";
export default async function Page({ searchParams }) {
const data = await fetch(`${process.env.API_URL}/data?q=${searchParams.q}`);
return <div>{data}</div>;
}동작 원칙
- 동적 함수 사용 여부와 관계 없음
- 데이터 캐싱 설정과 관계 없음
- 모든 요청마다 새롭게 페이지 생성
- 항상 실시간 렌더링
즉, 페이지 내부 구현과 상관없이 무조건 Dynamic으로 동작한다.
3️⃣ force-static (무조건 Static 페이지)
export const dynamic = "force-static";
export default async function Page({ searchParams }) {
const data = await fetch(`${process.env.API_URL}/data?q=${searchParams.q}`);
return <div>{data}</div>;
}동작 원칙
searchParams같은 동적 함수는undefined로 처리cache: "no-store"는 자동으로force-cache로 변경- 모든 데이터 페칭은 정적으로 처리
즉, 페이지 내부에서 어떤 동적 로직을 사용했든 간에 강제로 Static 페이지로 동작하도록 변경된다.
⚠️ 주의
검색어 기반으로 데이터를 불러오는 search 페이지 같은 경우,
force-static을 사용하면 검색 기능이 정상 동작하지 않을 수 있다.
4️⃣ error (Static 페이지 설정 + 오류 감지)
export const dynamic = "error";
export default async function Page({ searchParams }) {
const data = await fetch(`${process.env.API_URL}/data?q=${searchParams.q}`);
return <div>{data}</div>;
}동작 원칙
- 기본적으로
force-static처럼 Static으로 강제 설정 - 단, Static으로 렌더링할 수 없는 요소가 있다면 빌드 오류 발생
빌드 오류 예시
Error occurred prerendering page "/search":
Route "/search" with dynamic="error" couldn't be rendered statically
because it used searchParams.q.이 오류 메시지는 다음을 의미한다.
/search페이지를 Static으로 렌더링하려 했지만searchParams.q라는 동적 함수를 사용하고 있어서- Static으로 변환할 수 없다는 것
즉, 왜 Static 페이지로 변경할 수 없는지 명확하게 알려준다.
이 옵션은 Static 페이지로 만들 수 없는 부분을 사전에 발견하고 수정할 때 유용하다.
그래서 force-static보다 안전하게 사용할 수 있는 옵션이다.
⚠️ 주의사항
dynamic 옵션은 강력하지만, 남용하는 것은 권장되지 않는다.
1️⃣ Next.js의 기본 동작 무시
App Router는 페이지를 구성하는 모든 컴포넌트를 분석하여 Static/Dynamic을 자동 판단하는 강력한 메커니즘을 제공한다.
이를 무시하고 강제로 설정하면 다음과 같은 문제가 발생할 수 있다.
- 의도치 않은 기능 동작 오류
- 검색 페이지에서 검색이 동작하지 않는 문제
- 캐싱 전략 왜곡
2️⃣ 실험적 / 임시적 용도로 활용
그럼에도 다음과 같은 상황에서는 유용하게 사용할 수 있다.
- 캐싱 전략을 실험해보고 싶을 때
- 특정 페이지를 반드시 Static 또는 Dynamic으로 강제해야 할 때
- 우선 빠르게 동작을 맞춘 뒤, 이후 구조를 개선할 때
즉,
알고는 있되, 꼭 필요한 경우에만 사용하는 옵션
정도로 이해하는 것이 가장 적절하다.
✅ 정리
dynamic은 페이지 유형을 강제로 설정하는 라우트 세그먼트 옵션auto는 기본값이며 Next.js의 자동 판단을 따른다force-dynamic은 항상 실시간 렌더링force-static은 강제로 정적 처리error는 Static 불가능한 요소를 빌드 단계에서 감지
Next.js의 기본 전략을 충분히 이해한 뒤, 필요할 때만 보조적으로 사용하는 것이 가장 좋은 접근이라고 생각한다.
