Eine Blockstudio-Website bereitstellen
Für Blöcke reicht es, einen Theme-Ordner auf einen Server zu kopieren: Blockstudio erkennt sie im Dateisystem, und seine Caches bemerken Änderungen an Eingaben von selbst. Bei einer echten Website gibt es mehr bewegliche Teile. Dateibasierte Seiten gelangen erst nach einer Synchronisierung in die Datenbank. Ein statisches Vorab-Rendering liefert weiterhin das gestrige HTML aus, bis es ersetzt wird. Ein vorgeschaltetes CDN liefert weiter aus, was dort zwischengespeichert wurde.
Diese Anleitung erstellt einen Deploy für ein Theme namens acme, das Blockstudio über Composer einbindet. Sie behandelt die Abläufe in CI und nach dem Übertragen der Dateien auf dem Server, das Lesen des Seitensynchronisierungsberichts und die Wartungsbefehle wp bs, die in einen Release gehören.
Der Release im Überblick
- Erstellen. CI installiert die Composer-Abhängigkeiten für den Produktivbetrieb.
- Hochladen. Das Theme einschließlich
vendor/wird auf den Server übertragen. - Seiten abgleichen.
wp bs pages syncbringt Seitenbeiträge mit den Dateien in Einklang und gibt einen Bericht aus. - Origin-Cache aktualisieren. Der gespeicherte HTML-Cache wird bei geänderten Seiten geleert und anschließend neu befüllt.
- CDN leeren. Zuletzt, damit der Edge-Cache wieder frische Inhalte vom Origin abruft.
Für die Schritte 3 und 4 wird WP-CLI auf dem Server benötigt. Das folgende Skript verwendet außerdem jq, um JSON zu lesen.
Schritt 1: Composer in CI
Binde Blockstudio in das Theme ein und committe composer.lock, damit CI genau die Version installiert, die du getestet hast:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
Installiere in CI ohne Entwicklungspakete:
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
Blockstudio wird über den Autoloader initialisiert. Die Laufzeitabhängigkeiten sind direkt im Paket gebündelt und mit einem eigenen Namensraum versehen. Wird es aus einem vendor/-Verzeichnis geladen, ist der integrierte GitHub-Updater deaktiviert. Composer bleibt damit der einzige Weg, die Version zu ändern.
Schritt 2: Schreibrechte festlegen
Blockstudio schreibt zur Laufzeit generierte Dateien. Lege vor einem Deploy fest, wo sie gespeichert werden, damit kein Verzeichnis ersetzt oder gesperrt wird:
- Laufzeit-Caches liegen standardmäßig unter
wp-content/blockstudio/cache/. Richtecache.pathbei Bedarf auf ein separates beschreibbares Volume. Ein geänderter Pfad beginnt mit einem leeren Cache. - Kompilierte Block-Assets werden standardmäßig in einem Ordner
_distneben jedem Block abgelegt. Ist dein Release-Verzeichnis schreibgeschützt oder wird es bei jedem Deploy ersetzt, setzeassets.outputaufcache. Dann werden die Assets stattdessen im Cache-Verzeichnis abgelegt:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"assets": {
"output": "cache"
}
}
Du musst beim Deploy keine Caches leeren. Jeder Cache-Eintrag richtet sich nach seinen Eingaben, darunter Blockdateien, Einstellungen, aktives Theme und Plugins sowie die Versionen WordPress, PHP und Blockstudio. Ändert ein Release diese Angaben, erhält es neue Schlüssel. In production und staging verlässt sich Blockstudio 20 Sekunden lang auf einen validierten Watch-Snapshot, bevor es Dateien erneut prüft. Änderungen werden daher möglicherweise erst nach bis zu 20 Sekunden erkannt. Der Filter blockstudio/cache/watch_debounce ändert dieses Zeitfenster.
Schritt 3: Seiten abgleichen
Seitenbeiträge ändern sich nur durch eine ausdrücklich angeforderte Synchronisierung. Frontend-, Admin-, Ajax-, REST-, cron- und gewöhnliche WP-CLI-Anfragen suchen nie nach Seitenquellen und schreiben keine Seitenbeiträge. Der Deploy muss den Vorgang ausdrücklich anstoßen:
wp bs pages sync --format=json
Auf einer Website, deren Theme zwei Seiten enthält, about und contact, werden sie beim ersten Lauf erstellt:
{
"discovered": 2,
"created": 2,
"updated": 0,
"unchanged": 0,
"removed": 0,
"failed": 0,
"fullReconciliation": true,
"sourceId": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd",
"sourceIdentity": {
"commit": "",
"dirtyHash": "",
"inventoryHash": "aaec5b9dd13d74eea872117b6167caa7a5d5c1abad9572fba22f6ddf6340adfe",
"engineFingerprint": "2c442442bb49f91e7187560e6db8f3475caa0b62b47708cab95b6ff13aba4469",
"hash": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd"
},
"pages": {
"about": {
"status": "created",
"postId": 545,
"locked": false
},
"contact": {
"status": "created",
"postId": 546,
"locked": false
}
},
"errors": []
}
So liest du den Bericht:
created,updated,unchanged,removedundfailedzählen Seiten. Eine Seite, deren Quellfingerabdruck sich nicht geändert hat, erzeugt keine Schreibvorgänge für Beiträge oder Beitragsmetadaten und löst keine Aktualisierungshooks aus.- Jeder Durchlauf vergleicht den vollständigen Seitenbestand.
fullReconciliationgibt an, ob der Durchlauf als vollständiger Abgleich gilt:truebeim ersten Lauf, mit--fulloder wenn sich die Sync-Engine selbst geändert hat, undfalse, wenn eine Identität aus einem vorherigen erfolgreichen Sync vorhanden ist. Nachgelagerte Tools können damit entscheiden, ob alles neu aufgebaut werden muss. sourceIdentityist ein deterministischer Fingerabdruck des Seitenbestands und der Sync-Engine. Der Befehl speichert ihn nach einem erfolgreichen Durchlauf.
Ohne --format=json gibt der Befehl eine Zusammenfassungszeile und eine Erfolgsmeldung aus. In einem CI-Protokoll, das kein Terminal ist, sind die Spalten der Zeile durch Tabulatoren getrennt:
discovered created updated unchanged removed failed source_id
2 0 1 1 0 0 7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.
Dieser Lauf folgte auf eine Änderung an about/index.php: Eine Seite wurde aktualisiert, eine blieb unverändert.
Wenn die Synchronisierung fehlschlägt
Der Befehl wird mit Status 1 beendet, wenn die Ermittlung oder der Abgleich einen Fehler meldet. Dadurch schlägt der CI-Schritt fehl. Der Bericht JSON wird trotzdem ausgegeben, also protokolliere ihn. Ein fehlerhaftes page.json sieht so aus:
{
"discovered": 0,
...
"failed": 1,
...
"pages": [],
"errors": [
{
"code": "invalid_page_json",
"message": "Invalid page.json file.",
"context": {
"path": ".../wp-content/themes/acme/pages/pricing/page.json"
}
}
]
}
Verwaltete Seiten, deren Quellen nicht mehr vorhanden sind, werden erst entfernt, wenn ein Durchlauf fehlerfrei endet. So löscht ein fehlgeschlagener Sync beim Release keine aktiven Seiten. Standardmäßig wandern entfernte Seiten in den Papierkorb; der Filter blockstudio/pages/orphan_action kann trash, delete oder keep zurückgeben.
Bei jedem Deploy ausführen
Führe den Sync auch aus, wenn sich keine Seite geändert hat. Wenn du in Release-Verzeichnisse deployst und einen Symlink umschaltest, verweist eine unveränderte Seite weiterhin auf die Template- und Layoutpfade des vorherigen Releases, bis der nächste Sync sie aktualisiert. Dabei werden post_content und das Änderungsdatum nicht verändert.
--authoritative und --full
Ein normaler Sync bewahrt Inhalte, die Redakteure innerhalb von Blöcken mit Schlüssel geändert haben. --authoritative ersetzt stattdessen verwaltete Inhalte durch die Dateien und kann eine Page-Sync-Sperre aufheben. Verwende es, wenn die Dateien maßgeblich sein sollen: etwa beim Zurücksetzen einer Staging-Website oder auf einer Website, auf der niemand dateibasierte Seiten im Editor bearbeitet. Führe es nicht bei jedem Deploy einer Website mit aktiven Redakteuren aus.
--full kennzeichnet den Durchlauf unabhängig von der gespeicherten Identität als vollständigen Abgleich. Der Seitenvergleich ist ohnehin bei jedem Durchlauf vollständig, daher ändert die Option den Wert von fullReconciliation im Bericht, nicht die geprüften Seiten. Übergib sie, wenn ein späterer Schritt anhand dieses Werts einen vollständigen Neuaufbau auslösen soll.
In PHP geschriebene Tools können Blockstudio\Pages::reconcile() direkt aufrufen. Die Funktion gibt denselben Bericht zurück, speichert aber die Identität nicht. Rufe Blockstudio\Pages::store_successful_source_identity() auf, sobald der übrige Release geprüft wurde, zum Beispiel nachdem ein statisches Artefakt aktiviert wurde.
Schritt 4: Statischen Cache aktualisieren
Wenn die Website statisches Prerendering im standardmäßigen Modus signature verwendet, löschen aktualisierte Beiträge aus WP-CLI den gespeicherten HTML-Cache nicht selbst. Lies den Bericht und leere den Cache, wenn sich etwas geändert hat. Wärme ihn anschließend auf:
#!/usr/bin/env bash
set -euo pipefail
cd /var/www/example.com
report=$(mktemp)
# 1. Reconcile file-backed pages and keep the report.
if ! wp bs pages sync --format=json > "$report"; then
cat "$report"
exit 1
fi
jq '{discovered, created, updated, unchanged, removed}' "$report"
# 2. Drop stored HTML when page content changed.
changed=$(jq '.created + .updated + .removed' "$report")
if [ "$changed" -gt 0 ]; then
wp bs prerender purge
fi
# 3. Re-warm in bounded passes until a pass warms nothing.
for _ in $(seq 1 50); do
warmed=$(wp bs prerender warm | jq '.warmed')
[ "$warmed" -gt 0 ] || break
done
wp bs prerender status | jq '{files, queue}'
Bei jedem Lauf von wp bs prerender warm werden veraltete öffentliche URLs in die Warteschlange gestellt, bis zu warm.concurrency davon gerendert und eine Zusammenfassung ausgegeben. In diesem Durchlauf wurden vier von sechs eingereihten URLs übernommen, aber alle vier konnten nicht gerendert werden:
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
Ein URL, das nicht gerendert werden kann, bleibt veraltet und wird beim nächsten Lauf erneut eingereiht. Deshalb endet die Schleife beim ersten Durchlauf, der nichts aufwärmt, statt auf eine leere Warteschlange zu warten. Alles Übrige übernimmt der geplante Cache-Aufwärmer oder der nächste anonyme Besuch.
Im Modus graph ist der Aufwärmer pro URL deaktiviert, und warm reiht nichts ein. Websites mit Graph ersetzen die Schritte 2 und 3 durch ihren eigenen Build, der die betroffenen URLs rendert und das Ergebnis atomar aktiviert. Siehe Signatur- und Graph-Modi.
Schritt 5: Der CI-Workflow
Der folgende Workflow ist ein Beispiel für GitHub Actions. Der Ablauf lässt sich auf jedes CI-System übertragen: erstellen, hochladen, das Skript auf dem Server ausführen und den CDN-Cache leeren.
name: Deploy
on:
push:
branches: [main]
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: "8.2"
tools: composer:v2
- name: Install production dependencies
run: composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
- name: Configure SSH
run: |
mkdir -p ~/.ssh
echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
ssh-keyscan example.com >> ~/.ssh/known_hosts
- name: Upload the theme
run: |
rsync -az --delete --exclude ".git" --exclude ".github" \
./ deploy@example.com:/var/www/example.com/wp-content/themes/acme/
- name: Sync pages and refresh the static cache
run: ssh deploy@example.com 'bash -s' < scripts/post-deploy.sh
- name: Purge the CDN
run: curl -fsS -X POST "${{ secrets.CDN_PURGE_URL }}"
concurrency mit cancel-in-progress: false reiht einen zweiten Push hinter einem laufenden Deploy ein, statt ihn mitten in einem Sync abzubrechen. PHP 8.2 ist die Mindestversion von Blockstudio. Ersetze den letzten Schritt durch den Purge-API deines CDN.
Wartungsbefehle
Diese gehören nicht in jedes Release, sollten aber im Deploy-Handbuch stehen.
Rückstand der alten Sperren abbauen. Releases vor 7.6.14 hinterließen bei jeder Inhaltsänderung eine Datei .build.lock. Nach dem Upgrade entfernt WP-Cron sie in begrenzten Stapeln. So prüfst du den Rückstand und baust ihn auf einmal ab:
wp bs cache status
wp bs cache cleanup
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).
cleanup lässt Sperren, die jünger als eine Stunde sind oder noch von einer laufenden Anfrage gehalten werden, bis zum nächsten Durchlauf bestehen. Lösche niemals manuell Sperrdateien, während die Website Anfragen bedient.
Laufzeitcache leeren. wp bs cache clear leert den gesamten Cache der aktuellen Website, und wp bs cache clear --scope=runtime leert einen Bereich über alle Namensräume hinweg. Die nächste Anfrage baut den Cache von Grund auf neu auf. Führe das bei geringem Traffic und nur bei Bedarf aus: Änderungen an Eingaben rotieren die Schlüssel bereits.
Blockstudio entfernen. Bei einer Composer-Installation gibt es keinen Hook zum Deaktivieren des Plugins. Daher werden cron-Ereignisse nicht aus dem Zeitplan entfernt und das Drop-in für die frühe Auslieferung bleibt bestehen, wenn das Paket entfernt wird. Führe dies aus, bevor du die Abhängigkeit entfernst:
wp bs teardown
Der Befehl entfernt die cron-Ereignisse und den Status für statisches Prerendering, der dieser Installation gehört. Fremde Drop-ins und Konfigurationsdateien bleiben unangetastet; eine spätere Reaktivierung kann sauber beginnen.
Nächste Schritte
- Dateibasierte Seiten erstellen: die Seiten, die bei diesem Deploy abgeglichen werden.
- Seitenreferenz: Sync-Verhalten, den Abgleich von PHPAPI und den Vertrag für die Deploy-Identität.
- Referenz zu CLI: alle
wp bs-Befehle. - Caching: Cache-Speicherort, Identität, Aufbewahrung und Rückstand der Sperren.
- WordPress als statisches HTML bereitstellen: der Cache, den Schritt 4 aktualisiert.
- Composer: Plugin-, Must-Use-, Theme- und im Plugin gebündelte Installationen.