Gå til indhold

Flyt databaseindhold til filer med Content Sync

Blocks, templates og filbaserede sider ligger allerede i dit repository. Noget indhold passer ikke ind i den model, fordi redaktører opretter det i administrationspanelet: teammedlemmer, kontorsteder og casestudier. Det indhold er stadig vigtigt for projektet. Et staging-site skal have den samme teamside som produktionen, en ny udvikler har brug for realistiske data, og en anmelder bør kunne se, når nogen ændrer en jobtitel. Database-dumps løser ikke noget af dette særligt godt. De indeholder alt, ID’er er forskellige fra miljø til miljø, og ingen gennemgår en SQL-diff.

Content Sync lukker det hul. En WP-CLI-kommando overfører en tilladelsesliste over indlæg, begreber, relationer og metadata til JSON- og HTML-filer i dit tema. En anden kommando anvender filerne på en anden database. Hver enhed får et portabelt UID, og referencer mellem enheder omskrives kun, hvor du har erklæret dem.

Denne vejledning gennemgår et teamkatalog: hent det ned i filer, gennemgå det, redigér en fil, flyt det til et nyt miljø, og ryd sikkert op.

Eksemplet

Temaet registrerer en acme_member-indlægstype og en acme_team-taksonomi i hvert miljø. Hvert medlemsindlæg kan indeholde:

Metanøgle Indeholder
_acme_role Jobtitlen, en almindelig streng
_acme_mentor Indlægs-id’et for et andet medlem
_thumbnail_id Vedhæftnings-id’et for portrættet
_acme_api_token Et integrationstoken, der aldrig må ende i git

Content Sync registrerer aldrig indlægstyper eller taksonomier. De skal findes alle steder, hvor du udfører push.

Trin 1: Konfigurer Content Sync

Content Sync er slået fra, indtil du aktiverer det i blockstudio.json. Indtil da returnerer hver kommando én enkelt skipped-række:

Shell
wp bs content status
Kode
action   entity   id       uid  message
skipped  content  default       Content Sync is disabled. Set content.enabled to true to run this command.

Tilføj en content-gruppe:

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"
  }
}

Hver nøgle afgrænser:

  • postTypes og taxonomies er tilladelseslister. Intet uden for dem læses, skrives eller ryddes op. En tom postTypes betyder, at ingen indlæg berøres.
  • meta.include angiver tilladte metanøgler med jokertegnene *. meta.exclude har altid forrang, og _edit_lock, _edit_last og _wp_old_slug er som standard udelukket.
  • meta.references angiver, hvilke metaværdier der er id’er. Content Sync gætter aldrig på, at et heltal er et id.
  • id navngiver indholdssættet. Det gemmes på hver synkroniseret enhed, og oprydning berører kun enheder fra det samme sæt.
  • path er outputmappen i forhold til den aktive temamappe.

Trin 2: Hent ned

Se først en forhåndsvisning af overførslen. Intet skrives, og de viste UID’er bliver endnu ikke gemt:

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

Hent derefter indholdet for alvor. Det tildeler et permanent _blockstudio_content_uid til hver enhed, der ikke allerede har et, og skriver filerne:

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

Resultatet i temaet:

Kode
content/
├── media/
│   └── manifest.json
├── posts/
│   └── acme_member/
│       ├── jane.5d4bf9b5.html
│       ├── jane.5d4bf9b5.json
│       └── sam.208db72e.json
└── terms/
    └── acme_team/
        └── leadership.7491a6a1.json

Filnavnene kombinerer sluggen med den første del af UID’et. Indlægget JSON indeholder felterne, termrelationerne og de tilladte metaværdier:

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"
    }
}

Termrelationen og miniaturebilledet er UID’er, ikke lokale id’er. Indlæggets indhold ligger ved siden af i jane.5d4bf9b5.html som rå blokmarkup. Et indlæg med tomt indhold, som Sams, får ingen .html-fil. Sams _acme_mentor gemmes som Janes UID, fordi nøglen er erklæret som en post-reference.

Trin 3: Gennemgå før commit

Kør status før commit. Den sammenligner filer og database og markerer også risikable data:

Shell
wp bs content status
Kode
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.

Jokertegnet _acme_* fangede tokenet. Behandl meta.include som en commitgrænse, og udeluk nøglen eksplicit:

JSON
"meta": {
  "include": ["_acme_*", "_thumbnail_id"],
  "exclude": ["_acme_api_token"],
  "references": {
    "_acme_mentor": { "kind": "post" },
    "_thumbnail_id": { "kind": "attachment" }
  }
}

Den næste pull omskriver sam.208db72e.json uden tokenet og lader de andre filer være urørte. status advarer også om numeriske id’er i blokindhold, fordi Content Sync ikke omskriver id’er i .html-filer.

Commit mappen content/.

Trin 4: Redigér en fil, og udfør push

Filerne er sandhedskilden for push. Skift Janes rolle i filen JSON fra Design Lead til Head of Design, og se derefter, hvad der vil ske:

Shell
wp bs content status
Kode
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 viser den samme plan i push-rækkefølge. Anvend den:

Shell
wp bs content push
Kode
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 validerer hele planen, før den skriver. Uafklarede erklærede referencer, slugkonflikter, manglende indlægstyper og fejlformaterede filer stopper den.

WordPress giver et opdateret indlæg et nyt ændringstidspunkt, mens filen stadig har den gamle værdi modified. En status-kørsel lige efter dette push rapporterer derfor Janes indlæg som conflict med “Database changed since last sync.” Kør pull én gang efter push for at registrere det nye tidspunkt; status rapporterer derefter unchanged.

Trin 5: Flyt indholdet til et andet miljø

I et nyt miljø beskriver filerne indlæg, der endnu ikke findes. I dette eksempel findes termen og portrætvedhæftningen allerede dér med de samme UID’er, så kun de to medlemmer mangler:

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

Indlæggene fik nye lokale id’er, 536 og 537. Referencerne fulgte med: Sams _acme_mentor indeholder nu 536, Jane er igen i termen leadership, og hendes _thumbnail_id peger på den lokale vedhæftning med det matchende UID. Overordnede indlæg, termoverordnede og termrelationer gemmes altid som UID’er; metaværdier omskrives kun for nøgler i meta.references.

Sikker oprydning

Sletning af en fil sletter ikke noget ved push, medmindre du beder om det. Fjern sam.208db72e.json, og prøv at rydde op:

Shell
wp bs content push --prune
Kode
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

Prøvekørslen viser, hvad der ville blive fjernet:

Shell
wp bs content push --prune --dry-run
Kode
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

push --prune --yes flytter derefter Sams indlæg til papirkurven og rapporterer pruned-trash. Flere sikkerhedsforanstaltninger begrænser omfanget:

  • Kun enheder, der tilhører dette indholdssæt (content.id), er kandidater.
  • Kun konfigurerede indlægstyper og taksonomier tages i betragtning.
  • Hele kildeplanen parses og valideres, før noget skrives eller ryddes op. Hvis mappen indeholder en fejlformateret JSON-fil, rapporterer push en error-række såsom could not be read: Syntax error og rydder ikke op.

Standardhandlingen er trash. Filteret blockstudio/content/orphan_action kan returnere trash, delete eller keep for hver enhed. Sådan bevares termer, mens indlæg beholder standardhandlingen:

PHP
add_filter(
	'blockstudio/content/orphan_action',
	function ( string $action, string $type ) {
		return 'term' === $type ? 'keep' : $action;
	},
	10,
	2
);

Med dette rapporteres en forældreløs term som would-prune-keep i stedet for would-prune-trash.

Medier

Mediefiler kopieres aldrig. content.media bestemmer, hvad der sker med erklærede referencer til vedhæftninger:

  • "manifest" (standard) gemmer vedhæftningernes UID’er og viser dem i content/media/manifest.json med sti, MIME-type og alternativ tekst. Push kræver, at hver refereret vedhæftnings-UID findes på målet, så flyt uploads med din sædvanlige arbejdsgang for medier først.
  • "none" udelader erklærede referencer til vedhæftninger fra filerne. Janes JSON indeholder så kun _acme_role. Da en udeladt nøgle ikke anvendes ved push, beholder et eksisterende indlæg på målet sit aktuelle miniaturebillede.

Låsning af en enhed

Nogle gange skal et målmiljø beholde sin egen version af et indlæg. Sæt _blockstudio_content_locked-metanøglen til en sandhedsværdi på det pågældende indlæg, så springer push det over med en locked-række og meddelelsen “Locked entity skipped.” Slet metanøglen for at medtage det igen.

Ejerskabsregler

  • Indlæg, der administreres af filbaserede sider, er som standard udelukket. Med includePageSyncManaged: true kan Content Sync synkronisere deres konfigurerede metadata, men Page Sync ejer stadig deres post_content. Disse JSON-projektioner indeholder bodyOwner: "page-sync", og pull rapporterer udtrykkeligt, at brødteksten blev sprunget over. Eksisterende .html-gennemgangskopier bevares og ignoreres af push. Synkronisér siderne i et målmiljø, før du pusher deres metadataprojektioner.
  • Forfattere ignoreres som standard, fordi brugere ikke synkroniseres. Med authors: "login" gemmer indlægsfiler forfatterens login, og push slår det op blandt eksisterende brugere; en manglende bruger giver en fejl i forhåndskontrollen.
  • pull sletter aldrig filer. Når en databasepost er væk, rapporterer pull filen som forældet og overlader oprydningen til dig.

Hvornår du ikke skal bruge det

Content Sync egner sig til udvalgt indhold, der sjældent ændres: snesevis eller hundredvis af elementer, op til nogle få tusinde, når dataene er strukturerede og opdelt i fokuserede indlægs- typer. Det erstatter ikke sikkerhedskopier af databaser eller migreringer. Ordrer, formularindsendelser, logfiler, analyser og redaktionelt indhold i stor skala hører til i disse værktøjer. Taksonomidefinitioner, binære mediefiler og id’er inde i blokmarkup ligger uden for dets område.

Næste trin