Przenoszenie zawartości bazy danych do plików za pomocą synchronizacji zawartości
Bloki, szablony i strony oparte na plikach już znajdują się w repozytorium. Część zawartości nie pasuje do tego modelu, ponieważ tworzą ją redaktorzy w panelu administracyjnym: członkowie zespołu, lokalizacje biur, studia przypadków. Ta zawartość nadal ma znaczenie dla projektu. Witryna testowa potrzebuje tej samej strony zespołu co produkcyjna, nowy programista potrzebuje realistycznych danych, a osoba sprawdzająca powinna widzieć zmiany stanowisk pracy. Zrzuty bazy danych nie rozwiązują tego problemu. Zawierają wszystko, identyfikatory różnią się w poszczególnych środowiskach, a nikt nie sprawdza różnic SQL.
Content Sync wypełnia tę lukę. Polecenie WP-CLI przenosi listę dozwolonych wpisów, taksonomii, relacji i metadanych do plików JSON i HTML w motywie. Inne polecenie stosuje te pliki w innej bazie danych. Każda encja otrzymuje przenośny UID, a odwołania między encjami są przepisywane tylko tam, gdzie zostanie to zadeklarowane.
Ten przewodnik opisuje katalog zespołu: przeniesienie go do plików, ich przegląd, edycję pliku, przeniesienie do nowego środowiska i bezpieczne usuwanie zbędnych danych.
Przykład
Motyw rejestruje typ wpisu acme_member i taksonomię acme_team w każdym
środowisku. Każdy wpis członka zespołu może zawierać:
| Klucz meta | Zawartość |
|---|---|
_acme_role |
Stanowisko, zwykły ciąg znaków |
_acme_mentor |
ID wpisu innego członka zespołu |
_thumbnail_id |
ID załącznika z portretem |
_acme_api_token |
Token integracji, który nigdy nie może trafić do git |
Content Sync nigdy nie rejestruje typów wpisów ani taksonomii. Muszą one istnieć w każdym środowisku, do którego wysyłasz dane.
Krok 1: Konfiguracja Content Sync
Content Sync jest wyłączony, dopóki nie włączysz go w blockstudio.json. Do tego czasu każde
polecenie zwraca jeden wiersz skipped:
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.
Dodaj grupę content:
{
"$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"
}
}
Każdy klucz wyznacza granicę:
postTypesitaxonomiesto listy dozwolonych elementów. Nic spoza nich nie jest odczytywane, zapisywane ani usuwane. Pusta wartośćpostTypesoznacza, że żadne wpisy nie zostaną zmienione.meta.includeokreśla dozwolone klucze meta, a*oznacza symbole wieloznaczne.meta.excludezawsze ma pierwszeństwo, a_edit_lock,_edit_lasti_wp_old_slugsą domyślnie wykluczone.meta.referencesokreśla, które wartości meta są identyfikatorami. Content Sync nie zakłada, że liczba całkowita jest identyfikatorem.idokreśla zestaw treści. Jest zapisywany przy każdej synchronizowanej encji, a usuwanie zbędnych elementów obejmuje wyłącznie encje z tego samego zestawu.pathto folder wyjściowy względem katalogu aktywnego motywu.
Krok 2: Pobieranie
Najpierw wyświetl podgląd projekcji. Nic nie zostanie zapisane, a pokazane UID-y nie są jeszcze przechowywane:
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
Następnie pobierz dane na stałe. Każda encja, która go nie ma, otrzyma trwały
_blockstudio_content_uid, a pliki zostaną zapisane:
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
Wynik w motywie:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Nazwy plików składają się ze sluga i początkowej części UID. Wpis JSON zawiera pola, relacje taksonomii i dozwolone metadane:
{
"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"
}
}
Relacja taksonomii i miniatura są zapisane jako UID-y, a nie lokalne ID. Treść
wpisu znajduje się obok, w pliku jane.5d4bf9b5.html, jako surowy znacznik bloków. Wpis
bez treści, taki jak wpis Sama, nie otrzymuje pliku .html. Wartość pola
_acme_mentor Sama jest zapisana jako UID Jane, ponieważ klucz jest zadeklarowany jako
odwołanie post.
Krok 3: Przegląd przed zatwierdzeniem
Przed zatwierdzeniem uruchom status. Porównuje pliki z bazą danych i oznacza też
ryzykowne dane:
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.
Symbol wieloznaczny _acme_* wykrył token. Potraktuj meta.include jako granicę
zatwierdzania i jawnie wyklucz ten klucz:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Kolejne pull zapisze ponownie sam.208db72e.json bez tokenu i pozostawi pozostałe pliki
bez zmian. status ostrzega też o liczbowych identyfikatorach w treściach
znaczników bloków, ponieważ Content Sync nie przepisuje ID w plikach .html.
Zatwierdź folder content/.
Krok 4: Edycja pliku i wysyłanie
Pliki są źródłem prawdy dla push. Zmień stanowisko Jane w pliku JSON
z Design Lead na Head of Design, a następnie sprawdź, co się stanie:
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 wyświetla ten sam plan w kolejności wysyłania. Zastosuj go:
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
Przed zapisaniem wysyłanie sprawdza cały plan. Nierozwiązane zadeklarowane odwołania, konflikty slugów, brakujące typy wpisów i nieprawidłowe pliki przerywają działanie.
WordPress nadaje zaktualizowanemu wpisowi nową datę modyfikacji, podczas gdy plik nadal
zawiera starą wartość modified. Dlatego uruchomienie status zaraz po wysłaniu
zgłosi wpis Jane jako conflict z komunikatem „Baza danych zmieniła się od ostatniej
synchronizacji”. Po wysłaniu uruchom raz pull, aby zapisać nową datę;
status zgłosi wtedy unchanged.
Krok 5: Przeniesienie treści do innego środowiska
W nowym środowisku pliki opisują wpisy, które jeszcze nie istnieją. W tym przykładzie taksonomia i załącznik ze zdjęciem już tam są i mają te same UID-y, więc brakuje tylko dwóch członków zespołu:
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
Wpisy otrzymały nowe lokalne ID: 536 i 537. Odwołania zostały
zaktualizowane: pole _acme_mentor Sama zawiera teraz 536, Jane ponownie należy do
terminu leadership, a jej _thumbnail_id wskazuje lokalny załącznik o pasującym UID. Rodzice
wpisów, rodzice terminów i relacje terminów są zawsze przechowywane jako UID-y;
wartości meta są przepisywane tylko dla kluczy w meta.references.
Bezpieczne usuwanie zbędnych elementów
Usunięcie pliku nie usuwa niczego podczas wysyłania, chyba że o to poprosisz.
Usuń sam.208db72e.json i spróbuj usunąć zbędne elementy:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Uruchomienie próbne pokazuje, co zostałoby usunięte:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
Następnie push --prune --yes przenosi wpis Sama do kosza i zgłasza pruned-trash. Kilka
zabezpieczeń ogranicza zakres działania:
- Kandydatami są wyłącznie encje należące do tego zestawu treści (
content.id). - Uwzględniane są wyłącznie skonfigurowane typy wpisów i taksonomie.
- Cały plan źródłowy jest analizowany i sprawdzany, zanim cokolwiek zostanie zapisane
lub usunięte. Jeśli w folderze znajduje się nieprawidłowy plik JSON, wysyłanie
zgłasza wiersz
error, taki jakcould not be read: Syntax error, i niczego nie usuwa.
Domyślną czynnością jest trash. Filtr blockstudio/content/orphan_action może zwrócić dla każdej encji
trash, delete lub keep. Dzięki temu terminy są zachowywane, a wpisy pozostają
przy ustawieniu domyślnym:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Dzięki temu osierocony termin jest zgłaszany jako would-prune-keep zamiast
would-prune-trash.
Multimedia
Pliki multimedialne nigdy nie są kopiowane. content.media określa, co dzieje się z zadeklarowanymi
odwołaniami do załączników:
"manifest"(domyślnie) przechowuje UID-y załączników i umieszcza je wcontent/media/manifest.jsonwraz ze ścieżką, typem MIME i tekstem alternatywnym. Wysyłanie wymaga, aby każdy wskazany UID załącznika istniał w środowisku docelowym, więc najpierw przenieś pliki przesłane na serwer za pomocą zwykłego procesu obsługi multimediów."none"pomija w plikach zadeklarowane odwołania do załączników. Pole JSON Jane zawiera wtedy tylko_acme_role. Ponieważ pominięty klucz nie jest stosowany podczas wysyłania, istniejący wpis docelowy zachowuje bieżącą miniaturę.
Blokowanie encji
Czasami środowisko docelowe musi zachować własną wersję wpisu. Ustaw
metadane _blockstudio_content_locked tego wpisu na wartość prawdziwą. Wysyłanie pominie go wtedy
wierszem locked z komunikatem „Pominięto zablokowaną encję”. Usuń te metadane,
aby ponownie uwzględnić wpis.
Zasady własności
- Wpisy zarządzane przez strony oparte na plikach są domyślnie wykluczone. Przy
includePageSyncManaged: trueContent Sync może synchronizować skonfigurowane metadane tych wpisów, ale Page Sync nadal zarządza ichpost_content. Te projekcje JSON zawierająbodyOwner: "page-sync", a pull jawnie zgłasza pominięcie treści. Istniejące kopie do przeglądu.htmlsą zachowywane i ignorowane przez push. Zsynchronizuj strony w środowisku docelowym przed wypchnięciem ich projekcji metadanych. - Autorzy są domyślnie ignorowani, ponieważ użytkownicy nie są synchronizowani. Przy
authors: "login"pliki wpisów przechowują login autora, a push przypisuje go do istniejącego użytkownika; brak użytkownika powoduje błąd podczas kontroli wstępnej. pullnigdy nie usuwa plików. Gdy encja w bazie danych przestaje istnieć, pull zgłasza nieaktualny plik i pozostawia jego usunięcie Tobie.
Kiedy z niego nie korzystać
Content Sync sprawdza się przy wyselekcjonowanych treściach, które rzadko się zmieniają: przy dziesiątkach lub setkach wpisów, a przy uporządkowanych danych podzielonych na wyspecjalizowane typy wpisów nawet przy kilku tysiącach. Nie zastępuje kopii zapasowych ani migracji baz danych. Zamówienia, zgłoszenia z formularzy, logi, analityka i treści redakcyjne publikowane w dużej ilości należą do innych narzędzi. Definicje taksonomii, pliki multimedialne i binarne oraz ID w znacznikach bloków są poza zakresem.
Następne kroki
- Dokumentacja Content Sync: wszystkie klucze konfiguracji, formaty plików i zapisany stan synchronizacji.
- Tworzenie witryny dokumentacji: treści, które zaczynają się w plikach i są synchronizowane WordPress w przeciwnym kierunku.
- Tworzenie stron opartych na plikach: strony, których strukturę określają szablony w motywie.