Almacenamiento en caché en Next.js 15: recuperación sin caché predeterminado, revalidateTag y unstable_cache
¿Qué cambió al pasar a 15?
En Next.js 14, fetch en los componentes del servidor se almacenó en caché de forma predeterminada. En 15 este comportamiento se revirtió:
fetchno se almacena en caché a menos que especifique explícitamentecache: 'force-cache'onext.revalidate.- Los controladores GET en los controladores de ruta no se almacenan en caché de forma predeterminada.
- La caché del enrutador del cliente para páginas ya no contiene segmentos de 30 segundos:
staleTimepara páginas dinámicas es cero.
Una historia típica después de una actualización: la carga en la API o la base de datos ha aumentado porque cada solicitud de página ahora recupera datos. O viceversa: los datos no parecen estar almacenados en caché, pero la página aún muestra los antiguos.
Trampa: no se recupera caché, pero la página es estática
Si la ruta no utiliza API dinámicas (cookies(), headers(), searchParams, connection()), Next.js la renderizará previamente en next build. fetch sin caché se ejecutará una vez en el momento de la compilación y el resultado permanecerá en el HTML para siempre. En el modo de desarrollo, todo parece dinámico, por lo que el problema sólo aparece en producción.
Verificar: salida next build: ○ significa ruta estática, ƒ significa dinámica.
Haga explícitamente la ruta dinámica:
// 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} />;
}O viceversa, actualice periódicamente la ruta estática mediante export const revalidate = 300 en el archivo de la página.
Búsqueda de almacenamiento en caché con etiquetas
// 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 - vida útil adicional. El mecanismo principal es la invalidación de la etiqueta en el momento del cambio de datos.
revalidateTag y 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");
}Diferencia entre funciones:
revalidateTag(tag)marca como obsoletas todas las entradas de la caché de datos con esta etiqueta, sin importar en qué páginas se utilicen.revalidatePath(path)invalida una ruta específica. Para un segmento dinámico, se indican la plantilla y el tipo:revalidatePath("/blog/[slug]", "page")- todas las páginas de artículos,revalidatePath("/", "layout")- todo en general.
Las etiquetas son más precisas: invalidas los datos, en lugar de adivinar en qué URL aparecen. revalidatePath es conveniente cuando los datos no provienen de fetch (por ejemplo, de una base de datos sin contenedor).
Ambas funciones funcionan en Acciones del servidor y Controladores de ruta. Para un webhook desde un CMS, cree un controlador de ruta con una verificación secreta que llame a revalidateTag.
unstable_cache para consultas a la base de datos
fetch se almacena en caché a través de next, pero una solicitud a Postgres a través de ORM no. Existe unstable_cache para ello:
// 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"] }
);Restricciones: no puede llamar a cookies() y headers() dentro de una función; pase todo lo que dependa de la solicitud como argumentos. El resultado debe serializarse en JSON, por lo que los objetos Date se devolverán como cadenas. El prefijo unstable_ significa que la API puede cambiar. En Next.js 16, el modelo de almacenamiento en caché ha cambiado nuevamente (directiva use cache y cambios a revalidateTag), así que verifique la documentación de su versión al actualizar.
Cómo entender qué está en caché
- 1.Habilite el inicio de sesión de consultas en
next.config.ts:
const nextConfig = { logging: { fetches: { fullUrl: true } } };
export default nextConfig;La consola del servidor mostrará líneas que indican un acierto o error de caché para cada fetch.
- 2.Para
next startautohospedado, consulte el encabezado de respuestax-nextjs-cache:HIT,STALEoMISSpara páginas del caché.
- 3.Verifique la compilación
next build && next start, no ennext dev: en modo de desarrollo, el caché se comporta de manera diferente.
Errores comunes
- Espere que
revalidateTagactualice los datos recibidos sin una etiqueta. La etiqueta está vinculada en el momento de la solicitud. - Invalidar desde el componente cliente. Las funciones de
next/cachesolo funcionan en el servidor. - Varias instancias
next startdetrás del equilibrador. El caché predeterminado está en el sistema de archivos de cada instancia yrevalidateTagen uno no afectará a los demás. Necesita uncacheHandlergenérico (por ejemplo, en Redis). - Almacenar en caché los datos personales bajo una clave común. Si la respuesta depende del usuario, la identificación del usuario debe ser parte de la clave y es mejor no almacenar en caché dichos datos en absoluto.
Cuando el caché no es necesario
Es más fácil dejar los paneles de administración, las cuentas personales y las páginas con datos en tiempo real completamente dinámicos. Se justifica un caché cuando muchos usuarios leen los mismos datos con más frecuencia de la que cambian.