Hoppa till innehåll

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:

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

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

Varje nyckel drar en gräns:

  • postTypes och taxonomies är tillåtelselistor. Ingenting utanför dem läses, skrivs eller rensas. En tom postTypes innebär att inga inlägg berörs.
  • meta.include anger tillåtna metanycklar, med jokertecken för *. meta.exclude har alltid företräde, och _edit_lock, _edit_last och _wp_old_slug utesluts som standard.
  • meta.references anger vilka metavärden som är ID:n. Content Sync gissar aldrig att ett heltal är ett ID.
  • id namnger 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:

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

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

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

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

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

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

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

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

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

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

Shell
wp bs content push --prune --dry-run
Kod
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 exempel could 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:

PHP
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 i content/media/manifest.json med 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: true kan Content Sync synkronisera deras konfigurerade metadata, men Page Sync ansvarar fortfarande för deras post_content. Dessa JSON-projektioner innehåller bodyOwner: "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.
  • pull tar 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