Flytta databasinnehåll till filer med Content Sync
Block, mallar och filbaserade sidor finns redan i ditt repo. En del innehåll passar inte in i den modellen, eftersom redaktörer skapar det i adminpanelen: teammedlemmar, kontorsplatser och fallstudier. Det innehållet är fortfarande viktigt för projektet. En stagingwebbplats behöver samma teamsida som produktionsmiljön, en ny utvecklare behöver realistiska data, och en granskare bör se när någon ändrar en jobbtitel. Databassäkerhetskopior löser inget av detta särskilt bra. De innehåller allt, ID:n skiljer sig mellan miljöer och ingen granskar en SQL-diff.
Content Sync täpper igen det glappet. Ett WP-CLI-kommando projicerar en tillåtelselista med inlägg, termer, relationer och metadata till JSON- och HTML-filer i ditt tema. Ett annat kommando tillämpar filerna på en annan databas. Varje entitet får ett portabelt UID, och referenser mellan entiteter skrivs om endast där du anger det.
Den här guiden går igenom en teamkatalog: hur du hämtar den till filer, granskar den, redigerar en fil, flyttar den till en ny miljö och rensar säkert.
Exemplet
Temat registrerar en inläggstyp med acme_member och en taxonomi med acme_team i
varje miljö. Varje medlemsinlägg kan innehålla:
| Metanyckel | Innehåller |
|---|---|
_acme_role |
Jobbtiteln, en vanlig sträng |
_acme_mentor |
Inläggs-ID för en annan medlem |
_thumbnail_id |
Bilaga-ID för porträttet |
_acme_api_token |
En integrationstoken som aldrig får nå git |
Content Sync registrerar aldrig inläggstyper eller taxonomier. De måste finnas där du skickar data.
Steg 1: Konfigurera Content Sync
Content Sync är inaktiverat tills du aktiverar det i blockstudio.json. Fram till dess returnerar varje
kommando en enda skipped-rad:
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.
Lägg till en content-grupp:
{
"$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"
}
}
Varje nyckel drar en gräns:
postTypesochtaxonomiesär tillåtelselistor. Ingenting utanför dem läses, skrivs eller rensas. En tompostTypesinnebär att inga inlägg berörs.meta.includeanger tillåtna metanycklar, med jokertecken för*.meta.excludehar alltid företräde, och_edit_lock,_edit_lastoch_wp_old_slugutesluts som standard.meta.referencesanger vilka metavärden som är ID:n. Content Sync gissar aldrig att ett heltal är ett ID.idnamnger innehållsmängden. Den lagras för varje synkad entitet, och rensning berör endast entiteter i samma mängd.pathär utdatamappen, relativ till den aktiva temamappen.
Steg 2: Hämta
Förhandsgranska först projektionen. Inget skrivs, och de UID:n som visas lagras inte än:
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
Hämta sedan på riktigt. Då tilldelas ett permanent _blockstudio_content_uid till varje
entitet som saknar ett, och filerna skrivs:
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 temat:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Filnamnen kombinerar sluggen med UID:ts första del. Inlägget JSON innehåller fälten, termrelationerna och de tillåtna metanycklarna:
{
"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 och miniatyrbilden är UID:n, inte lokala ID:n. Inläggstexten
ligger bredvid i jane.5d4bf9b5.html som rå blockmarkup. Ett inlägg med tomt
innehåll, som Sams, får ingen .html-fil. Sams _acme_mentor lagras som
Janes UID, eftersom nyckeln har deklarerats som en post-referens.
Steg 3: Granska före commit
Kör status före commit. Det jämför filer och databas och flaggar även
riskabla 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.
Jokertecknet i _acme_* fångade tokenen. Betrakta meta.include som en commitgräns och uteslut nyckeln uttryckligen:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Nästa pull skriver om sam.208db72e.json utan tokenen och lämnar de
andra filerna orörda. status varnar också för numeriska ID:n i blockmarkupens
innehåll, eftersom Content Sync inte skriver om ID:n i .html-filer.
Committa mappen content/.
Steg 4: Redigera en fil och skicka ändringarna
Filerna är källan till sanningen för push. Ändra Janes roll i JSON-filen
från Design Lead till Head of Design och kontrollera sedan vad som skulle hända:
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 skriver ut samma plan i den ordning ändringarna skickas. Tillämpa 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 validerar hela planen innan något skrivs. Olösta deklarerade referenser, slugkonflikter, saknade inläggstyper och felaktiga filer stoppar körningen.
WordPress ger ett uppdaterat inlägg en ny ändringstid, medan filen fortfarande har
det gamla värdet för modified. Därför rapporterar en status-körning direkt efter denna push
Janes inlägg som conflict med meddelandet “Database changed since last sync.” Kör pull
en gång efter push för att fånga den nya tiden; därefter rapporterar status unchanged.
Steg 5: Flytta innehållet till en annan miljö
I en ny miljö beskriver filerna inlägg som ännu inte finns. I det här exemplet finns termen och porträttbilagan redan där med samma UID:n, så bara de två medlemmarna saknas:
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
Inläggen fick nya lokala ID:n, 536 och 537. Referenserna följde med: Sams
_acme_mentor innehåller nu 536, Jane finns åter i termen leadership och hennes
_thumbnail_id pekar på den lokala bilagan med matchande UID. Föräldrainlägg,
termföräldrar och termrelationer lagras alltid som UID:n; metavärden skrivs om
endast för nycklar i meta.references.
Säker rensning
Att ta bort en fil raderar inte något vid push, om du inte begär det. Ta bort
sam.208db72e.json och prova att rensa:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Testkörningen visar vad som skulle tas bort:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes flyttar sedan Sams inlägg till papperskorgen och rapporterar
pruned-trash. Flera skyddsåtgärder håller omfattningen begränsad:
- Endast entiteter som ägs av den här innehållsmängden (
content.id) kan väljas. - Endast konfigurerade inläggstyper och taxonomier beaktas.
- Hela källplanen tolkas och valideras innan något skrivs eller
rensas. Om det finns en felaktig JSON-fil i mappen rapporterar push en
error-rad, till exempelcould not be read: Syntax error, och rensar ingenting.
Standardåtgärden är trash. Filtret blockstudio/content/orphan_action
kan returnera trash, delete eller keep för varje entitet. Då kan termerna behållas,
medan inlägg följer standarden:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Med detta rapporteras en föräldralös term som would-prune-keep i stället för
would-prune-trash.
Media
Mediefiler kopieras aldrig. content.media avgör vad som händer med deklarerade
bilagereferenser:
"manifest"(standard) lagrar bilagornas UID:n och listar dem icontent/media/manifest.jsonmed sökväg, typ av MIME och alternativtext. Push kräver att varje refererad bilagas UID finns i målet, så flytta uppladdningarna först med ditt vanliga arbetsflöde för media."none"utelämnar deklarerade bilagereferenser från filerna. Janes JSON innehåller då bara_acme_role. Eftersom en utelämnad nyckel inte tillämpas vid push behåller ett befintligt målinlägg sin nuvarande miniatyrbild.
Låsa en entitet
Ibland behöver en målmijö behålla sin egen version av ett inlägg. Ange ett
sant värde för metanyckeln _blockstudio_content_locked på det inlägget, så hoppar push över det med en locked-rad och meddelandet “Locked entity skipped.” Ta bort metanyckeln för att inkludera inlägget igen.
Ägarskapsregler
- Inlägg som hanteras av filbaserade sidor undantas som standard. Med
includePageSyncManaged: truekan Content Sync synkronisera deras konfigurerade metadata, men Page Sync ansvarar fortfarande för deraspost_content. Dessa JSON-projektioner innehållerbodyOwner: "page-sync", och pull rapporterar uttryckligen att innehållet hoppades över. Befintliga.html-granskningskopior bevaras och ignoreras vid push. Synkronisera sidorna i en målmiljö innan du pushar deras metadataprojektioner. - Författare ignoreras som standard eftersom användare inte synkroniseras. Med
authors: "login"lagras författarens inloggningsnamn i inläggsfilerna och push matchar det mot en befintlig användare; om användaren saknas uppstår ett preflight-fel. pulltar aldrig bort filer. När en databasenhet har försvunnit rapporterar pull filen som inaktuell och lämnar rensningen åt dig.
När du inte bör använda det
Content Sync passar för noggrant utvalt innehåll som ändras sällan: dussintals eller hundratals poster, upp till några tusen när data är strukturerad och uppdelad i fokuserade inläggstyper. Det ersätter inte databasbackuper eller migreringar. Beställningar, formulärinskick, loggar, analysdata och redaktionellt innehåll med hög volym hör hemma i dessa verktyg. Taxonomidefinitioner, binära mediefiler och ID:n i blockmarkup ligger utanför dess omfattning.
Nästa steg
- Referens för Content Sync: alla konfigurationsnycklar, filformat och lagrat synktillstånd.
- Bygga en dokumentationswebbplats: innehåll som börjar i filer och synkas till WordPress, fast åt andra hållet.
- Bygga filbaserade sidor: sidor vars struktur ägs av mallar i temat.