웹사이트 느릴 때 반드시 설정 해야 할 웹 캐시 & 캐싱 완전 정복: React Query부터 Vercel CDN, ISR까지

바이브 코딩으로 웹사이트를 뚝딱 만들었는데, 페이지 로딩이 느리거나 서버 비용이 예상보다 많이 나오고 있지 않으신가요? 혹시 같은 데이터를 매번 서버에서 불러오고 있지는 않으신가요? 이런 문제의 해결책이 바로 "캐싱(Caching)"입니다.

캐싱은 웹 성능 최적화의 핵심입니다. 제대로 구축하면 로딩 속도가 10배 이상 빨라지고, 서버 비용은 90% 이상 줄일 수 있습니다. 하지만 캐싱이라는 단어를 들어봤어도, 막상 적용하려면 어디서부터 시작해야 할지 막막한 분들이 많습니다.

이 문서에서는 캐시가 무엇인지 기초 개념부터 시작하여, 브라우저 캐시, CDN 캐시, React Query 캐시, 그리고 Next.js의 SSR, SSG, ISR까지 캐싱의 모든 것을 누구나 이해할 수 있도록 차근차근 설명합니다. 특히 Vercel에 Next.js 프로젝트를 배포한 분들이라면, 이 글을 통해 캐싱의 전체 그림을 파악하고 바로 적용할 수 있습니다.

1. 캐시란 무엇인가: 기초 개념 완전 이해

캐싱을 제대로 활용하려면 먼저 "캐시(Cache)"가 무엇인지 정확히 이해해야 합니다. 캐시는 생각보다 우리 일상에서 자주 접하는 개념입니다.

1) 캐시의 정의와 일상 속 비유

• 캐시(Cache)는 "은닉처", "저장소"라는 뜻의 프랑스어에서 유래했습니다. 컴퓨터 과학에서는 자주 사용하는 데이터를 빠르게 접근할 수 있는 곳에 임시로 저장해두는 메커니즘을 의미합니다.
• 일상의 비유로 설명하면, 자주 보는 책을 책장에서 꺼내 책상 위에 올려두는 것과 같습니다. 책장까지 가서 찾는 것보다 책상 위에서 바로 집는 것이 훨씬 빠른 것처럼, 캐시도 원본 데이터 저장소(서버, 데이터베이스)까지 가지 않고 가까운 곳에서 데이터를 가져옵니다.
• 또 다른 비유로는 냉장고가 있습니다. 마트(서버)에서 매번 음식을 사오는 것보다, 냉장고(캐시)에 보관해두고 필요할 때 꺼내 먹는 것이 훨씬 효율적입니다. 다만 음식에 유통기한이 있듯이, 캐시에도 유효 기간이 있습니다.

2) 웹에서 캐싱이 필요한 이유

• 웹사이트에서 데이터를 가져오는 과정은 여러 단계를 거칩니다. 사용자가 버튼을 클릭하면 브라우저가 서버에 요청을 보내고, 서버는 데이터베이스를 조회한 후 결과를 반환합니다. 이 왕복 과정에서 수백 밀리초에서 수 초까지 시간이 걸릴 수 있습니다.
• 문제는 같은 데이터를 여러 사용자가 반복해서 요청한다는 것입니다. 예를 들어 쇼핑몰의 카테고리 목록은 거의 변하지 않는데, 100명의 사용자가 방문하면 100번의 동일한 데이터베이스 쿼리가 실행됩니다. 이는 서버 자원 낭비이고, 사용자는 불필요하게 느린 응답을 경험합니다.
• 캐싱을 적용하면 첫 번째 요청에서만 서버와 데이터베이스를 거치고, 이후 99번의 요청은 캐시된 데이터를 즉시 반환합니다. 응답 시간은 수백 밀리초에서 수 밀리초로 단축되고, 서버 비용도 99% 절감할 수 있습니다.

3) 캐시의 핵심 용어 정리

• 캐시 히트(Cache Hit): 요청한 데이터가 캐시에 있어서 원본 저장소에 접근하지 않고 바로 반환하는 경우입니다. 마치 책상 위에서 바로 책을 찾은 것과 같습니다.
• 캐시 미스(Cache Miss): 캐시에 데이터가 없거나 만료되어 원본 저장소에서 새로 가져와야 하는 경우입니다. 책장까지 가서 책을 찾아야 하는 상황입니다.
• TTL(Time To Live): 캐시 데이터의 유효 기간입니다. 이 시간이 지나면 데이터가 "만료(expired)" 또는 "오래됨(stale)" 상태가 됩니다.
• 캐시 무효화(Cache Invalidation): 캐시된 데이터를 강제로 삭제하거나 갱신하는 작업입니다. 원본 데이터가 변경되었을 때 필요합니다.

2. 웹 캐시의 종류와 계층 구조

웹에서는 데이터가 사용자에게 전달되기까지 여러 위치에 캐시가 존재합니다. 각 캐시의 역할과 특성을 이해해야 효과적인 캐싱 전략을 세울 수 있습니다.

1) 브라우저 캐시 (Browser Cache / HTTP Cache)

• 브라우저 캐시는 사용자의 컴퓨터에 저장되는 캐시입니다. Chrome, Firefox, Safari, Edge 등 모든 브라우저가 이 기능을 기본으로 내장하고 있습니다.
• 이미지, CSS, JavaScript 파일, API 응답 등을 하드 디스크나 메모리에 저장합니다. 개발자 도구(F12)의 Network 탭에서 "(disk cache)" 또는 "(memory cache)"로 표시되는 것이 이 캐시입니다.
• 장점은 사용자 컴퓨터에 있으므로 가장 빠르게 접근할 수 있다는 것입니다. 네트워크 요청 자체가 필요 없습니다. 단점은 한 사용자에게만 적용되고, 브라우저를 닫거나 캐시를 지우면 사라진다는 것입니다.

2) CDN 캐시 (Content Delivery Network Cache)

• CDN은 전 세계에 분산된 서버 네트워크입니다. Vercel, Cloudflare, AWS CloudFront, Akamai 등이 대표적인 CDN 서비스입니다. Vercel에 배포하면 자동으로 Vercel Edge Network라는 CDN을 사용하게 됩니다.
• CDN 캐시는 원본 서버(Origin Server)의 응답을 전 세계 CDN 서버(엣지 서버)에 저장합니다. 한국 사용자가 요청하면 서울에 있는 CDN 서버에서 응답하고, 미국 사용자가 요청하면 미국에 있는 CDN 서버에서 응답합니다.
• 장점은 모든 사용자가 캐시를 공유하므로 효율적이고, 사용자와 물리적으로 가까운 위치에서 응답하므로 빠르다는 것입니다. 원본 서버의 부하를 크게 줄여주며, 서버 비용 절감에 직접적인 효과가 있습니다.

3) 서버 캐시 (Server-side Cache)

• 서버 내부에서 운영하는 캐시입니다. Redis, Memcached 같은 인메모리 데이터베이스를 사용하거나, Next.js의 Data Cache처럼 프레임워크가 자체적으로 관리하는 캐시가 여기에 해당합니다.
• 데이터베이스 쿼리 결과나 외부 API 응답을 서버 메모리에 저장해두고, 같은 요청이 오면 데이터베이스나 외부 API에 접근하지 않고 바로 반환합니다.
• Next.js에서는 fetch 요청의 결과를 자동으로 캐시하는 Data Cache가 있으며, 이 캐시는 배포 간에도 유지되어 재배포 후에도 캐시된 데이터를 사용할 수 있습니다.

4) 애플리케이션 캐시 (Application Cache / In-memory Cache)

• 애플리케이션 코드 내에서 관리하는 클라이언트 측 캐시입니다. React Query(TanStack Query), SWR, Apollo Client 등의 상태 관리 라이브러리가 이 역할을 합니다.
• JavaScript 메모리(힙)에 데이터를 저장하며, 같은 페이지 내에서 여러 컴포넌트가 동일한 데이터를 공유할 수 있게 해줍니다. 예를 들어 헤더와 사이드바에서 같은 사용자 정보를 표시할 때, API를 두 번 호출하지 않고 캐시된 데이터를 재사용합니다.
• 장점은 개발자가 세밀하게 제어할 수 있다는 것입니다. 캐시 시간, 재검증 조건, 무효화 시점 등을 코드로 정확히 지정할 수 있습니다. 단점은 페이지를 새로고침하면 메모리가 초기화되어 캐시가 사라지고, 해당 브라우저 탭에서만 유효하다는 것입니다.

5) 캐시 계층의 데이터 흐름

• 사용자가 데이터를 요청하면 가장 가까운 캐시부터 순서대로 확인합니다. 먼저 React Query 같은 애플리케이션 캐시를 확인하고, 없으면 브라우저 HTTP 캐시를 확인하며, 없으면 CDN 캐시를 확인하고, 그래도 없으면 원본 서버에 요청합니다.
• 이 계층 구조 덕분에 각 단계에서 캐시 히트가 발생할 수 있어, 원본 서버까지 요청이 도달하는 경우를 최소화할 수 있습니다. 잘 설계된 캐싱 전략에서는 원본 서버 요청이 전체의 1% 미만으로 줄어들 수 있습니다.

3. HTTP 캐시와 Cache-Control 헤더 완전 이해

HTTP 캐시는 웹 캐싱의 기본이자 핵심입니다. 서버가 응답을 보낼 때 Cache-Control 헤더를 통해 "이 데이터를 어떻게 캐시해야 하는지"를 브라우저와 CDN에게 지시합니다.

1) Cache-Control 헤더의 기본 구조

• Cache-Control은 HTTP 응답 헤더로, 여러 지시어(directive)를 쉼표로 구분하여 조합합니다. 예: Cache-Control: public, max-age=3600, s-maxage=86400
• 각 지시어는 캐시의 특정 동작을 제어합니다. public은 "이 응답은 누구나 캐시해도 된다", max-age=3600은 "3600초(1시간) 동안 유효하다"는 의미입니다.
• 이 헤더를 올바르게 설정하는 것이 웹 성능 최적화의 첫 번째 단계입니다. 잘못 설정하면 캐시가 전혀 작동하지 않거나, 반대로 오래된 데이터가 계속 보여질 수 있습니다.

2) 주요 Cache-Control 지시어 상세 설명

• public: 응답이 브라우저, CDN, 프록시 등 모든 캐시에 저장될 수 있음을 의미합니다. 로그인이 필요 없는 공개 데이터에 사용합니다.
• private: 응답이 브라우저 캐시에만 저장될 수 있고, CDN이나 공유 캐시에는 저장되면 안 된다는 의미입니다. 사용자별 개인 데이터(장바구니, 프로필 등)에 사용합니다.
• max-age=초: 응답이 "신선한(fresh)" 상태로 유지되는 시간을 초 단위로 지정합니다. 브라우저와 CDN 모두에 적용됩니다. max-age=3600은 1시간입니다.
• s-maxage=초: CDN(공유 캐시)에서만 적용되는 캐시 시간입니다. "s"는 shared의 약자입니다. 브라우저 캐시에는 영향을 주지 않습니다. Vercel에서 CDN 캐시 시간을 설정할 때 주로 사용합니다.
• no-cache: 캐시는 하되, 사용하기 전에 반드시 서버에 유효성을 확인하라는 의미입니다. "캐시하지 마"가 아니라 "캐시해도 되지만 매번 확인해"입니다.
• no-store: 응답을 어디에도 캐시하지 말라는 의미입니다. 민감한 정보(결제 정보, 비밀번호 등)에 사용합니다.
• stale-while-revalidate=초: 캐시가 만료된 후에도 지정된 시간 동안 오래된 캐시를 먼저 반환하고, 백그라운드에서 새 데이터를 가져오라는 의미입니다. 사용자는 항상 빠른 응답을 받고, 다음 요청부터 새 데이터가 적용됩니다.

3) ETag와 Last-Modified: 조건부 요청

• ETag는 리소스의 "지문"과 같습니다. 서버가 응답과 함께 ETag: "abc123" 헤더를 보내면, 브라우저는 다음 요청 시 If-None-Match: "abc123" 헤더를 포함합니다. 서버는 리소스가 변경되지 않았으면 304 Not Modified 상태 코드만 반환하고, 실제 데이터는 보내지 않습니다.
• Last-Modified는 리소스가 마지막으로 수정된 날짜입니다. 서버가 Last-Modified: Wed, 01 Jan 2026 00:00:00 GMT를 보내면, 브라우저는 다음 요청 시 If-Modified-Since 헤더로 이 날짜를 보냅니다. 서버는 그 이후로 변경이 없으면 304를 반환합니다.
• 304 Not Modified 응답은 네트워크를 통해 전송되지만, 실제 데이터(body)가 없어 매우 가볍습니다. 캐시된 데이터가 여전히 유효하다는 확인만 받고, 브라우저는 로컬 캐시를 그대로 사용합니다.

4) Vercel에서 Cache-Control 설정 방법

• Next.js API Route에서 직접 설정할 수 있습니다. NextResponse를 반환할 때 headers 옵션에 Cache-Control을 포함하면 됩니다. 예: headers: { 'Cache-Control': 'public, s-maxage=604800, stale-while-revalidate=604800' }
• s-maxage=604800은 CDN에서 7일(604800초) 동안 캐시하라는 의미이고, stale-while-revalidate=604800은 만료 후 7일 동안 오래된 캐시를 제공하면서 백그라운드 갱신하라는 의미입니다.
• Vercel은 CDN-Cache-Control과 Vercel-CDN-Cache-Control 헤더도 지원합니다. 이를 통해 Vercel CDN, 다른 CDN, 브라우저 캐시를 각각 다른 시간으로 설정할 수 있습니다.

4. Next.js 렌더링 방식과 캐싱: CSR, SSR, SSG, ISR

Next.js는 다양한 렌더링 방식을 지원하며, 각 방식에 따라 캐싱 동작이 완전히 달라집니다. 이 네 가지 방식을 이해하는 것이 Next.js 캐싱 전략의 핵심입니다.

1) CSR (Client-Side Rendering, 클라이언트 사이드 렌더링)

• CSR은 브라우저에서 JavaScript가 실행된 후에 페이지 내용이 렌더링되는 방식입니다. 서버는 빈 HTML 껍데기만 보내고, React 코드가 브라우저에서 실행되면서 API를 호출하고 화면을 그립니다.
• 장점은 서버 부하가 적고, 페이지 전환이 빠르며, 인터랙티브한 UI에 적합하다는 것입니다. 단점은 초기 로딩이 느리고, JavaScript가 실행되기 전에는 빈 화면이 보이며, 검색 엔진이 내용을 인식하기 어려울 수 있다는 것입니다.
• CSR에서 캐싱은 주로 React Query 같은 클라이언트 캐시와 브라우저 HTTP 캐시에 의존합니다. 서버 측 캐시(CDN, Data Cache)는 API 응답에만 적용됩니다.

2) SSR (Server-Side Rendering, 서버 사이드 렌더링)

• SSR은 사용자가 페이지를 요청할 때마다 서버에서 HTML을 생성하는 방식입니다. 서버가 데이터베이스를 조회하고, React 컴포넌트를 실행하여 완성된 HTML을 만들어 보냅니다.
• 장점은 사용자가 항상 최신 데이터를 보고, SEO에 유리하며, 초기 로딩 시 내용이 바로 보인다는 것입니다. 단점은 매 요청마다 서버 작업이 필요해 서버 부하가 높고, TTFB(Time To First Byte)가 길어질 수 있다는 것입니다.
• SSR 페이지는 기본적으로 캐시되지 않습니다. 매 요청마다 새로 렌더링됩니다. 하지만 Cache-Control 헤더를 설정하면 CDN에서 SSR 응답을 캐시할 수 있습니다.

3) SSG (Static Site Generation, 정적 사이트 생성)

• SSG는 빌드 시점(npm run build)에 모든 페이지를 미리 HTML로 생성해두는 방식입니다. 사용자가 요청하면 이미 만들어진 HTML 파일을 그대로 반환합니다.
• 장점은 가장 빠른 응답 속도를 제공하고, 서버 부하가 거의 없으며, CDN에서 완벽하게 캐시된다는 것입니다. 단점은 빌드 시점의 데이터만 반영되어, 데이터가 변경되면 다시 빌드해야 한다는 것입니다.
• SSG 페이지는 자동으로 Full Route Cache에 저장됩니다. 한 번 빌드하면 배포 기간 내내 캐시된 HTML을 제공합니다. 블로그, 문서, 마케팅 페이지 등 내용이 자주 변하지 않는 페이지에 적합합니다.

4) ISR (Incremental Static Regeneration, 점진적 정적 재생성)

• ISR은 SSG의 장점을 유지하면서 데이터 갱신 문제를 해결한 방식입니다. 정적 페이지를 제공하되, 지정된 시간이 지나면 백그라운드에서 페이지를 다시 생성합니다.
• 작동 방식은 이렇습니다. 사용자가 페이지를 요청하면 캐시된 정적 페이지를 즉시 반환합니다. 만약 설정된 revalidate 시간이 지났다면, 이 요청을 처리하면서 동시에 백그라운드에서 페이지를 새로 생성합니다. 다음 사용자부터는 새로 생성된 페이지를 받습니다.
• 장점은 정적 페이지의 빠른 속도를 유지하면서도, 전체 사이트를 다시 빌드하지 않고 개별 페이지만 갱신할 수 있다는 것입니다. 뉴스 사이트, 이커머스 상품 페이지 등 데이터가 주기적으로 변하는 페이지에 적합합니다.

5) 렌더링 방식 선택 가이드

• 데이터가 거의 변하지 않는 페이지(회사 소개, 약관 등)는 SSG를 사용합니다. 빌드 시 한 번만 생성하고 CDN에서 제공합니다.
• 데이터가 주기적으로 변하는 페이지(상품 목록, 뉴스 등)는 ISR을 사용합니다. revalidate를 60초로 설정하면 1분마다 데이터가 갱신됩니다.
• 실시간 데이터가 필요한 페이지(주식 시세, 실시간 채팅 등)는 SSR 또는 CSR을 사용합니다. 매 요청마다 최신 데이터를 가져옵니다.
• 사용자 인터랙션이 많은 페이지(대시보드, 에디터 등)는 CSR이 적합합니다. 초기 로딩 후에는 클라이언트에서 모든 것을 처리합니다.

5. Next.js의 4가지 캐시 메커니즘 완전 분석

Next.js App Router에서는 4가지 서로 다른 캐시 메커니즘이 동작합니다. 각각의 역할과 상호작용을 이해하면 캐싱을 정확하게 제어할 수 있습니다.

1) Request Memoization (요청 메모이제이션)

• Request Memoization은 같은 렌더링 사이클 내에서 동일한 fetch 요청을 자동으로 중복 제거하는 기능입니다. 이것은 React의 기능이며, Next.js가 이를 활용합니다.
• 예를 들어 Layout, Page, 여러 컴포넌트에서 같은 API를 호출해도 실제 네트워크 요청은 한 번만 발생합니다. 첫 번째 호출 결과가 메모리에 저장되고, 나머지 호출은 이 결과를 재사용합니다.
• 이 캐시는 단일 요청의 렌더링이 완료되면 사라집니다. 다음 요청에서는 다시 fetch가 실행됩니다. 서버 컴포넌트에서만 동작하며, GET 메서드에만 적용됩니다.

2) Data Cache (데이터 캐시)

• Data Cache는 fetch 요청의 결과를 서버에 영구적으로 저장하는 기능입니다. 사용자 요청 간에도, 심지어 재배포 후에도 캐시가 유지됩니다.
• fetch 요청에 { cache: 'force-cache' } 옵션을 주거나, 정적 렌더링 중에 호출하면 결과가 Data Cache에 저장됩니다. 이후 같은 요청은 원본 서버에 접근하지 않고 캐시된 데이터를 반환합니다.
• Data Cache를 갱신하는 방법은 두 가지입니다. 시간 기반 재검증(Time-based Revalidation)은 { next: { revalidate: 60 } }처럼 초 단위로 지정하면 그 시간이 지난 후 백그라운드에서 갱신됩니다. 요청 기반 재검증(On-demand Revalidation)은 revalidateTag() 또는 revalidatePath()를 호출하여 즉시 캐시를 무효화합니다.

3) Full Route Cache (전체 라우트 캐시)

• Full Route Cache는 정적으로 렌더링된 페이지의 HTML과 RSC Payload를 서버에 캐시하는 기능입니다. SSG와 ISR 페이지에 적용됩니다.
• 빌드 시점에 페이지가 렌더링되면 그 결과(HTML + RSC Payload)가 Full Route Cache에 저장됩니다. 사용자 요청 시 서버는 React를 다시 실행하지 않고 캐시된 결과를 반환합니다.
• 동적 렌더링(SSR)을 사용하는 페이지는 Full Route Cache에 저장되지 않습니다. cookies(), headers(), searchParams 등 요청별로 달라지는 API를 사용하면 자동으로 동적 렌더링으로 전환됩니다.

4) Router Cache (라우터 캐시)

• Router Cache는 클라이언트(브라우저) 측에서 RSC Payload를 메모리에 저장하는 기능입니다. 페이지 간 네비게이션을 빠르게 만들어줍니다.
• 사용자가 페이지를 방문하면 해당 페이지의 RSC Payload가 Router Cache에 저장됩니다. 이후 같은 페이지로 돌아가면 서버 요청 없이 캐시된 데이터로 즉시 화면을 그립니다. 또한 Link 컴포넌트는 뷰포트에 보이는 링크들을 미리 프리페치하여 Router Cache에 저장합니다.
• Router Cache는 브라우저 세션 동안만 유지됩니다. 페이지를 새로고침하면 초기화됩니다. Next.js 15부터는 페이지 세그먼트가 기본적으로 캐시되지 않도록 변경되었습니다.

5) 4가지 캐시의 상호작용

• 이 캐시들은 서로 연결되어 있습니다. Data Cache가 재검증되면 Full Route Cache도 무효화됩니다. 왜냐하면 페이지 렌더링 결과가 데이터에 의존하기 때문입니다.
• revalidatePath()를 호출하면 Data Cache, Full Route Cache, Router Cache가 모두 무효화됩니다. revalidateTag()도 마찬가지입니다.
• router.refresh()는 Router Cache만 무효화하고 Data Cache와 Full Route Cache는 유지합니다. 서버 데이터는 그대로 두고 클라이언트 캐시만 새로고침하고 싶을 때 사용합니다.

6. React Query 캐싱 시스템 완전 정복

React Query(TanStack Query)는 클라이언트 측 서버 상태 관리의 표준 라이브러리입니다. 강력한 캐싱 기능으로 불필요한 API 호출을 줄이고 사용자 경험을 크게 개선할 수 있습니다.

1) staleTime 완전 이해하기

• staleTime은 데이터가 "신선한(fresh)" 상태로 유지되는 시간입니다. "stale"은 "신선하지 않은", "오래된"이라는 뜻입니다. staleTime은 "데이터가 stale 상태가 되기까지의 시간"입니다.
• 기본값은 0입니다. 이는 데이터를 받자마자 즉시 "오래된" 것으로 간주한다는 의미입니다. 새 컴포넌트가 마운트되거나 윈도우에 포커스가 돌아오면 백그라운드에서 데이터를 다시 가져옵니다. 이 과정에서 기존 캐시 데이터는 먼저 보여주고, 새 데이터가 도착하면 업데이트합니다.
• staleTime을 5분(300000ms)으로 설정하면, 5분 동안은 데이터가 "신선한" 상태로 유지됩니다. 이 기간에는 어떤 상황에서도 네트워크 요청을 보내지 않고 캐시된 데이터만 사용합니다. 데이터 갱신 주기에 맞춰 적절히 설정하면 불필요한 API 호출을 크게 줄일 수 있습니다.

2) gcTime 완전 이해하기

• gcTime(이전 버전에서는 cacheTime)은 "가비지 컬렉션 시간"입니다. 쿼리가 비활성화된 후 캐시가 메모리에서 제거되기까지의 시간을 의미합니다.
• "비활성화"란 해당 쿼리를 사용하는 모든 컴포넌트가 언마운트된 상태입니다. 예를 들어 상품 목록 페이지에서 다른 페이지로 이동하면, 상품 목록 쿼리가 비활성화됩니다.
• 기본값은 5분(300000ms)입니다. 상품 목록 페이지를 떠난 후 5분이 지나면 캐시가 메모리에서 삭제됩니다. 5분 이내에 다시 돌아오면 캐시된 데이터가 즉시 표시되어 로딩 없이 화면을 볼 수 있습니다.

3) staleTime과 gcTime의 관계

• 두 설정은 서로 다른 역할을 합니다. staleTime은 "언제 새 데이터를 가져올지"를 결정하고, gcTime은 "캐시를 얼마나 오래 보관할지"를 결정합니다.
• gcTime은 항상 staleTime보다 크거나 같아야 합니다. 만약 staleTime이 7일인데 gcTime이 5분이면, 데이터가 아직 신선한 상태(새 요청 필요 없음)인데도 캐시에서 삭제될 수 있습니다. 이는 논리적으로 맞지 않습니다.
• 권장 설정은 gcTime을 staleTime의 1.5배에서 2배로 설정하는 것입니다. staleTime이 1시간이라면 gcTime은 1시간 30분에서 2시간 정도가 적절합니다.

4) queryKey의 역할과 캐시 분리

• queryKey는 캐시의 고유 식별자입니다. React Query는 queryKey를 기준으로 캐시를 저장하고 조회합니다. 같은 queryKey를 가진 모든 쿼리는 같은 캐시를 공유합니다.
• queryKey는 배열 형태로 구성되며, 배열 내용이 달라지면 완전히 다른 캐시 엔트리로 취급됩니다. ['products']와 ['products', { category: 'electronics' }]는 서로 다른 캐시입니다.
• 필터나 검색 조건이 있는 API라면 해당 파라미터를 queryKey에 포함해야 합니다. 그래야 각 조건별로 독립적인 캐시가 생성됩니다. 예를 들어 ['channels', { country: 'KR', page: 1 }]과 ['channels', { country: 'US', page: 1 }]은 별도로 캐시됩니다.

5) 새로고침과 React Query 캐시

• React Query 캐시는 JavaScript 메모리(힙)에 저장됩니다. 페이지를 새로고침(F5)하면 JavaScript 실행 환경이 초기화되므로 React Query 캐시도 사라집니다.
• 하지만 이것이 문제가 되지 않는 이유는 캐시 계층 구조 때문입니다. React Query 캐시가 사라져도 브라우저 HTTP 캐시나 CDN 캐시에서 데이터를 빠르게 가져올 수 있습니다.
• 캐시를 새로고침에도 유지하고 싶다면 React Query Persist를 사용할 수 있습니다. 이 기능은 캐시를 localStorage에 저장하여 페이지 새로고침 후에도 복원합니다. 하지만 대부분의 경우 HTTP/CDN 캐시가 있으면 Persist 없이도 충분히 빠른 응답을 받을 수 있습니다.

7. 실무 캐싱 전략 설계 가이드

이론을 알았으니 이제 실제로 어떻게 캐싱 전략을 설계하고 적용하는지 알아봅니다. 데이터 특성과 비즈니스 요구사항에 따라 다른 전략이 필요합니다.

1) 데이터 특성별 캐시 설정

• 거의 변하지 않는 데이터(국가 목록, 카테고리, 약관 등)는 길게 캐시합니다. staleTime 7일 이상, CDN s-maxage 7일 이상으로 설정하여 API 호출을 최소화합니다.
• 주기적으로 변하는 데이터(상품 목록, 뉴스, 통계 등)는 업데이트 주기에 맞춰 캐시합니다. 매일 업데이트되면 1일, 매주 업데이트되면 7일로 설정합니다.
• 실시간 데이터(재고 수량, 가격, 알림 등)는 짧게 캐시하거나 캐시하지 않습니다. staleTime 30초에서 1분, 또는 캐시 없이 매번 조회합니다.
• 사용자별 개인 데이터(장바구니, 프로필, 설정 등)는 CDN 캐시 없이 브라우저 캐시만 사용합니다. Cache-Control: private을 설정합니다.

2) 버전 기반 캐시 무효화 전략

• 데이터가 변경되면 캐시를 자동으로 갱신하고 싶을 때 버전 기반 전략을 사용합니다. queryKey에 데이터 버전(예: 마지막 업데이트 날짜)을 포함합니다.
• 먼저 데이터 버전만 반환하는 가벼운 API를 만듭니다. 이 API는 데이터베이스에서 최신 created_at 또는 updated_at만 조회합니다. 캐시 시간은 1시간 정도로 짧게 설정합니다.
• 메인 데이터 쿼리의 queryKey에 이 버전을 포함합니다. 예: ['channels', dataVersion, filters]. 데이터가 업데이트되면 버전이 변경되고, 이는 새로운 queryKey를 생성하므로 자동으로 새 데이터를 가져옵니다.

3) 필터별 캐시 관리

• 필터 옵션이 있는 UI에서는 각 필터 조합이 별도의 캐시 엔트리를 생성합니다. 국가 필터, 정렬 옵션, 페이지 번호가 있다면 이 조합 수만큼 캐시가 생깁니다.
• 사용자가 필터를 변경했다가 원래 필터로 돌아오면, 기존 캐시가 유효한 경우 즉시 데이터를 표시합니다. 이를 통해 필터 전환이 매우 빠르게 느껴집니다.
• gcTime을 적절히 설정하여 사용하지 않는 필터 조합의 캐시는 자동으로 정리되도록 합니다. 14일 정도로 설정하면 자주 사용하는 조합은 유지되고, 드물게 사용하는 조합은 정리됩니다.

4) 캐시 무효화 타이밍

• 데이터 변경 후 즉시 반영이 필요한 경우 revalidateTag() 또는 revalidatePath()를 사용합니다. Server Action에서 데이터를 수정한 후 호출하면 관련 캐시가 즉시 무효화됩니다.
• 사용자 액션 후 UI 갱신이 필요한 경우 queryClient.invalidateQueries()를 사용합니다. 특정 queryKey의 캐시를 무효화하면 React Query가 자동으로 새 데이터를 가져옵니다.
• 배포 시 캐시를 초기화하고 싶다면 Vercel 대시보드에서 캐시 퍼지를 실행하거나, 버전 기반 캐시 전략을 사용하여 자연스럽게 갱신되도록 합니다.

8. FAQ

Q: 캐시를 설정했는데 데이터가 갱신되지 않아요. 어떻게 해야 하나요? A: 캐시가 아직 유효한 상태이기 때문입니다. 해결 방법은 여러 가지가 있습니다. 개발 중이라면 브라우저 캐시를 지우거나 강제 새로고침(Ctrl+F5)을 하면 됩니다. 운영 환경에서는 revalidateTag()나 revalidatePath()를 사용하여 서버 측 캐시를 무효화하고, React Query는 invalidateQueries()로 클라이언트 캐시를 무효화합니다. 근본적으로는 캐시 시간(staleTime, s-maxage)을 데이터 갱신 주기에 맞게 조정하는 것이 좋습니다.

Q: SSG, SSR, ISR 중 어떤 것을 선택해야 하나요? A: 데이터 변경 빈도와 실시간성 요구에 따라 선택합니다. 데이터가 거의 변하지 않는 페이지(회사 소개, 도움말 등)는 SSG를 사용합니다. 빌드 시 한 번만 생성되고 CDN에서 제공되므로 가장 빠릅니다. 데이터가 주기적으로 변하는 페이지(상품 목록, 블로그 등)는 ISR을 사용합니다. revalidate를 60초로 설정하면 1분마다 갱신됩니다. 항상 최신 데이터가 필요한 페이지(검색 결과, 실시간 가격 등)는 SSR을 사용합니다.

Q: 강제 새로고침(Ctrl+F5)하면 모든 캐시가 무너지나요? A: 완전히 무너지지는 않습니다. React Query 메모리 캐시와 브라우저 HTTP 캐시는 무효화되지만, CDN 캐시는 유지됩니다. CDN은 사용자의 브라우저 요청 헤더와 무관하게 자체 캐시 정책(s-maxage)을 따릅니다. 따라서 강제 새로고침 후에도 CDN에서 캐시된 응답을 빠르게 받을 수 있고, 이 데이터로 React Query 캐시가 다시 구축됩니다. 서버 원본까지 요청이 가는 것은 CDN 캐시도 만료된 경우뿐입니다.

Q: React Query의 staleTime과 gcTime 차이가 헷갈려요. A: 쉽게 비유하면 이렇습니다. staleTime은 "이 음식이 신선한 기간"이고, gcTime은 "이 음식을 냉장고에 보관하는 기간"입니다. 음식이 신선한 동안(staleTime)은 그냥 먹으면 됩니다(캐시 사용). 신선도가 떨어지면(stale) 새 음식을 주문하면서 일단 있는 것을 먹습니다(백그라운드 갱신). 냉장고 보관 기간(gcTime)이 지나면 음식을 버립니다(캐시 삭제). gcTime은 staleTime보다 길어야 논리적으로 맞습니다. 신선한 음식을 버리면 안 되니까요.

Q: Next.js의 Data Cache와 Full Route Cache의 차이점은 무엇인가요? A: Data Cache는 fetch 요청의 응답 데이터를 저장하고, Full Route Cache는 페이지 렌더링 결과(HTML + RSC Payload)를 저장합니다. Data Cache는 여러 페이지에서 같은 API를 호출할 때 재사용되고, Full Route Cache는 특정 URL의 페이지 전체를 캐시합니다. Data Cache가 재검증되면 Full Route Cache도 무효화됩니다. 왜냐하면 페이지 내용이 데이터에 의존하기 때문입니다. Data Cache는 배포 후에도 유지되지만, Full Route Cache는 새 배포 시 초기화됩니다.

Q: 캐시 설정이 잘 적용되었는지 어떻게 확인하나요? A: 여러 방법이 있습니다. 브라우저 개발자 도구(F12)의 Network 탭에서 응답 헤더를 확인합니다. Cache-Control, X-Vercel-Cache 헤더를 보면 캐시 상태를 알 수 있습니다. X-Vercel-Cache가 HIT이면 CDN 캐시에서 응답한 것이고, MISS면 원본 서버에서 가져온 것입니다. React Query는 React Query DevTools를 설치하면 캐시 상태, stale 여부, 데이터 내용 등을 실시간으로 확인할 수 있습니다.

9. 마무리

웹 캐싱은 복잡해 보이지만, 핵심 개념을 이해하면 체계적으로 접근할 수 있습니다. 캐시 계층 구조를 이해하고, 데이터 특성에 맞는 캐시 전략을 선택하면 웹사이트 성능을 극적으로 개선할 수 있습니다.

핵심 요약:

• 캐시는 자주 사용하는 데이터를 가까운 곳에 저장하여 빠르게 접근하는 메커니즘이며, 브라우저 캐시, CDN 캐시, 서버 캐시, 애플리케이션 캐시 등 여러 계층으로 구성됩니다
• Cache-Control 헤더의 s-maxage와 stale-while-revalidate를 조합하면 CDN에서 효율적으로 캐시하면서도 데이터 신선도를 유지할 수 있습니다
• Next.js의 SSG는 빌드 시 페이지를 생성하고, ISR은 정적 페이지를 주기적으로 갱신하며, SSR은 매 요청마다 렌더링합니다. 데이터 갱신 빈도에 따라 선택합니다
• Next.js App Router의 4가지 캐시(Request Memoization, Data Cache, Full Route Cache, Router Cache)는 서로 연결되어 있으며, revalidatePath()나 revalidateTag()로 함께 무효화됩니다
• React Query의 staleTime은 데이터 신선도를, gcTime은 캐시 보관 기간을 제어하며, queryKey에 파라미터를 포함하면 조건별로 독립적인 캐시가 생성됩니다

바이브 코딩으로 만든 웹사이트가 느리다면, 먼저 API 응답에 Cache-Control 헤더를 추가해보세요. 그 다음 React Query로 클라이언트 캐시를 설정하고, 페이지 특성에 맞게 SSG나 ISR을 적용하면 됩니다. 이 문서에서 설명한 개념들을 하나씩 적용해나가면, 로딩 속도는 빨라지고 서버 비용은 크게 줄어드는 것을 경험할 수 있습니다.