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:
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.
Tilføj en content-gruppe:
{
"$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:
postTypesogtaxonomieser tilladelseslister. Intet uden for dem læses, skrives eller ryddes op. En tompostTypesbetyder, at ingen indlæg berøres.meta.includeangiver tilladte metanøgler med jokertegnene*.meta.excludehar altid forrang, og_edit_lock,_edit_lastog_wp_old_sluger som standard udelukket.meta.referencesangiver, hvilke metaværdier der er id’er. Content Sync gætter aldrig på, at et heltal er et id.idnavngiver indholdssættet. Det gemmes på hver synkroniseret enhed, og oprydning berører kun enheder fra det samme sæt.pather 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:
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
Hent derefter indholdet for alvor. Det tildeler et permanent _blockstudio_content_uid til hver
enhed, der ikke allerede har et, og skriver filerne:
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
Resultatet i temaet:
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:
{
"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:
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.
Jokertegnet _acme_* fangede tokenet. Behandl meta.include som en commitgrænse,
og udeluk nøglen eksplicit:
"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:
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 viser den samme plan i push-rækkefølge. Anvend den:
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 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:
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
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:
wp bs content push --prune
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:
wp bs content push --prune --dry-run
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åsomcould not be read: Syntax errorog 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:
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 icontent/media/manifest.jsonmed 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: truekan Content Sync synkronisere deres konfigurerede metadata, men Page Sync ejer stadig derespost_content. Disse JSON-projektioner indeholderbodyOwner: "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. pullsletter 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
- Content Sync-reference: alle konfigurationsnøgler, filformater og gemt synkroniseringstilstand.
- Opbygning af et dokumentationswebsted: indhold, der begynder i filer og synkroniseres den anden vej ind i WordPress.
- Opbygning af filbaserede sider: sider, hvis struktur ejes af skabeloner i temaet.