Przejdź do treści

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:

Powłoka
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.

Dodaj grupę content:

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

Każdy klucz wyznacza granicę:

  • postTypes i taxonomies to listy dozwolonych elementów. Nic spoza nich nie jest odczytywane, zapisywane ani usuwane. Pusta wartość postTypes oznacza, że żadne wpisy nie zostaną zmienione.
  • meta.include określa dozwolone klucze meta, a * oznacza symbole wieloznaczne. meta.exclude zawsze ma pierwszeństwo, a _edit_lock, _edit_last i _wp_old_slug są domyślnie wykluczone.
  • meta.references określa, które wartości meta są identyfikatorami. Content Sync nie zakłada, że liczba całkowita jest identyfikatorem.
  • id okreś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.
  • path to 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:

Powłoka
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

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:

Powłoka
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

Wynik w motywie:

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

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

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:

Powłoka
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.

Symbol wieloznaczny _acme_* wykrył token. Potraktuj meta.include jako granicę zatwierdzania i jawnie wyklucz ten klucz:

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

Powłoka
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 wyświetla ten sam plan w kolejności wysyłania. Zastosuj go:

Powłoka
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

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:

Powłoka
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
Powłoka
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

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:

Powłoka
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.

Uruchomienie próbne pokazuje, co zostałoby usunięte:

Powłoka
wp bs content push --prune --dry-run
Kod
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 jak could 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:

PHP
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 w content/media/manifest.json wraz 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: true Content Sync może synchronizować skonfigurowane metadane tych wpisów, ale Page Sync nadal zarządza ich post_content. Te projekcje JSON zawierają bodyOwner: "page-sync", a pull jawnie zgłasza pominięcie treści. Istniejące kopie do przeglądu .html są 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.
  • pull nigdy 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