Zum Inhalt springen

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:

Shell
wp bs content status
Code
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:

JSON
{
  "$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:

  • postTypes und taxonomies sind Positivlisten. Alles außerhalb davon wird weder gelesen noch geschrieben oder bereinigt. Ein leeres postTypes bedeutet, dass keine Beiträge bearbeitet werden.
  • meta.include legt eine Positivliste der Meta-Schlüssel fest und unterstützt *-Platzhalter. meta.exclude hat immer Vorrang. _edit_lock, _edit_last und _wp_old_slug sind standardmäßig ausgeschlossen.
  • meta.references legt fest, welche Metawerte IDs sind. Content Sync nimmt niemals an, dass eine Ganzzahl eine ID ist.
  • id benennt die Inhaltsgruppe. Sie wird bei jeder synchronisierten Entität gespeichert, und die Bereinigung betrifft nur Entitäten derselben Gruppe.
  • path ist 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:

Shell
wp bs content pull --dry-run
Code
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:

Shell
wp bs content pull
Code
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:

Code
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:

JSON
{
    "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:

Shell
wp bs content status
Code
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:

JSON
"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:

Shell
wp bs content status
Code
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:

Shell
wp bs content push
Code
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:

Shell
wp bs content status
Code
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
Shell
wp bs content push
Code
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:

Shell
wp bs content push --prune
Code
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:

Shell
wp bs content push --prune --dry-run
Code
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 wie could not be read: Syntax error und 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:

PHP
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 in content/media/manifest.json mit 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: true kann Content Sync ihre konfigurierten Metadaten synchronisieren, aber Page Sync bleibt für ihre post_content zuständig. Diese JSON-Projektionen enthalten bodyOwner: "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.
  • pull lö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