Next.js

Cache Rocket für Next.js ist ein Image-CDN + optionales `/_next/static`-CDN + Cache-Warming-Paket, das sich neben Ihrem vorhandenen Host befindet.Sie behalten SSR und HTML dort, wo sie sind (Vercel, Netlify, Cloudflare Pages oder Ihr eigener Node-Host).Cache Rocket optimiert und liefert Bilder, kann gehashtes JS/CSS vom verwalteten CDN bereitstellen und kann URLs nach jeder Bereitstellung erwärmen.

1. Erstellen Sie eine Next.js-Site#

Öffnen Sie im Dashboard Konto → Next.js , erstellen Sie eine Site für Ihren Hostnamen und kopieren Sie das Site-Token, die Site-ID und die API-Schlüssel.Fügen Sie für jeden Ursprung, von dem Sie Bilder laden, Einträge zur Bildhost-Zulassungsliste hinzu (Ihr Site-Hostname ist immer enthalten).

2. Installieren Sie das Paket#

@cacherocket/next ist in der öffentlichen NPM-Registrierung veröffentlicht:

npm i @cacherocket/next

3. Umgebungsvariablen#

# 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. Wrappen Sie 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. Verwenden Sie next/image wie gewohnt#

Bevorzugen Sie absolute Bild-URLs oder relative Pfade, wenn CACHEROCKET_ASSET_ORIGIN festgelegt ist.Der Loader schreibt Anfragen in pfadbasierte Transformations-URLs auf img.cacherocket.com um:

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

6. Optional: statisches Asset-CDN (`/_next/static`)#

Aktivieren Sie für selbst gehostete oder nicht von Vercel stammende Next.js-Apps (oder wenn Sie gehashtes JS/CSS von Ihrem Ursprung haben möchten) Statisches Asset-CDN auf Konto → Next.js .Dies erfordert Managed CDN in Ihrem Plan.Cache Rocket speichert die Build-Ausgabe in OVH unter Ihrem Mandantenpfad und stellt sie von Bunny auf assets.cacherocket.com bereit.HTML und SSR bleiben auf Ihrem Host.

Kopieren Sie staticCdnUrl in CACHEROCKET_STATIC_CDN_URL (niemals CacheRocket .coms internes CACHEROCKET_CDN_URL).Laden Sie nach jedem next build Assets hoch:

npx cacherocket-next upload-static

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

await uploadStatic()

7. Beim Einsatz erwärmen#

Fügen Sie einen Route-Handler hinzu und richten Sie einen Vercel Deploy Hook (oder einen gleichwertigen Webhook) darauf:

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

export const POST = onVercelDeploy()

Oder rufen Sie Helfer über ein Skript oder einen CI-Schritt an:

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

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

Plattform-Webhook-URLs ohne das npm-Paket werden unter Trigger bereitstellen behandelt.

Paketexporte#

Häufige Probleme#

Bilder laufen immer noch über /_next/image auf meinem Host.

Bestätigen Sie, dass withCacheRocket Ihre exportierte Konfiguration umschließt und dass CACHEROCKET_SITE_TOKEN zum Zeitpunkt der Erstellung festgelegt wird.Nach Änderung der Umgebungsvariablen erneut bereitstellen.

Ich sehe „Unbekanntes oder inaktives Site-Token“.

Das Token in der Bild-URL stimmt nicht mit einer aktiven Next.js-Site überein.Kopieren Sie das aktuelle Site-Token von Konto → Next.js und stellen Sie es erneut bereit.

Remote-Bilder geben einen Fehler zurück oder greifen auf die ursprüngliche URL zurück.

Fügen Sie den Hostnamen des Bildes zur Site-Zulassungsliste hinzu.Nur zugelassene Ursprünge können optimiert werden.Ein Soft-Fail zur ursprünglichen URL kommt auch dann vor, wenn Ihr Plankontingent überschritten ist.

Relative /public-Bilder können nicht optimiert werden.

Legen Sie CACHEROCKET_ASSET_ORIGIN (oder den Ursprung Ihrer öffentlichen Website) fest, damit Cache Rocket eine absolute Abruf-URL auflösen kann.

Beim Umschalten zwischen statischem CDN wird angezeigt, dass mein Plan kein verwaltetes CDN beinhaltet.

Die statische /_next/static-Bereitstellung verwendet Managed CDN (assets.cacherocket.com) und erfordert einen Plan mit allowCdn.Image CDN auf Free funktioniert weiterhin über img.cacherocket.com.

/_next/static 404s vom CDN nach der Bereitstellung.

Aktivieren Sie statisches CDN auf der Site, legen Sie CACHEROCKET_STATIC_CDN_URL fest, stellen Sie es erneut bereit, damit assetPrefix angewendet wird, und führen Sie dann npx cacherocket-next upload-static nach next build aus.

Deploy Warming wird nie ausgeführt.

Bestätigen Sie, dass der Webhook Ihre /api/cacherocket/deploy-Route (oder den öffentlichen Bereitstellungs-Webhook) erreicht, dass die Nur-Server-API-Schlüssel und CACHEROCKET_SITE_ID festgelegt sind und dass der Hostname mit einem aktiven Warmer übereinstimmt.Siehe Trigger bereitstellen.

Brauchen Sie Hilfe?#

Öffnen Sie Konto → Support und wählen Sie die Kategorie Next.js oder beginnen Sie mit Fehlerbehebung.Geben Sie Ihre Site-ID und die Paketversion an und geben Sie an, ob es sich bei dem Problem um die Bildbereitstellung oder die Bereitstellungserwärmung handelt.