Zum Inhalt springen

WordPress als statische HTML ausliefern

Die meisten Seiten einer Marketing- oder Dokumentationswebsite sind für alle anonymen Besucher gleich. WordPress startet trotzdem, lädt jedes Plugin, führt das Theme aus und rendert die Blöcke bei jeder Anfrage. Ein Seiten-Cache-Plugin kann helfen, ist aber eine weitere Komponente mit eigenen Regeln dafür, was sicher gespeichert werden kann.

Blockstudio bietet optionales statisches Prerendering. Dabei werden vollständige HTML-Dokumente für anonyme Besucher in einem eigenen Cache-Verzeichnis gespeichert und, wenn du es erlaubst, über ein advanced-cache.php-Drop-in ausgeliefert, bevor WordPress startet. Alles wird in blockstudio.json konfiguriert.

Dieser Leitfaden aktiviert die Funktion Schritt für Schritt, zeigt, wie du prüfst, was im Cache landet, erklärt die eine Regel zum Schutz eingeloggter Besucher und endet mit einer CDN-Konfiguration, die nur Inhalte zwischenspeichert, die der Ursprung als cachebar kennzeichnet.

So wird eine Anfrage ausgeliefert

Ist das Prerendering aktiviert, endet eine geeignete Anfrage auf eine von drei Arten:

  1. Früher Treffer. Das Drop-in findet in seiner Routenkarte ein gespeichertes Dokument und sendet es, bevor WordPress geladen wird. Die Antwort enthält X-Blockstudio-Static-Prerender: HIT-EARLY.
  2. Treffer. WordPress startet, und bei template_redirect findet Blockstudio ein aktuelles gespeichertes Dokument und sendet es, statt das Template zu rendern. Die Antwort enthält X-Blockstudio-Static-Prerender: HIT.
  3. Kein Treffer. WordPress rendert die Seite wie gewohnt. Ist der Besucher anonym und das Ergebnis ein vollständiges HTML-Dokument mit Status 200, speichert Blockstudio es für die nächste Anfrage.

Nicht geeignete Anfragen greifen niemals auf den Cache zu.

Schritt 1: Profil und Cache aktivieren

Beginne mit dem Performance-Profil und Prerendering, aber ohne frühe Auslieferung:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "performance": {
    "profile": "speed",
    "staticPrerender": {
      "enabled": true,
      "ttl": 86400,
      "earlyServe": false,
      "dynamicPaths": ["/account", "/checkout", "/login"],
      "warm": {
        "enabled": true,
        "interval": 900,
        "concurrency": 4
      }
    }
  }
}

Aufgabe der einzelnen Teile:

  • profile: "speed" aktiviert die Produktionsstandards für das Frontend: Überflüssiges im Head, oEmbed-Erkennung, XML-RPC und allgemeine Core-Frontend-Assets werden entfernt; Links derselben Domain werden bei Interaktionsabsicht vorab geladen. Entfernte Core-Frontend-Assets solltest du zuerst testen, da Seiten, die davon abhängen, sichtbar beeinträchtigt werden. Jeder untergeordnete Wert überschreibt das Profil.
  • staticPrerender.enabled registriert die Laufzeitumgebung. Solange sie false ist, schreibt die Funktion keine Dateien und registriert keine Anfrage-Hooks.
  • ttl ist das Höchstalter eines gespeicherten Dokuments in Sekunden (Standardwert 86400).
  • dynamicPaths listet Pfadpräfixe auf, die immer live gerendert werden müssen.
  • warm plant einen Hintergrund-Wärmer, der veraltete öffentliche URLs alle interval Sekunden neu rendert.

Die Zeile $schema deckt alle Schlüssel ab. Ein Editor mit JSON-Schemaunterstützung markiert daher Fehler wie "ttl": 0 (der Mindestwert ist 1).

Schritt 2: Wissen, welche Anfragen geeignet sind

Blockstudio speichert vorsichtshalber nur ausgewählte Inhalte. Diese Anfragen umgehen den Cache immer:

  • alles außer GET
  • jedes URL mit Query-String
  • wp-admin, wp-json, wp-login.php, xmlrpc.php, Ajax und cron
  • Feeds, Suche und Vorschaubereiche
  • Anfragen mit einem X-WP-Nonce-Header
  • Pfade unter dynamicPaths
  • Besucher mit einem wordpress_logged_in_*-, wp-postpass_*– oder comment_author_email_*-Cookie, sofern serveLoggedIn nicht aktiviert ist

Dynamische Pfade werden anhand von Pfadgrenzen abgeglichen. Bei der obigen Konfiguration gilt:

Anfrage Umgangen
/pricing/ nein
/account/orders/ ja
/accounting/ nein
/checkout ja
/pricing/?utm_source=x ja
/blog/feed/ ja

Gespeichert werden nur vollständige Dokumente: Die Antwort muss mit <!doctype html oder <html beginnen, den Status 200 haben und darf die Opt-out-Markierung nicht enthalten. Ein Template, das niemals gespeichert werden soll, kann die Markierung an beliebiger Stelle auf der Seite ausgeben:

HTML
<!-- blockstudio:no-cache -->

Fehlerseiten werden nie gespeichert. Eine gestaltete 404-Seite kann daher niemals erneut als erfolgreiche Antwort ausgeliefert werden.

Schritt 3: Treffer überprüfen

Rufe einige Seiten in einem privaten Fenster auf und frage dann Blockstudio nach dem Cache-Inhalt:

Shell
wp bs prerender status
JSON
{
    "enabled": true,
    "invalidate": "signature",
    "identity": "e6cdd3fcda14ad6ded85a763bd01a33b",
    "cacheRoot": ".../wp-content/blockstudio/cache/sites/.../static-prerender",
    "files": 0,
    "bytes": 0,
    "records": 0,
    "queue": {
        "pending": 0,
        "processing": 0,
        "done": 0,
        "unique": 0,
        "bytes": 0
    },
    ...
    "diagnostics": []
}

files und bytes wachsen, wenn Dokumente gespeichert werden. queue zeigt die Warteschlange des Wärmers, und diagnostics enthält Treffer-, Fehlschlag-, Build- und Fehlerzähler für jeden Bereich. Um eine einzelne Seite zu prüfen, rufe sie als anonymer Besucher zweimal auf und suche nach dem Header:

Shell
curl -s -o /dev/null -D - https://example.com/pricing/ | grep -i x-blockstudio-static-prerender

Die zweite Antwort enthält X-Blockstudio-Static-Prerender: HIT. Verwende wie oben ein GET: curl -I sendet eine HEAD-Anfrage, die den Cache immer umgeht.

Schritt 4: Vor dem Start von WordPress ausliefern

Wenn Treffer wie erwartet aussehen, setze "earlyServe": true. Blockstudio verwaltet dann drei kleine Zustandskomponenten: ein wp-content/advanced-cache.php-Drop-in, eine gemeinsame wp-content/blockstudio-static-prerender-map.php-Routenkarte und eine Deklaration von WP_CACHE in wp-config.php. Sie werden bei der nächsten Admin-Anfrage installiert.

Einige Regeln sorgen dafür, dass dies auf gemeinsamem Hosting und in Multisite sicher bleibt:

  • Blockstudio überschreibt kein Drop-in, keine Map und keine WP_CACHE-Zeile, für die es nicht zuständig ist. Gehört advanced-cache.php bereits einem anderen Cache-Plugin, bleibt die frühe Auslieferung deaktiviert.
  • Wenn WP_CACHE bereits als true definiert ist, bleibt wp-config.php unverändert. Auf Hostern, auf denen wp-config.php nicht beschreibbar ist, musst du es selbst definieren.
  • Vor der Auslieferung prüfen sowohl das Drop-in als auch der Pfad PHP, ob das Dokument verknüpfte, inhaltlich gehashte Tailwind-Stylesheet noch vorhanden ist. Fehlt es, wird die Anfrage an WordPress weitergeleitet, statt das Dokument ohne Stylesheet auszuliefern.
  • Multisite-Einträge verwenden dieselbe Map, sind aber nach Host, Home-Pfad und Website-ID voneinander getrennt.
  • In replayHeaders genannte Response-Header, standardmäßig Link, werden zusammen mit jedem Dokument gespeichert und bei jedem Aufruf erneut gesendet. So bleibt ein Link-Header erhalten, den eine Seite mit header() sendet, wenn sie früh ausgeliefert wird. Cookie- und Cache-Header werden nie erneut ausgegeben.

Frühe Treffer enthalten X-Blockstudio-Static-Prerender: HIT-EARLY. Wird earlyServe oder enabled deaktiviert, entfernt das den von Blockstudio verwalteten Zustand einmalig; wp bs teardown entfernt ihn ausdrücklich bei Composer-Installationen ohne Deaktivierungs-Hook.

Eingeloggte Besucher und identisches Markup

Standardmäßig erhalten eingeloggte Besucher immer eine Live-Ausgabe. Mit "serveLoggedIn": true können sie auch ein vorhandenes gespeichertes Dokument abrufen. Dadurch ist die Website für Redakteure und Kunden genauso schnell wie für anonyme Besucher.

Personalisierte Antworten erzeugen niemals Cache-Einträge: Bei einem Cache-Fehltreffer wird für eingeloggte Nutzer live gerendert und nichts gespeichert. Die Folge wird leicht übersehen. Wenn serveLoggedIn aktiviert ist, erhalten eingeloggte Besucher das anonyme Dokument, sofern eines vorhanden ist, und nur andernfalls eine personalisierte Live-Ausgabe. Template-Zweige, die vom aktuellen Nutzer abhängen, erscheinen daher nur bei Fehltreffern. Dieselbe Seite ändert sich zwischen Besuchen, und der personalisierte Zweig bleibt auf Cache-Routen praktisch wirkungslos.

Daraus folgt: Auf jeder Route außerhalb von dynamicPaths muss das Markup für eingeloggte und anonyme Besucher byte-identisch sein. Daher dürfen Templates, die auf statischen Routen gerendert werden, keine is_user_logged_in()– oder wp_get_current_user()-Zweige enthalten:

PHP
<?php // Do not do this on a static route. ?>
<?php if ( is_user_logged_in() ) : ?>
  <a href="/account/">Hi, <?php echo esc_html( wp_get_current_user()->display_name ); ?></a>
<?php else : ?>
  <a href="/login/">Sign in</a>
<?php endif; ?>

Es gibt zwei einfache Lösungen. Verschiebe die Route nach dynamicPaths, wenn die ganze Seite personalisiert ist, etwa ein Konto-Dashboard. Oder behalte die statische Seite und rendere den persönlichen Teil als dynamische Block-Insel. Diese liefert im gespeicherten HTML einen cache-sicheren Platzhalter aus und ruft das echte Fragment in der Anfrage des Besuchers ab:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Der Leitfaden Personalisierte Fragmente auf gecachten Seiten erstellt diesen Block.

Signatur- oder Graph-Invalidierung

invalidate legt fest, wie gespeicherte Dokumente ablaufen.

Aspekt signature (Standard) graph
Wer den Cache füllt anonyme Fehltreffer und der Wärmer dein Build-Schritt sowie anonyme Fehltreffer
Was Einträge ablaufen lässt TTL, Speichern von Beiträgen, Änderungen auf Website-Ebene ein neuer Build; TTL als Obergrenze
Hintergrund-Wärmer verfügbar deaktiviert
Geeignet für gewöhnliche Websites Websites mit Deployment-Pipeline

Der Modus signature benötigt keine zusätzlichen Tools. Beim Speichern eines Beitrags wird der Cache für die Startseite und den Permalink dieses Beitrags geleert oder neu aufgewärmt. Änderungen auf Website-Ebene, etwa ein Theme-Wechsel, setzen die Cache-Identität zurück.

graph-Modus ist für deterministische Deployments gedacht. Ein Build berechnet mit Static_Prerender_Runtime::build_plan() einen Plan, rendert nur die betroffenen URLs, protokolliert jedes Ergebnis und aktiviert den fertigen Satz atomar mit Static_Prerender_Early_Serve::install_artifact_entry(). Schlägt die Validierung eines referenzierten Dokuments fehl, bleibt der vorherige Satz aktiv. Zugeordnete Routen werden bis zum nächsten Build, der sie ersetzt, aus dem aktivierten Artefakt bereitgestellt. Inhalte, die du in wp-admin bearbeitest, erreichen diese Routen also mit dem nächsten Deployment. Der Warmer pro URL ist in diesem Modus deaktiviert, weil Artefakte als Einheit erstellt und aktiviert werden. Ein typischer Aufbau für die Produktion sieht so aus:

JSON
{
  "performance": {
    "profile": "speed",
    "staticPrerender": {
      "enabled": true,
      "invalidate": "graph",
      "ttl": 2592000,
      "earlyServe": true,
      "serveLoggedIn": true,
      "dynamicPaths": [
        "/account",
        "/cart",
        "/checkout",
        "/login",
        "/reset-password"
      ]
    }
  }
}

Die 30-Tage-ttl begrenzt lediglich, wie alt ein bereitgestelltes Dokument sein darf. Aktualität entsteht durch das Deployment, das den Graph neu erstellt. Der Build-API, das Sharding und der interne Render-Transport werden in der Referenz zum statischen Prerendering behandelt.

Einen CDN davorschalten

Das Prerendering zeigt bereits, welche Antworten sicher geteilt werden können: genau die, die einen HIT-Header enthalten. Lass den Origin daraus einen Cache-Header machen und den CDN dem Origin folgen. Mit nginx vor PHP-FPM:

Nginx
map $upstream_http_x_blockstudio_static_prerender $edge_cache_control {
    "~^HIT"  "public, s-maxage=604800";
    default  "";
}

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php-fpm.sock;
        add_header Cache-Control $edge_cache_control;
    }
}

Der reguläre Ausdruck erfasst sowohl HIT als auch HIT-EARLY. Bei allen anderen Antworten ist die Variable leer. nginx fügt keinen Header mit leerem Wert hinzu. Daher erhalten nicht gefundene Seiten, dynamische Pfade und angemeldete Nutzer beim Rendering keine gemeinsame Cache-Lebensdauer vom Origin.

Auf der CDN-Seite:

  • Cache HTML nur, wenn der Origin eine Cache-Lebensdauer sendet. Deaktiviere eine Standard-TTL am Edge für Antworten ohne eine solche Angabe.
  • Umgehe den Edge für dieselben Cookies, die Blockstudio als persönlich behandelt (wordpress_logged_in_, wp-postpass_, comment_author_email_), sowie für deine dynamicPaths, wp-admin und wp-json.
  • Leere den CDN nach jedem Deployment, das Seiten, Vorlagen oder Assets ändert. Der Origin-Cache erneuert sich selbst; der Edge weiß nicht, dass er erneuert werden muss.

Wenn du Tailwind mit "output": "link" verwendest, ist das Stylesheet URL inhaltsgehasht. Daher kann dieser Pfad mit einem langlebigen, unveränderlichen Cache-Header bereitgestellt werden.

Wartungsbefehle

Shell
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs teardown

warm nimmt veraltete öffentliche URLs in die Warteschlange und rendert pro Durchlauf bis zu warm.concurrency davon; dabei wird eine Zusammenfassung mit JSON ausgegeben. purge entfernt die gespeicherten Dokumente und die Warteschlange der aktuellen Website. teardown entfernt die cron-Ereignisse und den Status für frühes Bereitstellen, die dieser Installation gehören, und lässt Konfigurationsdateien unangetastet.

Führe die Einführung in dieser Reihenfolge durch: zuerst das Profil, dann das Prerendering mit deaktiviertem earlyServe und schließlich das frühe Bereitstellen, sobald status und die Header stimmen. Jede Ebene lässt sich einzeln zurücksetzen, indem du ihren Wert zurückstellst.

Nächste Schritte