Кэширование и ревалидация: 4 уровня кэша Next.js

Зачем это нужно#

В высоконагруженных веб-приложениях латентность базы данных и внешних микросервисов напрямую определяет TTFB и пользовательский опыт. Неконтролируемое выполнение повторяющихся SQL-запросов и HTTP-вызовов перегружает вычислительные мощности сервера и приводит к исчерпанию пулов сетевых соединений.

В архитектуре Next.js App Router реализована многоуровневая система кэширования, объединяющая возможности ядра React и рантайма Next.js. Она охватывает весь жизненный цикл данных — от дедупликации вызовов в оперативной памяти одного серверного тика до распределенного хранения статических страниц на CDN и кэширования маршрутных сегментов в браузере клиента.

Глубокое понимание каждого уровня кэша, правил его деоптимизации и механизмов он-деманд инвалидации отделяет разработчика, страдающего от «зависших» данных в продакшене, от архитектора, проектирующего консистентные и быстрые распределенные системы.

Ментальная модель#

В Next.js функционируют 4 независимых уровня кэширования, каждый из которых решает узкоспециализированную задачу, имеет изолированную область видимости и собственный жизненный цикл:

1. Request Memoization (React): Кэш в оперативной памяти сервера на время генерации одного ответа. Предотвращает дублирование сетевых запросов между изолированными серверными компонентами дерева.
2. Data Cache (Next.js): Постоянный серверный кэш (диск, KV или Redis), сохраняющий ответы HTTP-запросов и результаты тяжелых вычислений между запросами разных клиентов и сессий.
3. Full Route Cache (Next.js): Серверный кэш скомпилированного HTML-документа и бинарного графа RSC Flight Payload для статических маршрутов.
4. Client Router Cache (Next.js / Browser): Кэш сегментов интерфейса в оперативной памяти вкладки браузера, обеспечивающий мгновенный переход между экранами без повторного обращения к серверу (Soft Navigation).

Ниже представлен интерактивный симулятор потока кэширования. Переключайте сценарии, чтобы изучить движение запроса сквозь все 4 уровня:

Синтаксис и API#

1. Request Memoization (React)#

React автоматически дедуплицирует вызовы fetch с одинаковым URL и одинаковым набором опций в пределах одного дерева рендеринга серверных компонентов. Жизненный цикл этого кэша ограничен миллисекундами генерации ответа.

[!IMPORTANT] Request Memoization не шарится между пользователями и сессиями. Это внутризапросная оптимизация единичного дерева рендера React Server Components. Для неё нет глобального флага отключения, но её можно обойти, передав уникальный AbortController (через свойство signal) в fetch.

// app/components/Header.tsx
export async function Header() {
  // Выполняется реальный сетевой запрос
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <header>Пользователь: {user.name}</header>;
}

// app/components/Sidebar.tsx
export async function Sidebar() {
  // Данные мгновенно извлекаются из Request Memoization (RAM) без повторного HTTP-запроса
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <aside>Роль: {user.role}</aside>;
}

2. Data Cache (Управление сетевым кэшем)#

В версиях Next.js 15+ стандартный fetch по умолчанию является некэшируемым (cache: 'no-store'). Кэширование на уровне Data Cache включается явно.

// 1. По умолчанию в Next.js 15+: no-store (всегда свежие данные из сети)
const freshData = await fetch('https://api.internal/rates');

// 2. Персистентное кэширование (хранится бесконечно до явной ревалидации)
const immutableData = await fetch('https://api.internal/dictionary', {
  cache: 'force-cache',
});

// 3. Time-based revalidation (Stale-While-Revalidate на 60 секунд)
const catalog = await fetch('https://api.internal/products', {
  next: { revalidate: 60 },
});

// 4. Тегирование запросов для точечной On-demand инвалидации
const profile = await fetch('https://api.internal/user/10', {
  next: { tags: ['user-10', 'users'] },
});

3. On-demand Revalidation: revalidateTag и revalidatePath#

Для сброса устаревших данных по событию (Server Action, обработка Webhook) используются функции из модуля next/cache. Они одновременно инвалидируют записи в Data Cache и зависимые сегменты в Full Route Cache.

'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { db } from '@/lib/db';
import { products } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export async function updateProductPrice(productId: string, newPrice: number): Promise<{ success: boolean }> {
  // 1. Мутация данных в основной базе данных
  await db.update(products).set({ price: newPrice }).where(eq(products.id, productId));

  // 2. Точечный сброс кэша по тегу (затрагивает все эндпоинты с этим тегом во всем приложении)
  revalidateTag(`product-${productId}`);
  revalidateTag('catalog-list');

  // 3. Инвалидация конкретного маршрута
  revalidatePath(`/products/${productId}`, 'page');

  return { success: true };
}

Практические паттерны#

Паттерн 1: Stale-While-Revalidate (SWR) под капотом#

При установке опции next: { revalidate: 60 } система работает по строгому протоколу:

1. Запрос T = 0c (Cold Start): Промах кэша. Сервер ожидает ответа от источника, отдает данные клиенту и сохраняет их в Data Cache с временной меткой.
2. Запросы T = 1..59c (Cache Hit): Все пользователи мгновенно получают ответ из Data Cache без обращения к БД.
3. Запрос T = 60c+ (Stale Window): Данные признаются устаревшими (stale). Next.js мгновенно отдает клиенту старые данные (TTFB не просаживается), но в отдельном фоновом воркере инициирует повторный запрос к источнику.
4. Запрос T = 62c+ (Cache Replaced): После успешного завершения фонового запроса кэш перезаписывается, и последующие пользователи получают актуализированную версию.

Паттерн 2: Кэширование в Next.js 16: директива 'use cache', cacheLife, cacheTag и unstable_cache#

В Next.js 16 на смену устаревшему unstable_cache пришла официальная парадигма Cache Components на базе директивы 'use cache'. Директива 'use cache' может применяться как к целым серверным компонентам, так и к отдельным асинхронным функциям уровня Data Access Layer (DAL).

Управление временем жизни и тегами кэша осуществляется декларативными функциями cacheLife() и cacheTag() из модуля next/cache:

import 'server-only';
import { cacheLife, cacheTag } from 'next/cache';
import { db } from '@/lib/db';
import { projects } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export interface ProjectDTO {
  id: string;
  name: string;
  stars: number;
}

// 1. Современный стандарт Next.js 16: 'use cache' на уровне функции
export async function getProjectById(projectId: string): Promise<ProjectDTO | null> {
  'use cache';
  cacheLife('hours'); // Пресет времени жизни: seconds, minutes, hours, days, max
  cacheTag(`project-${projectId}`, 'projects');

  const record = await db.query.projects.findFirst({
    where: eq(projects.id, projectId),
  });

  return record ?? null;
}

// 2. Использование 'use cache' напрямую на уровне Server Component
export async function ProjectWidget({ projectId }: { projectId: string }) {
  'use cache';
  cacheLife('days');
  cacheTag(`project-${projectId}`);

  const project = await getProjectById(projectId);
  if (!project) return null;

  return (
    <div className="p-4 rounded-xl border border-border">
      <h3 className="font-bold">{project.name}</h3>
      <span>Звезд: {project.stars}</span>
    </div>
  );
}

Для обратной совместимости со старыми кодовыми базами Next.js 14/15 функция unstable_cache по-прежнему поддерживается, но для всех новых модулей 2026 года стандартом является директива 'use cache'.

Паттерн 3: Opt-out и деоптимизация статического Full Route Cache#

Маршрут автоматически переключается из статического режима (Static Generation) в динамический (Dynamic Rendering при каждом запросе), если в его коде вызываются динамические API:

import { cookies, headers } from 'next/headers';

// Принудительное отключение Full Route Cache на уровне всего сегмента
export const dynamic = 'force-dynamic';

export default async function AnalyticsPage() {
  // Асинхронное чтение заголовков и cookies в Next.js 15+ делает рендер строго динамическим
  const headersList = await headers();
  const userAgent = headersList.get('user-agent') ?? 'unknown';

  const cookieStore = await cookies();
  const sessionId = cookieStore.get('sid')?.value;

  return (
    <main className="p-6">
      <h1>Системная аналитика</h1>
      <p>Клиент: {userAgent}</p>
      <p>Сессия: {sessionId}</p>
    </main>
  );
}

Распространённые ошибки#

// ❌ ОШИБКА: Попытка чтения cookies внутри кэшируемой функции
const getAuthData = unstable_cache(
  async () => {
    const cookieStore = await cookies(); // Вызовет исключение DynamicServerError!
    return fetchUserData(cookieStore.get('token')?.value);
  },
  ['auth-user-key']
);

// ✅ ПРАВИЛЬНО: Передавайте динамические данные в виде явных аргументов, входящих в ключ кэша
const getAuthData = (token: string) => 
  unstable_cache(
    async (authToken: string) => fetchUserData(authToken),
    ['auth-user-key', token]
  )(token);

// ❌ Ошибка: Ключ кэша статичен, поэтому все клиенты увидят данные пользователя с первым ID
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user'] 
);

// ✅ Правильно: ID включен в составной ключ кэша
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user', id]
);

Сравнительный анализ 4 уровней кэша#

Вопросы для собеседования#