Content-Synchronisierung
Blockstudio basiert auf einem dateibasierten Workflow: Blöcke, Felder, Templates, Assets, Patterns und dateibasierte Seiten können alle in deinem Projekt liegen. Content Sync erweitert dieses Modell auf ausgewählte WordPress-Datenbankinhalte für Teams, die kuratierte Beiträge, Begriffe, Beziehungen und deklarierte Metadaten ebenfalls in git verwalten möchten.
Es handelt sich um einen WP-CLI-Workflow, keine laufende Datenbankreplikation. Beim Abruf überführt Content Sync freigegebene Beiträge, postmeta, Begriffe, termmeta und Beitrags-Begriffs-Beziehungen in portable Dateien in deinem Theme. Beim Übertragen wendet es diese Dateien auf eine andere Umgebung an. Dabei verwendet es stabile UIDs und schreibt nur Referenzen um, die du ausdrücklich deklarierst.
Hinweis
Content Sync wird bei Bedarf ausgeführt. Es läuft nicht bei jeder Admin-Anfrage. Bis
content.enabledden Statustruehat, melden Befehle, dass eine Zeile übersprungen wurde.
Wann du Content Sync verwenden solltest
Verwende Content Sync für Inhaltsbestände, die versioniert, geprüft und zwischen Umgebungen übertragen werden sollen:
- strukturierte Inhalte wie Teammitglieder, Standorte, Fallstudien, Produkte, Dokumentationseinträge oder Kampagnenseiten
- Taxonomien und Beziehungen, die zu diesen Inhaltsbeständen gehören
- freigegebene Metadaten, die sicher eingecheckt werden können und stabile Referenzen benötigen
- kleine bis mittelgroße Inhaltsbestände, deren Dateien sich noch gut in git prüfen lassen
Als Faustregel eignet sich Content Sync gut für Dutzende oder Hunderte von Datensätzen und kann bei strukturierter, selten geänderter und auf bestimmte Beitragstypen verteilter Daten auch einige Tausend verarbeiten. Es ist nicht dafür gedacht, eine gesamte Produktionsdatenbank, redaktionelle Inhalte mit hohem Aufkommen, Protokolle, Bestellungen, Analysen, Formulareinsendungen, Sitzungen oder andere umfangreiche oder häufig geänderte Daten zu spiegeln. Werden die generierten Dateien unübersichtlich, dauern Pushes zu lange, um sie nachvollziehen zu können, oder ändern sich die meisten Datensätze außerhalb deines Deployment-Workflows, verwende stattdessen ein Datenbank-Backup, Migrationstool oder Import-/Export-Tool.
Mediendateien werden nicht kopiert. Referenzen auf Anhänge können in einem Manifest erfasst und validiert werden, aber die Dateien selbst müssen in der Zielumgebung vorhanden sein.
Konfiguration
Aktiviere Content Sync in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"content": {
"enabled": true,
"id": "default",
"path": "content",
"includePageSyncManaged": false,
"authors": "ignore",
"postTypes": ["team_member"],
"meta": {
"include": ["_my_*"],
"exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
"references": {
"_thumbnail_id": { "kind": "attachment" },
"_related_posts": { "kind": "post", "path": "*" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
},
"taxonomies": [],
"media": "manifest"
}
}
postTypes ist eine Freigabeliste. Ist sie leer, greift Content Sync nicht auf Beiträge zu. taxonomies ist eine Freigabeliste registrierter Taxonomien, deren Begriffe und Beitragsbeziehungen synchronisiert werden sollen. Blockstudio registriert keine Taxonomiedefinitionen aus Content-Sync-Dateien. postmeta und termmeta werden über meta.include freigegeben; meta.exclude hat immer Vorrang.
Warnung
Betrachte
meta.includeals Grenze dafür, was eingecheckt wird. Synchronisierte Dateien gehören in git. Nimm daher keine Schlüssel auf, die Geheimnisse, Tokens, Zugangsdaten oder personenbezogene Daten enthalten.wp bs content statusmeldet Warnungen, wenn ein freigegebener Metaschlüssel sensibel zu sein scheint.
content.id wird für synchronisierte Entitäten als _blockstudio_content_set gespeichert. Bereinigungen und Besitzprüfungen beziehen sich auf diesen Wert, damit ein Inhaltsbestand nicht die Inhalte eines anderen löschen kann.
Von Page Sync verwaltete Beiträge sind standardmäßig ausgeschlossen. Wenn includePageSyncManaged aktiviert ist, kann Content Sync ihre konfigurierten Metadaten synchronisieren; post_content bleibt jedoch im Besitz von Page Sync.
Diese Projektionen enthalten "bodyOwner": "page-sync". Pull kennzeichnet den Schreibvorgang von JSON als reine Metadatenänderung und fügt eine skipped-Body-Zeile hinzu, statt den Beitrag so darzustellen, als hätte er einen leeren Body. Eine zugehörige .html-Datei wird weder geschrieben noch gelöscht. Eine vorhandene Review-Kopie bleibt erhalten und wird von Push ignoriert. Dieselben Hinweise zur Zuständigkeit sind in der Dry-Run-Ausgabe enthalten.
Führe Page Sync zuerst in einer anderen Umgebung aus. Eine Projektion mit
bodyOwner: "page-sync" muss auf einen vorhandenen, von Page Sync verwalteten Beitrag verweisen;
beim Push wird kein leerer Ersatzbeitrag erstellt und keine Prüffassung dieses Inhalts angewendet.
Projektionen aus älteren Versionen ohne den Marker werden weiterhin unterstützt.
Autoren werden standardmäßig ignoriert, weil Benutzer nicht synchronisiert werden. Setze authors: "login", um den Login des Autors in Beitragsdateien zu speichern und ihn beim Push einem vorhandenen Benutzer zuzuordnen. Fehlt der Benutzer, schlägt die Vorabprüfung fehl; Content Sync erstellt keine Benutzer.
Befehle
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status
pull überführt Datenbankinhalte in Dateien. Weist in den Geltungsbereich fallenden Beiträgen, die noch keine haben, eine _blockstudio_content_uid zu und meldet veraltete Dateien, deren Datenbankquelle nicht mehr existiert. Veraltete Dateien werden beim Abruf nicht gelöscht.
push wendet Dateien auf die aktuelle Datenbank an. Vor dem Schreiben wird der Plan validiert; nicht auflösbare deklarierte Referenzen, Slug-Konflikte, gesperrte Entitäten und fehlende Beitragstypen verhindern den Vorgang.
status vergleicht Dateien mit der Datenbank und meldet für jede Entität den Status unchanged, would-update, missing-db, conflict, locked oder orphaned. Außerdem warnt der Befehl vor dem Einchecken vor freigegebenen Metaschlüsseln, die wie Geheimnisse aussehen, sowie vor numerischen IDs in Block-Markup-Inhalten, da Content Sync IDs in .html-Dateien nicht umschreibt.
Verwende --dry-run, um einen Abruf oder Push ohne Schreibvorgänge zu prüfen. Mit push --prune --yes entfernst du Datenbankentitäten eines Inhaltsbestands, die in den Dateien nicht mehr vorhanden sind.
Sicherheit bei Fehlern
push parst und validiert den vollständigen Quellplan, bevor es schreibt oder Daten bereinigt. Ungültige JSON, nicht auflösbare deklarierte Referenzen, ungültige Besitzangaben und andere Fehler bei der Vorabprüfung verhindern destruktive Vorgänge. Bereinigungen bleiben auf die konfigurierten Beitragstypen, Taxonomien und content.id beschränkt.
pull schreibt jede überführte Datei, bevor es die Entität als synchronisiert vermerkt. Schlägt das Schreiben im Dateisystem fehl, wird dies als Fehlerzeile zurückgegeben und der gespeicherte Synchronisierungsstatus der Entität bleibt unverändert.
Die Behandlung von Anhängen richtet sich nach content.media. Mit "manifest" müssen referenzierte Anhang-UIDs in der Zielumgebung vorhanden sein. Mit "none" werden deklarierte Anhangsreferenzen absichtlich aus der portablen Ausgabe entfernt, statt umgebungsspezifische IDs beizubehalten.
Dateien
Content Sync schreibt Dateien in das konfigurierte content.path:
content/
posts/
team_member/
jane.9b1c0e6e.json
jane.9b1c0e6e.html
terms/
category/
leadership.5e900000.json
media/
manifest.json
Beitragsdateien .json enthalten Identität, Beitragsfelder, Begriffsbeziehungen, deklarierte Metadaten und deren Kodierung. Die benachbarte Datei .html enthält post_content als rohes Block-Markup und wird bei leerem Inhalt weggelassen. Begriffsdateien .json enthalten Identität, Taxonomie, Slug, Namen, Beschreibung, übergeordnete UID, deklarierte Begriffsmetadaten und deren Kodierung.
Der andere Fall ohne .html-Datei ist ein von Page Sync verwalteter Inhalt, erkennbar an
bodyOwner oben. Bei gewöhnlichen Beiträgen, deren Inhalt leer wird, entfernt pull
die alte Inhaltsdatei und führt sie in einer separaten Inhaltszeile deleted auf.
{
"uid": "9b1c0e6e-0000-4000-9000-000000000000",
"type": "team_member",
"status": "publish",
"slug": "jane",
"title": "Jane",
"parent": null,
"menuOrder": 0,
"terms": {
"category": ["5e900000-0000-4000-9000-000000000000"]
},
"meta": {
"_my_subtitle": "Creative Director",
"_thumbnail_id": "a1b2c3d4-0000-4000-9000-000000000000"
},
"metaEncoding": {
"_my_subtitle": "scalar",
"_thumbnail_id": "scalar"
}
}
Der gespeicherte Synchronisierungsstatus lautet:
| Metaschlüssel | Zweck |
|---|---|
_blockstudio_content_uid |
Portable Inhaltsidentität |
_blockstudio_content_set |
Namensraum des Inhaltsbestands aus content.id |
_blockstudio_content_source |
Theme-relativer Quellpfad |
_blockstudio_content_fingerprint |
Letzter Fingerabdruck von Datei/Datenbank-Abgleich |
_blockstudio_content_locked |
Ein wahrer Wert verhindert, dass ein Push die Entität überschreibt |
Referenzen
Content Sync nimmt niemals an, dass eine Ganzzahl eine ID ist. Referenzen werden nur umgeschrieben, wenn sie in meta.references konfiguriert sind.
{
"meta": {
"references": {
"_related_posts": { "kind": "post", "path": "*" },
"_topic": { "kind": "term" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
}
}
Beim Abruf werden lokale IDs an diesen Pfaden in portable UIDs umgewandelt. Beim Push werden die UIDs in der aktuellen Datenbank wieder lokalen IDs zugeordnet.
Übergeordnete Beiträge, übergeordnete Begriffe und Beitrags-Begriffs-Beziehungen sind strukturelle Referenzen, die Content Sync verwaltet und automatisch als UIDs speichert. Konfigurierte Taxonomien werden auch dann in Beitragsdateien geschrieben, wenn sie leer sind; ein leeres Array entfernt beim Push die Beziehungen dieser Taxonomie.
Anhangsreferenzen werden validiert, aber nicht importiert. Mit media: "manifest" werden referenzierte Anhänge in content/media/manifest.json aufgeführt; beim Push muss die UID des referenzierten Anhangs lokal vorhanden sein. Mit media: "none" werden deklarierte Anhangsreferenzen aus portablen Dateien ausgelassen. Da ein ausgelassener Schlüssel beim Push nicht angewendet wird, behält ein vorhandener Zielbeitrag seine aktuellen Anhangsmetadaten.
Portabilitäts-Workflow
- Registriere den Zielbeitragstyp in jeder Umgebung.
- Konfiguriere
content.postTypes,meta.includeund alle deklarierten Referenzen. - Führe
wp bs content pullin der Quellumgebung aus. - Checke die generierten Dateien ein.
- Führe
wp bs content pushin der Zielumgebung aus. - Führe
wp bs content statusaus, um zu prüfen, ob die Datenbank mit den Dateien übereinstimmt.
Für push sind die Dateien die maßgebliche Quelle. Mit pull werden Datenbankinhalte wieder in Dateien überführt.
Geltungsbereich
Content Sync unterstützt:
- Beiträge aus freigegebenen Beitragstypen
- freigegebenes postmeta
- Begriffe aus freigegebenen registrierten Taxonomien
- freigegebenes termmeta
- Beitrags-Begriffs-Beziehungen
- deklarierte Referenzen vom Typ
post,attachmentundterm - portable Beitrags- und Begriffs-UIDs sowie die Zuordnung zu Inhaltsbeständen
- standardmäßigen Ausschluss durch Page Sync
- Anhangsmanifest und Vorabprüfung
- Behandlung von
pull,push,status,--dry-run,--pruneund gesperrten Entitäten
Das Erfassen von Taxonomiedefinitionen, das Kopieren von Mediendateien und das Umschreiben von IDs im Block-Markup werden nicht unterstützt.