Next.js

Cache Rocket para Next.js es un paquete CDN de imagen + CDN `/_next/static` opcional + calentamiento de caché que se encuentra junto a su host existente.Mantienes SSR y HTML donde están (Vercel, Netlify, Cloudflare Pages o tu propio host de Nodo).Cache Rocket optimiza y entrega imágenes, puede servir JS/CSS con hash desde CDN administrada y puede calentar URL después de cada implementación.

1. Cree un sitio Next.js#

En el panel, abra Cuenta → Next.js , cree un sitio para su nombre de host y copie el token del sitio, el ID del sitio y las claves API.Agregue entradas de la lista de hosts de imágenes permitidas para cada origen desde el que cargue imágenes (el nombre de host de su sitio siempre se incluye).

2. Instale el paquete#

@cacherocket/next está publicado en el registro público de npm:

npm i @cacherocket/next

3. Variables ambientales#

# Public — safe in the browser / image URLs
CACHEROCKET_SITE_TOKEN=site_xxx
# Absolute origin for relative /public images (optional but recommended)
CACHEROCKET_ASSET_ORIGIN=https://www.example.com

# Optional — customer static CDN (/_next/static) from Account → Next.js
# Do not use CacheRocket.com's internal CACHEROCKET_CDN_URL
CACHEROCKET_STATIC_CDN_URL=https://assets.cacherocket.com/org_…/site_…/static

# Server-only — warm / purge / deploy / static upload
CACHEROCKET_PUBLIC_KEY=...
CACHEROCKET_SECRET_KEY=...
CACHEROCKET_SITE_ID=...

4. Envuelva next.config#

import type { NextConfig } from 'next'
import { withCacheRocket } from '@cacherocket/next'

const nextConfig: NextConfig = {
  // your config
}

export default withCacheRocket(
  {
    siteToken: process.env.CACHEROCKET_SITE_TOKEN,
    assetOrigin: process.env.CACHEROCKET_ASSET_ORIGIN,
    staticCdnUrl: process.env.CACHEROCKET_STATIC_CDN_URL,
  },
  nextConfig
)

5. Utilice siguiente/imagen como de costumbre#

Prefiere URL de imágenes absolutas o rutas relativas cuando se configura CACHEROCKET_ASSET_ORIGIN.El cargador reescribe las solicitudes de URL de transformación basadas en rutas en img.cacherocket.com:

https://img.cacherocket.com/i/site_xxx/w_1200,q_75,f_auto/https%3A%2F%2F...

6. Opcional: CDN de activos estáticos ( `/_next/static` )#

Para aplicaciones Next.js autohospedadas o que no sean de Vercel (o cuando desee eliminar JS/CSS de su origen), habilite CDN de activos estáticos en Cuenta → Next.js .Esto requiere CDN administrado en su plan.Cache Rocket almacena los resultados de compilación en OVH en la ruta de su inquilino y los entrega desde Bunny en assets.cacherocket.com.HTML y SSR permanecen en su host.

Copie staticCdnUrl en CACHEROCKET_STATIC_CDN_URL (nunca el CACHEROCKET_CDN_URL interno de CacheRocket .com).Después de cada next build, cargue los recursos:

npx cacherocket-next upload-static

import { uploadStatic } from '@cacherocket/next/server'

await uploadStatic()

7. Caliente al implementar#

Agregue un controlador de ruta y apúntelo con un gancho de implementación de Vercel (o un webhook equivalente):

import { onVercelDeploy } from '@cacherocket/next/server'

export const POST = onVercelDeploy()

O llame a ayudantes desde un script o paso de CI:

import { warm, purge } from '@cacherocket/next/server'

await warm({ urls: ['https://www.example.com/'] })
await purge({ rewarm: true })

Las URL de webhook de plataforma sin el paquete npm se tratan en [Disparadores de implementación] (/documentation/deploy-triggers).

Exportaciones de paquetes#

Problemas comunes#

Las imágenes todavía pasan por /_next/image en mi host.

Confirme que withCacheRocket envuelve su configuración exportada y que CACHEROCKET_SITE_TOKEN esté configurado en el momento de la compilación.Vuelva a implementar después de cambiar las variables de entorno.

Veo "Token de sitio desconocido o inactivo".

El token en la URL de la imagen no coincide con un sitio Next.js activo.Copie el token del sitio actual de Cuenta → Next.js y vuelva a implementarlo.

Las imágenes remotas devuelven un error o vuelven a la URL original.

Agregue el nombre de host de la imagen a la lista de sitios permitidos.Solo se pueden optimizar los orígenes incluidos en la lista permitida.La falla suave en la URL original también ocurre cuando se excede la cuota del plan.

Las imágenes relativas /public no se optimizan.

Configure CACHEROCKET_ASSET_ORIGIN (o el origen de su sitio público) para que Cache Rocket pueda resolver una URL de recuperación absoluta.

La alternancia de CDN estática dice que mi plan no incluye CDN administrada.

La entrega estática /_next/static utiliza CDN administrado (assets.cacherocket.com) y requiere un plan con allowCdn.Image CDN en Free todavía funciona a través de img.cacherocket.com.

/_next/static 404 de la CDN después de la implementación.

Habilite la CDN estática en el sitio, configure CACHEROCKET_STATIC_CDN_URL, vuelva a implementar para que se aplique assetPrefix y luego ejecute npx cacherocket-next upload-static después de next build.

El calentamiento de implementación nunca se ejecuta.

Confirme que el webhook llegue a su ruta /api/cacherocket/deploy (o al webhook de implementación pública), que las claves API de solo servidor y CACHEROCKET_SITE_ID estén configuradas y que el nombre de host coincida con un calentador activo.Consulte Implementar desencadenadores.

¿Necesitar ayuda?#

Abra Cuenta → Soporte y elija la categoría Next.js, o comience desde Solución de problemas.Incluya el ID de su sitio, la versión del paquete y si el problema es la entrega de imágenes o el calentamiento de la implementación.