Zum Inhalt springen

Statisches Vorab-Rendering

Statisches Vorab-Rendering ist ein optionaler anonymer HTML-Cache. Eine cachefähige Antwort muss ein vollständiges HTML-Dokument sein und kann mit <!-- blockstudio:no-cache --> ausgeschlossen werden. Blockstudio umgeht Nicht-GET-Anfragen, Query-Strings, den WordPress-Adminbereich, REST, Ajax, cron, Feeds, Suchergebnisse unterhalb der Suchbasis am Home-Pfad der Website (zum Beispiel /search/term/), Vorschau- und Canvas-Header, Anfragen mit Nonce, deklarierte dynamische Pfade, Passwort-/Kommentar-Cookies sowie standardmäßig angemeldete Anfragen. Eine Seite, deren Pfad nur weiter unten ein Segment search oder preview enthält, etwa /docs/blocks/preview/, wird wie jede andere Seite zwischengespeichert.

JSON
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "invalidate": "graph",
      "earlyServe": true,
      "serveLoggedIn": false,
      "dynamicPaths": ["/account", "/checkout"],
      "replayHeaders": ["Link"],
      "warm": {
        "enabled": true,
        "interval": 900,
        "concurrency": 4,
        "transport": "http"
      }
    }
  }
}

Angemeldete Benutzer können einen vorhandenen Treffer nur verwenden, wenn serveLoggedIn wahr ist. Personalisierte Antworten erzeugen niemals Cache-Einträge. Dynamische Pfade werden anhand von Pfadgrenzen abgeglichen: /account stimmt mit /account/orders überein, aber nicht mit /accounting.

Solange die Funktion deaktiviert ist, werden keine Dateien geschrieben, kein Drop-in installiert und keine Anfrage- oder Admin-Hooks registriert. Ebenso registriert earlyServe: false keinen Early-Serve-Admin-Callback, und warm.enabled: false registriert weder einen cron-Callback noch einen Zeitplan. Beim Deaktivieren einer der beiden Funktionen wird der zuvor zugehörige Status einmal entfernt. Nachfolgende Anfragen führen keine Dateisystem- oder cron-Bereinigungsprüfungen durch.

In einer Umgebung deaktivieren

Jeder Wert oben kann auch über einen Einstellungsfilter festgelegt werden. Blockstudio wird vor dem aktiven Theme geladen, durch ein Plugin oder den Composer-Autoloader des Themes, sodass es seine Laufzeiteinstellungen erneut auflöst, sobald das Theme geladen ist, und die statischen Prerender-Hooks bei after_setup_theme festlegt. Ein Filter, der durch ein Plugin oder in der functions.php des Themes hinzugefügt wird, greift daher:

PHP
add_filter('blockstudio/settings/performance/staticPrerender/enabled', function ($enabled) {
    return 'local' === wp_get_environment_type() ? false : $enabled;
});

Das Feature auf diese Weise zu deaktivieren, funktioniert wie die Deaktivierung in blockstudio.json: Es werden keine Hooks für Anfragen, Inhalte, den Admin-Bereich oder cron registriert, und ein zuvor früh ausgelieferter Aufruf wird einmalig aus dem Early-Serve-Eintrag entfernt. Ein später hinzugefügter Filter, etwa bei init, ändert nicht, welche Hooks registriert werden.

Signatur- und Graph-Modi

Der Modus signature füllt bei einem normalen anonymen Cache-Miss eine identitätsgebundene Antwort. Er ist praktisch für gewöhnliche WordPress-Websites und wird nach Änderungen auf Website-Ebene erneuert.

Der Modus graph ist für deterministische Build-/Deploy-Integrationen gedacht. Rufe Static_Prerender_Runtime::build_plan() mit den Live-Quell-URLs auf, rendere nur affectedUrls und speichere anschließend jedes Ergebnis mit persist_built_response() oder persist_skipped_response(). Der Plan vergleicht gemeinsame Dateien und die exakten Abhängigkeits-Hashes jeder Seite. Gelöschte URLs und nicht referenzierte HTML werden durch garbage_collect() entfernt.

PHP
use Blockstudio\Static_Prerender_Runtime;

$plan = Static_Prerender_Runtime::build_plan($sourceUrls);

foreach ($plan['affectedUrls'] as $url) {
    $result = render_with_dependencies($url);

    Static_Prerender_Runtime::persist_built_response(
        $url,
        $result['html'],
        $result['files'],
        $result['virtualHashes']
    );
}

$targets = array_keys($plan['live']);
Static_Prerender_Runtime::garbage_collect($targets);

Optionale Argumente für Ziel-Host und Startseite schreiben Routen für ein Deployment um, ohne den Pfad der ersten Seite als Website-Stamm zu verwenden. Batch-Werkzeuge können Static_Prerender_Batch_Renderer::render() und stabile N/TOTAL-Shards verwenden; Static_Prerender_Batch_Renderer::parse_shard() und select_shard() unterstützen die Shard-Option, sodass ein Aufrufer dieselbe Partition wie der Renderer berechnen kann. Während eines Builds gibt Static_Prerender_Batch_Renderer::is_rendering() an, ob die aktuelle Anfrage ein Batch-Render statt eines Besucheraufrufs ist, damit ein Template Arbeit überspringen kann, die während eines Builds nicht ausgeführt werden soll. Ein internal-Transport wird über den generischen Filter blockstudio/static_prerender/render_internal bereitgestellt; der optionale Fallback HTTP verwendet den normalen Warm-Header.

Was der Graph-Modus erfasst

Beim standardmäßigen Transport HTTP sendet Static_Prerender_Batch_Renderer::render() jeder Warm-Anfrage ein signiertes Token, und die Anfrage meldet die gelesenen Dateien: das geladene Template WordPress, das Template jedes gerenderten Blockstudio-Blocks, Template-Dateien und Asset-Dateien, über blockstudio/render/dependencies hinzugefügte Dateien sowie bei einer synchronisierten Seite deren Definitions-, Template-, Inhalts- und Layoutdateien. Der Bericht wird im Cache-Verzeichnis der Website gespeichert, das Renderer und Webserver bereits für das gerenderte HTML gemeinsam nutzen. Beim nächsten Build hasht build_plan() diese Dateien erneut und markiert nur die Routen, deren Dateien sich geändert haben, sowie neue Routen, Routen jenseits ihres ttl und alle Routen, wenn sich eine gemeinsame Datei ändert (blockstudio.json, theme.json, style.css, functions.php, header.php, footer.php, alles unter inc/, parts/ und templates/ sowie die Quellen der gebündelten UI-Assets von Blockstudio). Die gemeinsame Signatur hasht Quellen, niemals kompilierten Output. Daher ändern die _dist-Dateien, die der erste Render eines Builds kompiliert, sie nicht: artifact_entry() leitet die Build-ID aus derselben Signatur ab, die build_plan() vor dem Rendern ermittelt hat.

Inhalte, die nur in der Datenbank liegen, sind keine Dateien und werden nicht erfasst: Beiträge, die im Admin-Bereich bearbeitet wurden, Optionen, generierte Zeilen oder Preise. Ein Build, der solche Änderungen übernehmen muss, übergibt $force an build_plan() oder rendert die betroffenen URLs selbst. Der Transport internal erfasst die Abhängigkeiten, die sein Filter zurückgibt.

Frühe Auslieferung und atomisches Deployment

Wenn earlyServe aktiviert ist, verwaltet Blockstudio ein kleines wp-content/blockstudio-static-prerender-map.php, ein advanced-cache.php-Drop-in und eine genaue WP_CACHE-Deklaration. Das Drop-in liest eine Routenzuordnung pro Website und streamt einen geeigneten Treffer aus, bevor WordPress, Plugins oder das Theme geladen werden.

Blockstudio überschreibt niemals eine fremde Zuordnung, ein fremdes Drop-in oder eine fremde WP_CACHE-Deklaration. Graph-Artefakte validieren jede referenzierte HTML-Datei, bevor die Zuordnung ausgetauscht wird; bei einem Validierungsfehler bleibt der vorherige Graph aktiv. Multisite-Einträge teilen sich die Zuordnung, sind jedoch nach Host, Startpfad und Website-ID voneinander getrennt. Wird das Feature deaktiviert oder Blockstudio deaktiviert, wird nur der Eintrag der aktuellen Website entfernt. Gemeinsame Artefakte werden erst entfernt, wenn der letzte eigene Eintrag gelöscht ist.

Deployment-Werkzeuge können einen vollständig gerenderten Graph atomar aktivieren:

PHP
$entry = Static_Prerender_Runtime::artifact_entry($targetUrls);

Blockstudio\Static_Prerender_Early_Serve::install_artifact_entry(
    $entry,
    Static_Prerender_Runtime::cache_root_path()
);

Die Konfiguration bleibt maßgeblich. install_artifact_entry() gibt false zurück, sofern nicht sowohl enabled als auch earlyServe wahr sind. So kann ein Deployment niemals eine Zuordnung, ein Drop-in und eine WP_CACHE-Deklaration installieren, die die nächste Admin-Anfrage wieder entfernen würde.

install_artifact_entry() behält die build_id des Eintrags bei, sodass ein Deployment sie mit dem Eintrag vergleichen kann, den installed_map_entries() anschließend zurückgibt. Die Zuordnung ist eine PHP-Datei, die mit include gelesen wird, und bei jedem Schreibvorgang aus dem Opcode-Cache entfernt wird. Dadurch sieht dieser Lesevorgang im selben Prozess den neuen Eintrag, selbst wenn opcache.enable_cli aktiviert ist.

Bei der Installation eines Artefakts werden dessen Dokumente in einen eigenen Artefaktbereich übernommen, den die Aufbewahrungsbereinigung nie anfasst. Dateien, auf die die Zuordnung verweist, sind unabhängig von ihrem Speicherort vor dem Entfernen geschützt, sodass Live-Render-Aufrufe zugeordnete Routen nicht aus der frühen Auslieferung verdrängen können. Ein Routenschlüssel ist nicht vollständig inhaltsadressiert; ein erneutes Rendern kann daher ein Dokument ändern, ohne dessen Schlüssel zu ändern. Bei der Installation werden die Bytes verglichen und abweichende Artefaktdokumente atomar ersetzt. Identische Dokumente bleiben unberührt, ebenso Artefaktdokumente, deren Speicherkopie verschwunden ist. Static_Prerender_Early_Serve::last_promotion() meldet, wie viele Routen bei der letzten Installation übernommen, ersetzt, übersprungen oder beibehalten wurden, damit ein Deployment dies protokollieren kann.

Ein gespeichertes Dokument bindet die Build-Assets, auf die es über URL verweist. Diese Dateien haben ihre eigene Aufbewahrungsdauer, sodass eine länger bestehen kann als die andere. Vor der Auslieferung prüfen sowohl der PHP-Cache als auch das Drop-in, ob ein verknüpftes Tailwind-Stylesheet mit Inhalts-Hash noch auf dem Datenträger vorhanden ist. Fehlt das Stylesheet eines Dokuments, wird es an WordPress weitergeleitet, statt ohne Stylesheet ausgeliefert zu werden; dadurch werden Stylesheet und Dokument gemeinsam neu veröffentlicht. Dieselbe Prüfung erfolgt vor dem Speichern einer Antwort, sodass ein Dokument, das nicht ausgeliefert werden könnte, niemals geschrieben wird.

Eine Anfrage, deren Accept-Header text/markdown enthält, umgeht sowohl den PHP-Store als auch das Drop-in, weil gespeicherte Dokumente HTML sind und eine Seite diese Anfrage mit ihrer Quell-Markdown beantworten kann. Ausgelieferte Dokumente senden daher Vary: Accept. Eine Aktualisierung von Blockstudio schreibt beim nächsten Schreibvorgang der Zuordnung ein älteres Drop-in neu.

Zugeordnete Graph-Routen verwenden immer das aktivierte Artefakt. Liegt eine sichere anonyme Route nicht in dieser Zuordnung, wurde aber seitdem von WordPress gerendert und gespeichert, greift Early Serve auf den laufzeitgebundenen Store zurück, bevor WordPress geladen wird. So werden generierte oder selten besuchte Routen außerhalb eines bewusst begrenzten Deployment-Graphen unterstützt. Der Fallback verwendet die aktivierte Graph-Identität und dieselben Regeln für Host, Pfadnormalisierung, TTL, Cookies, Header, Query-String, dynamische Pfade und Feed-Umgehung wie zugeordnete Routen. Er findet nur Dokumente, die zur Laufzeit gespeichert wurden; Suchergebnisse sind darin nie enthalten.

Antwort-Header

Ein gespeichertes Dokument wird ohne die Anfrage wiedergegeben, durch die es gerendert wurde. Daher würde ein Header, den ein Theme oder Plugin mit header() sendet, bei jedem Aufruf fehlen. Blockstudio speichert die in replayHeaders genannten Header zusammen mit jedem Dokument und sendet sie sowohl aus dem PHP-Cache als auch aus dem Drop-in für die frühe Auslieferung erneut. Die Standardeinstellung ["Link"] umfasst Header wie eine Markdown-Alternative (rel="alternate"; type="text/markdown"), rel="describedby" oder rel="canonical". Namen werden ohne Beachtung der Groß- und Kleinschreibung abgeglichen, und der Einstellungsfilter ändert die Liste wie jeden anderen Wert:

PHP
add_filter('blockstudio/settings/performance/staticPrerender/replayHeaders', function (array $headers): array {
    $headers[] = 'X-Robots-Tag';

    return $headers;
});

Setze replayHeaders auf [], um die erneute Ausgabe von Headern zu deaktivieren. Eine explizite Liste ersetzt die Standardeinstellung. Füge daher Link hinzu, wenn du weitere Headernamen ergänzt und Link-Header weiterhin erneut ausgeben möchtest.

Header werden in dem Prozess erfasst, der die Seite rendert: aus headers_list(), wenn ein Live-Cache-Fehltreffer gespeichert wird, und aus der Aufwärmanfrage selbst, wenn ein Build oder der Aufwärmvorgang über HTTP rendert. Ein Header, den der Webserver eigenständig hinzufügt und jedem ausgelieferten Dokument erneut hinzufügt, wird also nie gespeichert. Nur wenn ein HTTP-Render keinen Bericht schreibt, werden die Header seiner Antwort verwendet. Der internal-Transport gibt sie in seinem Ergebnis als headers zurück, und persist_built_response() übernimmt sie als letztes Argument, entweder als Name: value-Zeilen oder als Zuordnung von Namen zu Werten.

Sie werden neben dem Dokument in <key>.headers.json geschrieben, bei der Übernahme von Artefakten, der Speicherbereinigung und dem Bereinigen abgelaufener Einträge mitgeführt und entfernt, wenn ein erneutes Rendern keine sendet. Cookie-, Cache- und Transport-Header werden nie gespeichert oder erneut ausgegeben, auch wenn sie aufgeführt sind: Set-Cookie, Cache-Control, Expires, Pragma, Age, ETag, Last-Modified, Vary, Content-Type, Content-Length, Content-Encoding, Transfer-Encoding, Location, Status, Date sowie Hop-by-Hop- und Authentifizierungs-Header. Ein ausgeliefertes Dokument setzt sein eigenes Content-Type und Vary.

Gespeicherte Header werden beim Senden erneut anhand der Liste geprüft. Der PHP-Cache liest die aktuelle Einstellung; das Drop-in liest die Kopie im Map-Eintrag der Website, die bei der nächsten Artefaktinstallation oder Synchronisierung der Map aktualisiert wird. Vor einem Upgrade gespeicherte Dokumente haben keine Header-Datei und werden bis zu ihrem erneuten Rendern wie zuvor ausgeliefert.

Aufwärmen, Wartung und Beobachtbarkeit

Die Warm-Queue ist dauerhaft, fasst URL-Aufträge zusammen, erlaubt jeweils nur einen laufenden Auftrag und stellt abgelaufene Aufträge wieder her. Inhalts- und Website-Änderungen erzwingen einen Ersatzauftrag, selbst wenn die aktuelle Signatur unverändert ist; bei Intervallläufen werden nur veraltete Aufträge eingereiht. Jeder Durchlauf, geplant oder über wp bs prerender warm gestartet, rendert bis zu warm.concurrency Aufträge. Der Modus graph deaktiviert das Aufwärmen pro URL, da Graph-Artefakte als Ganzes erstellt und aktiviert werden.

Shell
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs prerender map status
wp bs prerender map prune --dry-run

status meldet die aktive Identität, Dateien, Bytes, Graph-Datensätze, den Queue-Status, den Bericht zur Early-Serve-Zuordnung sowie Treffer-, Fehlversuchs-, Build- und Fehlerzähler pro Bereich.

Die Early-Serve-Zuordnung wird von allen Websites einer Installation gemeinsam genutzt. map status (und Static_Prerender_Early_Serve::map_report()) listet Einträge auf, die nicht mehr für die frühe Auslieferung verwendet werden können: orphaned-Einträge, deren Website nicht mehr existiert, und dead-Einträge, deren Verzeichnis verschwunden ist, sowie die Anzahl der missing-Routendokumente in den übrigen Einträgen. map prune (Static_Prerender_Early_Serve::prune_map()) entfernt verwaiste und ungültige Einträge unter Sperre der Zuordnung und meldet jeweils den Grund; --dry-run meldet sie nur. Wird der letzte Eintrag entfernt, werden die Zuordnung, das Drop-in und die WP_CACHE-Deklaration gelöscht. Wird eine Website aus einem Multisite-Netzwerk gelöscht, werden ihre Einträge sofort entfernt. Die Cache-Bereinigung sammelt niemals den Namensraum ein, aus dem ein aktiviertes Artefakt ausgeliefert wird. Einträge werden daher nur ungültig, wenn ihre Dateien auf anderem Weg entfernt werden.

Verfolge einzelne Antwortergebnisse mit blockstudio/static_prerender/outcome und alle gemeinsamen Cache-Ergebnisse mit blockstudio/cache/outcome.

Deinstallation

Installationen ohne Plugin-Deaktivierungs-Hook, etwa Composer-gebündelte Setups, können mit einem einzigen Befehl alles entfernen, was dem Feature gehört:

Shell
wp bs teardown

Dadurch werden die cron-Ereignisse und der statische Prerender-Status entfernt, den die Installation verwaltet: der Zuordnungseintrag der aktuellen Website sowie das gemeinsame Drop-in und die WP_CACHE-Deklaration, sobald der letzte eigene Eintrag entfernt ist. Konfigurationsdateien bleiben unangetastet, damit das Feature anschließend sauber wieder aktiviert werden kann.

Einführung im Produktivbetrieb

Eine sinnvolle Reihenfolge für die Einführung:

  1. Setze performance.profile auf speed und prüfe dann die Head-Ausgabe, Feeds und jedes Plugin, das auf oEmbed oder XML-RPC angewiesen ist.
  2. Erzeuge assets/media.json, verschiebe Templates nach bs_media_image() und aktiviere dann performance.media.lazy.
  3. Aktiviere performance.staticPrerender bei deaktiviertem earlyServe, prüfe Treffer mit wp bs prerender status und aktiviere anschließend earlyServe.

Ein Rollback erfolgt pro Feature: Wenn du staticPrerender.enabled auf false setzt, werden der von Blockstudio verwaltete Early-Serve-Status und die Warm-Zeitpläne einmalig entfernt. Anschließend bleibt die Prerender-Laufzeitumgebung unregistriert. Wenn du performance.profile wieder auf compat setzt, wird das Profil rückgängig gemacht. Die jeweils andere Ebene bleibt erhalten.

Performance

Die Profile, der Profiler und die zugrunde liegenden Render-Techniken.

Caching

Das eine Cache-Verzeichnis, in dem alle generierten Artefakte liegen.