Кэширование в Next.js 15: fetch без кэша по умолчанию, revalidateTag и unstable_cache
Что изменилось при переходе на 15
В Next.js 14 fetch в серверных компонентах по умолчанию кэшировался. В 15 это поведение перевернули:
fetchне кэшируется, если явно не указатьcache: 'force-cache'илиnext.revalidate.- GET-обработчики в Route Handlers не кэшируются по умолчанию.
- Клиентский Router Cache для страниц больше не держит сегменты по 30 секунд:
staleTimeдля динамических страниц равен нулю.
Типичная история после обновления: нагрузка на API или базу выросла, потому что каждый запрос страницы теперь ходит за данными. Или наоборот: данные вроде бы не кэшируются, а страница всё равно показывает старое.
Ловушка: нет кэша fetch, но страница статическая
Если маршрут не использует динамические API (cookies(), headers(), searchParams, connection()), Next.js пререндерит его при next build. Некэшированный fetch выполнится один раз во время сборки, и результат навсегда останется в HTML. В режиме разработки при этом всё выглядит динамическим, поэтому проблема всплывает только в продакшене.
Проверка — вывод next build: ○ означает статический маршрут, ƒ — динамический.
Явно сделать маршрут динамическим:
// app/dashboard/page.tsx
import { connection } from "next/server";
export default async function Page() {
await connection(); // дальше всё выполняется на каждый запрос
const stats = await fetch("https://api.example.com/stats").then((r) => r.json());
return <Stats data={stats} />;
}Или наоборот, сделать статический маршрут периодически обновляемым через export const revalidate = 300 в файле страницы.
Кэширование fetch с тегами
// lib/data/posts.ts
export async function getPosts() {
const res = await fetch("https://cms.example.com/posts", {
next: { revalidate: 3600, tags: ["posts"] },
});
if (!res.ok) throw new Error(`cms ${res.status}`);
return res.json() as Promise<Post[]>;
}
export async function getPost(slug: string) {
const res = await fetch(`https://cms.example.com/posts/${slug}`, {
next: { revalidate: 3600, tags: ["posts", `post:${slug}`] },
});
if (res.status === 404) return null;
return res.json() as Promise<Post>;
}revalidate: 3600 — запасной срок жизни. Основной механизм — инвалидация по тегу в момент изменения данных.
revalidateTag и revalidatePath
// app/admin/posts/actions.ts
"use server";
import { revalidatePath, revalidateTag } from "next/cache";
export async function publishPost(slug: string) {
await requireEditor(); // проверка прав — первой строкой
await cms.publish(slug);
revalidateTag(`post:${slug}`); // точечно: одна статья
revalidateTag("posts"); // списки, где она может быть
revalidatePath("/sitemap.xml");
}Разница между функциями:
revalidateTag(tag)помечает устаревшими все записи кэша данных с этим тегом, на каких бы страницах они ни использовались.revalidatePath(path)инвалидирует конкретный маршрут. Для динамического сегмента указывают шаблон и тип:revalidatePath("/blog/[slug]", "page")— все страницы статей,revalidatePath("/", "layout")— вообще всё.
Теги точнее: вы инвалидируете данные, а не угадываете, на каких URL они выводятся. revalidatePath удобен, когда данные пришли не через fetch (например, из базы без обёртки).
Обе функции работают в Server Actions и Route Handlers. Для вебхука из CMS сделайте Route Handler с проверкой секрета, который вызывает revalidateTag.
unstable_cache для запросов к базе
fetch кэшируется через next, а запрос к Postgres через ORM — нет. Для него есть unstable_cache:
// lib/data/stats.ts
import { unstable_cache } from "next/cache";
import { db } from "@/lib/db";
export const getCategoryCounts = unstable_cache(
async (locale: string) => {
const { rows } = await db.query(
"SELECT category, count(*)::int AS n FROM threads WHERE locale = $1 GROUP BY category",
[locale]
);
return rows;
},
["category-counts"], // часть ключа; аргументы добавляются автоматически
{ revalidate: 600, tags: ["threads"] }
);Ограничения: внутри функции нельзя вызывать cookies() и headers() — всё, что зависит от запроса, передавайте аргументами. Результат должен сериализоваться в JSON, поэтому объекты Date вернутся строками. Префикс unstable_ означает, что API может измениться. В Next.js 16 модель кэширования снова поменялась (директива use cache и изменения в revalidateTag), так что при обновлении сверяйтесь с документацией своей версии.
Как понять, что кэшируется
- 1.Включите логирование запросов в
next.config.ts:
const nextConfig = { logging: { fetches: { fullUrl: true } } };
export default nextConfig;В консоли сервера появятся строки с пометками о попадании в кэш или промахе для каждого fetch.
- 2.При self-hosted
next startсмотрите заголовок ответаx-nextjs-cache:HIT,STALEилиMISSдля страниц из кэша.
- 3.Проверяйте на сборке
next build && next start, а не вnext dev: в режиме разработки кэш ведёт себя иначе.
Типичные ошибки
- Ожидать, что
revalidateTagобновит данные, полученные без тега. Тег привязывается в момент запроса. - Инвалидировать из клиентского компонента. Функции из
next/cacheработают только на сервере. - Несколько инстансов
next startза балансировщиком. Кэш по умолчанию лежит в файловой системе каждого инстанса, иrevalidateTagна одном не затронет другие. Нужен общийcacheHandler(например, на Redis). - Кэшировать персональные данные под общим ключом. Если ответ зависит от пользователя, ID пользователя обязан быть частью ключа, а лучше такие данные не кэшировать вовсе.
Когда кэш не нужен
Админки, личные кабинеты и страницы с данными в реальном времени проще оставить полностью динамическими. Кэш оправдан там, где одни и те же данные читаются многими пользователями чаще, чем меняются.