🧠 Next.js 심화 1장: Caching Deep Dive — 4중 캐시 아키텍처 파헤치기

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 1단계: Request Memoization (수명 1초의 함수 캐시) 🟢
• 🌱 2단계: Data Cache (DB 쿼리의 영구 보존) 🟡
• 🛡️ 3단계: Full Route Cache (완성된 HTML의 화석화) 🔴
• 🚥 4단계: Router Cache (클라이언트 탭 메모리) 🟣
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분 (전체) / 핵심 파트만: 10분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(신입): "어? 관리자 페이지에서 공지사항 제목을 '긴급 패치 2.0'으로 수정하고 DB 저장(UPDATE)까지 성공했어요. 그런데 메인 화면으로 돌아가서 새로고침(F5)을 해도 예전 제목인 '긴급 패치 1.0'만 계속 떠요. 제가 캐시 갱신 경로를 놓친 걸까요?"
• 영호(리드): "좋은 의심이에요. Next.js는 버전과 설정에 따라 Data Cache, Full Route Cache, Router Cache가 서로 다른 수명으로 남습니다. 저장 로직이 성공해도 관련 캐시를 어떻게 무효화할지 연결하지 않으면 화면은 낡은 결과를 다시 받을 수 있어요."

🗺️ 이 문서의 흐름
Next.js 캐시의 악명 → 4가지 캐시 계층 완벽 분해 → 각 캐시의 초기화(Invalidate) 원리

🎯 이 문서를 다 읽으면 할 수 있는 것

• 내 코드가 어느 계층의 캐시에 묶여서 데이터를 갱신하지 못하고 있는지, "범인 레이어"를 정확하게 지목할 수 있다.
• Vercel 빌드 시 화면 옆에 뜨는 ○ (Static) 과 ƒ (Dynamic) 의 진짜 내부 동작 원리를 설명할 수 있다.

🤔 왜 알아야 하는가

Next.js App Router의 캐시는 버전과 설정에 따라 기본값이 달라졌어. Next 13/14의 이전 모델에서는 fetch와 정적 라우트가 적극적으로 캐시되었고, Next 15+ 이후에는 기본 fetch가 더 보수적으로 동작하며 cacheComponents: true와 'use cache'처럼 명시적인 선언이 중요해졌지.

그래도 핵심 질문은 그대로야. "이 결과를 언제까지 재사용해도 되는가?" 서버 렌더링(SSR) 위주의 웹은 구조적으로 비싸고, 사용자가 1만 명 들어올 때마다 서버가 1만 개의 HTML 공장을 돌리고 DB를 찌르면 비용과 지연이 커지기 때문이야.

하지만 이걸 완벽하게 이해하지 못하면, 영철이처럼 하루 종일 DB 값이 업데이트 안 되는 늪에서 헤매게 돼.
Next.js는 단일 캐시가 아니라 4개의 캐시 계층(Layer)이 마치 양파 껍질처럼 서로를 둘러싸고 있어. 이 4중 쉴드의 멘탈 모델을 머릿속에 그리는 것이 시니어의 가장 위대한 여정의 시작이야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면? (영수네 햄버거 공장의 4중 스피드 시스템)

손님이 "빅맥 하나!" 주문했을 때 공장 내부에서 일어나는 4단계 최적화:

• 1단계 (Router Cache - 내 스마트폰): "어? 나 방금 빅맥 시켰었는데. 배달 안 시키고 내 주머니에서 아까 시킨 빅맥(사진) 꺼내서 봐야징~" (새로고침 전까지 유지)
• 2단계 (Request Memoization - 한 번 배달할 때): "이번엔 진짜 배달 시켰어. 주방장이 고기 굽는데, 내가 고기(fetch) 2번 갖다 달라고 해도 주방장이 무시하고 한 번 구운 고기를 반반 나눠줌!"
• 3단계 (Data Cache - 주방의 영구 냉동고): "어제 들어온 특제 소스(DB 결과)를 영구 냉동고에 보관해뒀어. 내일 손님이 와도, 모레 와도 안 버리고 똑같은 소스를 계속 뿌릴 거야!"
• 4단계 (Full Route Cache - 진열장의 모형 햄버거): "아예 소스, 빵, 야채를 다 조립해둔 완제품 빅맥(HTML 파일 자체)을 가게 앞에 유리장식으로 걸어뒀어! 주문 오면 주방장 안 깨우고 저 모형 바로 던져줌 ㅋㅋㅋ"

🧩 1단계: Request Memoization (수명 1초의 함수 캐시) 🟢

이건 이미 guide 6장에서 마스터한 내용이야. 가볍게 짚고 넘어가자.

특징 요약

• 목적: 깊고 복잡한 컴포넌트 트리 하위에서 데이터를 똑같이 또 호출할 때, 네크워크 부하 방지 (Props Drilling 회피)
• 대상: 오로지 GET 방식의 fetch() 함수. (그리고 수동으로 래핑한 React.cache)
• 수명: 브라우저가 화면을 갱신하는 딱 그 "한 번의 렌더링 턴(Lifecycle)" 동안만 살아있음.
• 초기화(Revalidation) 방법: 없음. 컴포넌트 렌더링이 딱 끝나는 1초 뒤에 메모리에서 연기처럼 사라짐.

🌱 2단계: Data Cache (DB 쿼리의 영구 보존) 🟡

여기서부터 영철이가 실제로 디버깅해야 할 범위가 넓어져. 저장은 됐는데 화면이 갱신되지 않을 때 가장 먼저 의심할 계층이지.

특징

• 목적: 같은 URL과 파라미터로 들어오는 외부 API 응답이나 캐시 가능한 계산 결과를 서버 캐시에 저장해 재사용함.
• 대상: fetch() 응답값 그 자체.
• 수명: cache: 'force-cache', next.revalidate, cacheLife, 태그 무효화 같은 정책에 따라 달라짐.

❌ 영철이의 함정 (기본 캐시 늪)

// app/notice/page.tsx
export default async function NoticeInfo() {
  // Next 13/14 이전 모델에서는 기본 캐시 동작을 특히 조심해야 했다.
  // 현재 버전에서도 force-cache나 revalidate를 명시하면 갱신 정책이 필요하다.
  const res = await fetch('https://db.api/api/notice/urgent', {
    next: { revalidate: 3600 },
  });
  const data = await res.json();
  return <div>{data.title}</div>
}

✅ 제어권 되찾기 (Opting out)

수천 가지의 "캐시 안 해!" 탈출 방법이 있어.

1) 부분 탈출 (Fetch 레벨)
fetch(url, { cache: 'no-store' }) // Next.js야, 제발 이 쿼리만큼은 매번 실시간으로 가져오렴!

2) 파일 전체 탈출 (Segment Configuration)

export const dynamic = 'force-dynamic' // 이 파일(page) 내의 모든 로직 캐시 거부!
 
export default async function Page() { ... }

3) 시간제 보관 (ISR - Time based Revalidation)
fetch(url, { next: { revalidate: 3600 } }) // Next.js야, 이거 1시간(3600초) 카운트다운하고 캐시 폐기해.

🛡️ 3단계: Full Route Cache (완성된 HTML의 화석화) 🔴

Data Cache가 "DB 쿼리 결과(JSON)"를 조각조각 얼려두는 거라면, Full Route Cache는 더 극강의 병기야.
아예 화면 전체 HTML/RSC 결과를 빌드 타임이나 재검증 시점에 만들어 두고 재사용하는 계층이라고 보면 돼.

특징

• 목적: 서버 깡통 CPU를 아끼기 위해, 1초의 지연도 없이 번개처럼 화면을 응답하기 위한 완제품 보관.
• 수명: 영구적. 다음 빌드(Build)명령 npm run build를 새로 치기 전까지 사라지지 않음.
• 조건: 요청마다 달라지는 입력(cookies, headers, 실시간 데이터 등)이 없고, 라우트가 정적으로 평가될 수 있을 때.

🔄 Static vs Dynamic 루트 판독기

터미널에서 npm run build를 쳤을 때 뜨는 성적표를 잘 봐야 해.

Route (app)                       Size     First Load JS
┌ ○ /                             154 B    86.6 kB
├ ○ /about                        154 B    86.6 kB
└ ƒ /profile/[id]                 154 B    86.6 kB
 
○  (Static)   prerendered as static HTML (uses no initial data)
ƒ  (Dynamic)  server-rendered on demand using Node.js

• ○ (Static) 판정의 비밀: 라우트 결과가 요청별 입력에 의존하지 않을 때 획득한다. 공개 마케팅 페이지나 일정 시간 재사용 가능한 목록이 여기에 어울린다.
• ƒ (Dynamic) 판정: 로그인 인증처럼 cookies()나 headers()에 따라 결과가 바뀌면 요청마다 다시 판단해야 한다. 개인화 데이터를 정적 HTML에 섞으면 캐시 오염이 생긴다.

[영철이 에러의 진상 규명]
영철이의 공지사항 페이지는 공개 데이터라 캐시 후보였어. DB 값 업데이트 로직(Admin)만 만들고, 유저가 보는 라우트와 데이터 태그를 다시 검증하라는 명령(revalidatePath, revalidateTag, updateTag)을 연결하지 않았던 거야.

🚥 4단계: Router Cache (클라이언트 탭 메모리) 🟣

서버를 관리하는 위 3개의 캐시와 다르게, 마지막 방어선은 사파리/크롬 브라우저 속 사용자 컴퓨터의 메모리(RAM) 안에 살아있어.

브라우저는 똑똑하고 게으르다

Next.js App Router로 네비게이션(Link 태그 클릭)을 하면, 기존 리액트처럼 서버로 안 가고 브라우저 안에 꿍쳐둔 렌더링 조각 모음(RSC Payload)을 꺼내써.

• 수명: 브라우저 탭을 X로 닫거나 새로고침(F5)을 누르기 전까지(또는 30초~5분 내외 메모리 정책 만료 전까지).
• 이 대상 때문에 "나 방금 글 썼는데 뒤로 가기 눌렀더니 옛날 목록 뜨네?" 같은 버그성 체감이 간헐적으로 발생해.

🔨 무효화하기 (Invalidation)

이 캐시가 방해가 될 때는 브라우저에게 "네임펜으로 쓴 메모 수첩 비워!"라고 명령해야 해.

'use client'
import { useRouter } from 'next/navigation'
 
export default function ReRouteButton() {
  const router = useRouter()
  return <button onClick={() => router.refresh()}>강제 갱신(브라우저 캐시 무효화)!</button>
}

router.refresh() 는 화면 백지화 없이 오직 백그라운드로 서버의 최신 RSC Payload만 새로 싹 내려받아 치환하는 마법의 고급 훅이야.

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ Dynamic server usage: cookies 에러가 뜨면서 빌드가 실패해요!

원인: generateStaticParams 와 같이 '미리 정적으로(Static) 구워두려고 작정'한 파일 공간 내부에서, cookies() 나 URL 쿼리 파라미터 같이 실시간 런타임에만 알 수 있는 객체를 무리하게 꺼내 쓰려다 모순이 발생한 것.
해결책: 페이지에 export const dynamic = 'force-dynamic' 을 명시적으로 선언하여 이 파일은 절대 화석(Static)으로 남을 수 없는 운명임을 Next.js에게 자백해라.

🏁 이번에 배운 내용 총정리

이 거대한 4중 장벽의 방어 순서! 브라우저가 화면을 달라고 조르면...

💡 시니어의 멘탈 모델
빌드 시 ○ (Static) 로 굳어버린 라우트는 Data Cache를 무효화하기 전까지 절대 자기 스스로 갱신되지 않는다.
"데이터가 안 바뀌어요!" 라는 질문에 당황하지 말고, 가장 먼저 Vercel 빌드 터미널 창을 열고 그 페이지가 ○ 인지 ƒ 인지부터 색출하라!

📝 마무리 퀴즈

Q1. 영철이가 /profile/me 페이지에서 cookies()로 세션을 읽고 사용자 이름을 렌더링한다. 이 페이지를 Full Route Cache로 정적으로 구워도 될까?

✅ 정답: 안 된다.

💡 상세 해설: /profile/me는 요청 쿠키에 따라 결과가 달라지는 개인화 페이지다. cookies(), headers() 같은 요청 시점 API를 쓰면 정적 HTML 하나를 모든 사용자에게 공유할 수 없다. 영호가 강조한 기준은 간단하다. 요청마다 달라지는 입력이 렌더링 결과를 바꾸면 Full Route Cache 대상이 아니다. 공개 프로필처럼 URL 파라미터만으로 결과가 결정되는 구조와 분리해야 한다.

Q2. 관리자 페이지에서 공지 제목을 수정했는데 메인 공지 목록이 계속 예전 제목을 보여준다. 서버에 남아 있을 가능성이 가장 큰 캐시는 무엇인가?

✅ 정답: Data Cache 또는 그 데이터를 포함해 만들어진 Full Route Cache다.

💡 상세 해설: Request Memoization은 한 번의 렌더링 동안만 중복 fetch를 합치는 임시 기억이고, Router Cache는 브라우저 세션의 RSC Payload 기억이다. 새 요청에서도 낡은 데이터가 반복된다면 서버 쪽 Data Cache가 갱신되지 않았거나, 그 데이터로 만든 Full Route Cache가 아직 재검증되지 않았을 가능성이 높다. 수정 액션에는 revalidateTag나 revalidatePath 같은 무효화 전략이 함께 있어야 한다.

Q3. 영철이의 테스트 타임: 영수네 커뮤니티 홈은 공개 게시글 목록과 로그인한 사용자의 알림 배지를 함께 보여준다. 전체 페이지를 Dynamic으로 만들지 않고 빠른 첫 화면도 지키고 싶다. 어떤 설계가 더 안전할까?

✅ 정답: 공개 게시글 목록은 캐시 가능한 서버 데이터로 두고, 알림 배지는 요청 시점 데이터가 필요한 별도 경계로 분리한다.

💡 상세 해설: 공개 목록은 여러 사용자가 같은 결과를 보므로 Data Cache나 Full Route Cache의 후보가 된다. 반면 알림 배지는 쿠키와 사용자별 권한에 의존하므로 정적 셸 안에 섞으면 캐시 오염이 생긴다. 영호라면 "무엇을 캐시할지"보다 먼저 어떤 입력이 결과를 바꾸는지를 표로 나누라고 리뷰할 것이다.

🐣 영철이의 퇴근 일기

오늘은 캐시를 하나의 스위치처럼 보던 습관을 버렸다. Request Memoization, Data Cache, Full Route Cache, Router Cache가 서로 다른 수명과 위치를 가진다는 걸 알고 나니, "왜 새로고침했는데도 그대로지?"라는 질문도 훨씬 정확해졌다.

💡 "캐시는 빠르게 만드는 장치가 아니라, 같은 결과라고 말할 수 있는 범위를 선언하는 장치다."

내일부터 리뷰에서는 먼저 데이터의 주인을 묻기로 했다. 공개 데이터인지, 사용자 쿠키에 묶인 데이터인지, 브라우저가 잠깐 들고 있는 화면 조각인지 나눠 보고, 캐시를 붙인 코드 옆에는 반드시 무효화 경로를 같이 확인하겠다. 영호가 말한 것처럼 캐시 설계는 성능 튜닝이면서 동시에 개인정보 경계 설계다.

🔗 더 알아보기

• Next.js Docs: Building Your Application - Caching