Datenbankinhalte mit Content Sync in Dateien überführen
Blöcke, Vorlagen und dateibasierte Seiten liegen bereits in deinem Repository. Manche Inhalte passen nicht in dieses Modell, weil Redakteure sie im Admin-Bereich erstellen: Teammitglieder, Bürostandorte, Fallstudien. Diese Inhalte sind für das Projekt dennoch wichtig. Eine Staging-Site braucht dieselbe Teamseite wie die Produktionsumgebung, neue Entwickler brauchen realistische Daten und Prüfer sollten sehen, wenn jemand einen Jobtitel ändert. Datenbank-Dumps lösen keines dieser Probleme gut. Sie enthalten alles, IDs unterscheiden sich je nach Umgebung, und niemand prüft einen SQL-Diff.
Content Sync schließt diese Lücke. Ein WP-CLI-Befehl überträgt eine Positivliste mit Beiträgen, Begriffen, Beziehungen und Metadaten in JSON- und HTML-Dateien in deinem Theme. Ein weiterer Befehl wendet diese Dateien auf eine andere Datenbank an. Jede Entität erhält eine portable UID, und Referenzen zwischen Entitäten werden nur dort umgeschrieben, wo du es festlegst.
Diese Anleitung führt dich anhand eines Teamverzeichnisses durch den gesamten Ablauf: Inhalte in Dateien übertragen, prüfen, eine Datei bearbeiten, sie in eine neue Umgebung übertragen und Inhalte sicher bereinigen.
Das Beispiel
Das Theme registriert in jeder Umgebung einen Beitrags-Typ acme_member und eine Taxonomie acme_team. Jeder Mitgliederbeitrag kann Folgendes enthalten:
| Metaschlüssel | Enthält |
|---|---|
_acme_role |
Die Berufsbezeichnung als einfacher Text |
_acme_mentor |
Die Beitrags-ID eines anderen Mitglieds |
_thumbnail_id |
Die Anhang-ID des Porträts |
_acme_api_token |
Ein Integrationstoken, das niemals git erreichen darf |
Content Sync registriert niemals Beitrags-Typen oder Taxonomien. Sie müssen überall vorhanden sein, wo du Inhalte überträgst.
Schritt 1: Content Sync konfigurieren
Content Sync ist deaktiviert, bis du es in blockstudio.json aktivierst. Bis dahin gibt jeder Befehl eine einzelne Zeile skipped zurück:
wp bs content status
action entity id uid message
skipped content default Content Sync is disabled. Set content.enabled to true to run this command.
Füge eine Gruppe content hinzu:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"content": {
"enabled": true,
"id": "team",
"path": "content",
"postTypes": ["acme_member"],
"taxonomies": ["acme_team"],
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
},
"media": "manifest"
}
}
Jeder Schlüssel setzt eine Grenze:
postTypesundtaxonomiessind Positivlisten. Alles außerhalb davon wird weder gelesen noch geschrieben oder bereinigt. Ein leerespostTypesbedeutet, dass keine Beiträge bearbeitet werden.meta.includelegt eine Positivliste der Meta-Schlüssel fest und unterstützt*-Platzhalter.meta.excludehat immer Vorrang._edit_lock,_edit_lastund_wp_old_slugsind standardmäßig ausgeschlossen.meta.referenceslegt fest, welche Metawerte IDs sind. Content Sync nimmt niemals an, dass eine Ganzzahl eine ID ist.idbenennt die Inhaltsgruppe. Sie wird bei jeder synchronisierten Entität gespeichert, und die Bereinigung betrifft nur Entitäten derselben Gruppe.pathist der Ausgabeordner relativ zum aktiven Theme-Verzeichnis.
Schritt 2: Inhalte abrufen
Zeige zuerst eine Vorschau der Übertragung an. Es wird nichts geschrieben und die angezeigten UIDs werden noch nicht gespeichert:
wp bs content pull --dry-run
action entity id uid message
would-write post 530 4c8e9997-... .../posts/acme_member/jane.4c8e9997.json
would-write post 531 6cddc303-... .../posts/acme_member/sam.6cddc303.json
would-write term 4 6661b6d9-... .../terms/acme_team/leadership.6661b6d9.json
Führe anschließend den tatsächlichen Abruf aus. Dabei wird jeder Entität ohne UID eine dauerhafte _blockstudio_content_uid zugewiesen und werden die Dateien geschrieben:
wp bs content pull
action entity id uid message
written post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
written post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
written term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
written media manifest .../media/manifest.json
Das Ergebnis im Theme:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Dateinamen setzen sich aus dem Slug und dem Anfang der UID zusammen. Der Beitrag JSON enthält die Felder, Taxonomiebeziehungen und erlaubten Metadaten:
{
"uid": "5d4bf9b5-16b7-4975-acc6-51dc1d4e49ec",
"type": "acme_member",
"status": "publish",
"slug": "jane",
"title": "Jane Doe",
"date": "2026-10-13T03:03:02+00:00",
"modified": "2026-10-13T03:03:02+00:00",
"parent": null,
"menuOrder": 0,
"terms": {
"acme_team": [
"7491a6a1-702c-4a29-9993-9ae7b2a79c0a"
]
},
"meta": {
"_acme_role": "Design Lead",
"_thumbnail_id": "72a2db75-6fd2-41f9-8d3c-b323ce3b3551"
},
"metaEncoding": {
"_acme_role": "scalar",
"_thumbnail_id": "scalar"
}
}
Die Taxonomiebeziehung und das Beitragsbild werden über UIDs statt über lokale IDs angegeben. Der Beitragsinhalt liegt daneben in jane.5d4bf9b5.html als rohes Block-Markup. Für einen Beitrag ohne Inhalt wie den von Sam wird keine Datei .html erstellt. Sams _acme_mentor wird als UID von Jane gespeichert, weil der Schlüssel als post-Referenz deklariert ist.
Schritt 3: Vor dem Commit prüfen
Führe status vor dem Commit aus. Der Befehl vergleicht Dateien und Datenbank und weist außerdem auf riskante Daten hin:
wp bs content status
action entity id uid message
unchanged post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
unchanged post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
warning meta _acme_api_token Allowlisted meta key may contain secrets or PII; review before committing synced files.
Der _acme_*-Platzhalter hat das Token erfasst. Betrachte meta.include als Commit-Grenze und schließe den Schlüssel ausdrücklich aus:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Der nächste pull schreibt sam.208db72e.json ohne das Token neu und lässt die anderen Dateien unberührt. status warnt außerdem vor numerischen IDs in den Block-Markup-Inhalten, da Content Sync IDs in .html-Dateien nicht neu schreibt.
Übertrage den Ordner content/ in den Commit.
Schritt 4: Datei bearbeiten und pushen
Dateien sind die maßgebliche Quelle für push. Ändere Janes Rolle in der Datei JSON von Design Lead zu Head of Design und prüfe anschließend, was passieren würde:
wp bs content status
action entity id uid message
would-update post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
unchanged post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
push --dry-run gibt denselben Plan in Push-Reihenfolge aus. Wende ihn an:
wp bs content push
action entity id uid message
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
updated post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
unchanged post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
Push validiert den vollständigen Plan, bevor Änderungen geschrieben werden. Nicht aufgelöste deklarierte Referenzen, Slug-Konflikte, fehlende Beitragstypen und fehlerhafte Dateien verhindern den Vorgang.
WordPress weist einem aktualisierten Beitrag eine neue Änderungszeit zu, während die Datei weiterhin den alten Wert modified enthält. Ein status-Lauf direkt nach diesem Push meldet Janes Beitrag daher als conflict mit „Datenbank seit der letzten Synchronisierung geändert.“ Führe pull nach dem Push einmal aus, um die neue Zeit zu übernehmen; status meldet dann unchanged.
Schritt 5: Inhalte in eine andere Umgebung übertragen
In einer frischen Umgebung beschreiben die Dateien Beiträge, die dort noch nicht existieren. In diesem Beispiel sind der Begriff und der Porträt-Anhang dort bereits mit denselben UIDs vorhanden, sodass nur die beiden Mitglieder fehlen:
wp bs content status
action entity id uid message
missing-db post jane 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
missing-db post sam 208db72e-... .../posts/acme_member/sam.208db72e.json
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
wp bs content push
action entity id uid message
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
created post 536 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
created post 537 208db72e-... .../posts/acme_member/sam.208db72e.json
Die Beiträge erhielten neue lokale IDs, 536 und 537. Die Referenzen wurden entsprechend angepasst: Sam hat jetzt 536 in _acme_mentor, Jane ist wieder im Begriff leadership, und _thumbnail_id verweist auf den lokalen Anhang mit der passenden UID. Beitrags-Eltern, Begriffs-Eltern und Begriffsbeziehungen werden immer als UIDs gespeichert; Meta-Werte werden nur für Schlüssel in meta.references neu geschrieben.
Sicheres Bereinigen
Das Löschen einer Datei löscht beim Push nichts, sofern du es nicht ausdrücklich anforderst. Entferne sam.208db72e.json und versuche, Inhalte zu bereinigen:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Der Probelauf zeigt, was entfernt würde:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes verschiebt Sams Beitrag daraufhin in den Papierkorb und meldet pruned-trash. Mehrere Schutzmaßnahmen begrenzen den Umfang:
- Nur Entitäten, die diesem Inhaltssatz gehören (
content.id), kommen infrage. - Berücksichtigt werden nur konfigurierte Beitragstypen und Taxonomien.
- Der gesamte Quellplan wird geparst und validiert, bevor etwas geschrieben oder bereinigt wird. Bei einer fehlerhaften Datei JSON im Ordner meldet Push eine
error-Zeile wiecould not be read: Syntax errorund bereinigt nichts.
Die Standardaktion ist trash. Der Filter blockstudio/content/orphan_action kann für jede Entität trash, delete oder keep zurückgeben. So bleiben Begriffe erhalten, während Beiträge die Standardaktion verwenden:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Damit wird ein verwaister Begriff als would-prune-keep statt als would-prune-trash gemeldet.
Medien
Mediendateien werden nie kopiert. content.media legt fest, was mit deklarierten Anhang-Referenzen geschieht:
"manifest"(Standard) speichert Anhang-UIDs und führt sie incontent/media/manifest.jsonmit Pfad, MIME-Typ und Alternativtext auf. Push erfordert, dass jeder referenzierte Anhang-UID im Ziel vorhanden ist. Übertrage die Uploads daher zuerst wie gewohnt über deinen Medien-Workflow."none"lässt deklarierte Anhang-Referenzen aus den Dateien weg. Janes JSON enthält dann nur noch_acme_role. Da ein ausgelassener Schlüssel beim Push nicht angewendet wird, behält ein vorhandener Zielbeitrag sein aktuelles Vorschaubild.
Eine Entität sperren
Manchmal muss eine Zielumgebung ihre eigene Version eines Beitrags behalten. Setze das Meta-Feld _blockstudio_content_locked dieses Beitrags auf einen Wahrheitswert. Push überspringt ihn dann mit einer locked-Zeile und der Meldung „Gesperrte Entität übersprungen.“ Lösche das Meta-Feld, um ihn wieder einzubeziehen.
Regeln zur Zuständigkeit
- Beiträge, die von dateibasierten Seiten verwaltet werden, sind standardmäßig ausgeschlossen. Mit
includePageSyncManaged: truekann Content Sync ihre konfigurierten Metadaten synchronisieren, aber Page Sync bleibt für ihrepost_contentzuständig. Diese JSON-Projektionen enthaltenbodyOwner: "page-sync", und pull meldet den übersprungenen Inhalt ausdrücklich. Vorhandene.html-Prüfkopien bleiben erhalten und werden von push ignoriert. Synchronisiere die Seiten in einer Zielumgebung, bevor du ihre Metadatenprojektionen überträgst. - Autoren werden standardmäßig ignoriert, da Benutzer nicht synchronisiert werden. Mit
authors: "login"speichern Beitragsdateien den Anmeldenamen des Autors, und push ordnet ihn einem vorhandenen Benutzer zu. Fehlt der Benutzer, schlägt die Vorabprüfung fehl. pulllöscht niemals Dateien. Wenn eine Datenbankentität nicht mehr vorhanden ist, meldet pull ihre Datei als veraltet und überlässt dir die Bereinigung.
Wann du es nicht verwenden solltest
Content Sync eignet sich für sorgfältig zusammengestellte Inhalte mit wenigen Änderungen: Dutzende oder Hunderte Einträge, bei strukturierter Aufteilung in gezielte Beitragstypen auch bis zu einigen Tausend. Es ersetzt weder Datenbank-Backups noch Migrationen. Bestellungen, Formulareinsendungen, Protokolle, Analysen und redaktionelle Inhalte mit hohem Volumen gehören in andere Werkzeuge. Taxonomie-Definitionen, Mediendateien und IDs innerhalb von Block-Markup liegen außerhalb des Einsatzbereichs.
Nächste Schritte
- Referenz zu Content Sync: alle Konfigurationsschlüssel, Dateiformate und der gespeicherte Synchronisierungsstatus.
- Eine Dokumentationswebsite erstellen: Inhalte, die in Dateien beginnen und mit WordPress synchronisiert werden – in umgekehrter Richtung.
- Dateibasierte Seiten erstellen: Seiten, deren Struktur von Vorlagen im Theme bestimmt wird.