Перенесення вмісту бази даних у файли за допомогою Content Sync
Блоки, шаблони й сторінки на основі файлів уже містяться у вашому репозиторії. Частина вмісту не вписується в цю модель, адже редактори створюють її в адмінпанелі: члени команди, офісні адреси, приклади робіт. Цей вміст усе одно важливий для проєкту. На проміжному сайті потрібна та сама сторінка команди, що й на робочому; новому розробнику потрібні реалістичні дані, а рецензент має бачити зміни в назві посади. Дампи бази даних не вирішують цих завдань: вони містять усе, ідентифікатори різняться в різних середовищах, а ніхто не перевіряє зміни SQL.
Content Sync закриває цю прогалину. Команда WP-CLI проєктує список дозволених записів, термінів, зв’язків і метаданих у файли JSON та HTML у вашій темі. Інша команда застосовує ці файли до іншої бази даних. Кожна сутність отримує переносний UID, а посилання між сутностями переписуються лише там, де ви це вкажете.
У цьому посібнику розглянуто каталог команди: як перенести його у файли, перевірити їх, відредагувати файл, перемістити його в нове середовище та безпечно очистити.
Приклад
Тема реєструє тип запису acme_member і таксономію acme_team у
кожному середовищі. Кожен запис учасника може містити:
| Ключ метаданих | Містить |
|---|---|
_acme_role |
Посаду, звичайний рядок |
_acme_mentor |
ID запису іншого учасника |
_thumbnail_id |
ID вкладення з портретом |
_acme_api_token |
Токен інтеграції, який ніколи не має потрапити до git |
Content Sync не реєструє типи записів або таксономії. Вони мають існувати в кожному середовищі, до якого ви надсилаєте дані.
Крок 1: налаштуйте Content Sync
Content Sync вимкнено, доки ви не ввімкнете його в blockstudio.json. До цього кожна
команда повертає один рядок 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.
Додайте групу 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"
}
}
Кожен ключ визначає межу:
postTypesіtaxonomies— списки дозволеного. За їхні межами нічого не читається, не записується й не очищується. Порожнє значенняpostTypesозначає, що жодні записи не обробляються.meta.includeвизначає дозволені ключі метаданих за допомогою шаблонів*.meta.excludeзавжди має вищий пріоритет, а_edit_lock,_edit_lastі_wp_old_slugвиключено за замовчуванням.meta.referencesвизначає, які значення метаданих є ID. Content Sync не вгадує, що ціле число є ID.idзадає назву набору контенту. Вона зберігається для кожної синхронізованої сутності, а під час очищення обробляються лише сутності з того самого набору.path— це вихідна папка відносно каталогу активної теми.
Крок 2: перенесіть дані
Спершу перегляньте проєкцію. Нічого не записується, а показані UID ще не зберігаються:
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
Потім виконайте перенесення. Для кожної
сутності без UID буде призначено постійний _blockstudio_content_uid, а файли буде записано:
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
Результат у темі:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Назви файлів утворюються зі slug і першої частини UID. Запис 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"
}
}
Зв’язок із терміном і мініатюра зберігаються як UID, а не як локальні ID. Тіло запису
зберігається поруч у jane.5d4bf9b5.html як необроблена розмітка блоків. Для запису з порожнім
вмістом, як у Сема, файл .html не створюється. Значення _acme_mentor Сема зберігається як UID Джейн,
оскільки цей ключ оголошено як посилання post.
Крок 3: перевірте перед комітом
Перед комітом виконайте status. Команда порівнює файли й базу даних, а також позначає
ризиковані дані:
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.
Шаблон _acme_* виявив токен. Вважайте meta.include межею коміту
й явно виключіть цей ключ:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Наступний pull переписує sam.208db72e.json без токена й не змінює
інші файли. status також попереджає про числові ID у тілах розмітки блоків, оскільки Content Sync не переписує ID у файлах .html.
Закомітьте папку content/.
Крок 4: відредагуйте файл і надішліть зміни
Файли — джерело істини для push. Змініть посаду Джейн у файлі JSON
з Design Lead на Head of Design, а потім перевірте, що станеться:
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 виводить той самий план у порядку надсилання. Застосуйте його:
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 перевіряє весь план. Невирішені оголошені посилання, конфлікти slug, відсутні типи записів і некоректні файли зупиняють виконання.
WordPress присвоює оновленому запису новий час зміни, тоді як у файлі досі зберігається
старе значення modified. Тому запуск status одразу після цього надсилання повідомить, що запис Джейн має стан conflict із повідомленням «Базу даних змінено після останньої синхронізації». Один раз виконайте pull
після надсилання, щоб зафіксувати новий час; тоді status повідомить про unchanged.
Крок 5: перенесіть контент в інше середовище
У новому середовищі файли описують записи, яких там ще немає. У цьому прикладі термін і вкладення з портретом уже є там із такими самими UID, тож бракує лише двох учасників:
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
Записи отримали нові локальні ID: 536 і 537. Посилання оновилися: у _acme_mentor Сема
тепер міститься 536, Джейн знову належить до терміна leadership, а її
_thumbnail_id вказує на локальне вкладення з відповідним UID. Батьківські записи, батьківські терміни та зв’язки між термінами завжди зберігаються як UID; значення метаданих переписуються лише для ключів у meta.references.
Безпечне очищення
Видалення файлу саме по собі не видаляє нічого під час надсилання, якщо ви цього не попросите. Видаліть
sam.208db72e.json і спробуйте очистити дані:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Пробний запуск показує, що буде видалено:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
Потім push --prune --yes переміщує запис Сема до кошика й повідомляє про
pruned-trash. Кілька запобіжників звужують межі операції:
- Кандидатами можуть бути лише сутності, що належать цьому набору контенту (
content.id). - Розглядаються лише налаштовані типи записів і таксономії.
- Увесь вихідний план розбирається й перевіряється до будь-якого запису чи
очищення. Якщо в папці є некоректний файл JSON, push повідомляє про рядок
error, як-отcould not be read: Syntax error, і нічого не очищує.
За замовчуванням виконується дія trash. Фільтр blockstudio/content/orphan_action
може повертати trash, delete або keep для кожної сутності. Так можна зберегти терміни,
залишивши для записів дію за замовчуванням:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Завдяки цьому для осиротілого терміна повідомляється would-prune-keep замість
would-prune-trash.
Медіафайли
Медіафайли ніколи не копіюються. content.media визначає, що робити з оголошеними
посиланнями на вкладення:
"manifest"(за замовчуванням) зберігає UID вкладень і перелічує їх уcontent/media/manifest.jsonразом зі шляхом, типом MIME і альтернативним текстом. Push вимагає, щоб UID кожного вкладення, на яке є посилання, існував у цільовому середовищі, тож спершу перенесіть завантаження звичним для вас способом роботи з медіафайлами."none"не додає до файлів оголошені посилання на вкладення. У JSON Джейн тоді міститься лише_acme_role. Оскільки пропущений ключ не застосовується під час надсилання, наявна мініатюра запису в цільовому середовищі зберігається.
Блокування сутності
Іноді в цільовому середовищі потрібно зберегти власну версію певного запису. Установіть
для метаданих _blockstudio_content_locked цього запису істинне значення, і push пропустить
його, додавши рядок locked із повідомленням «Сутність заблоковано й пропущено». Видаліть метадані, щоб знову включити запис.
Правила керування
- За замовчуванням публікації, якими керують сторінки на основі файлів, виключено. З
includePageSyncManaged: trueContent Sync може синхронізувати їхні налаштовані метадані, але Page Sync і далі керує їхнімpost_content. Ці проєкції JSON містятьbodyOwner: "page-sync", а під час отримання даних явно повідомляється про пропущений вміст. Наявні копії для перевірки.htmlзберігаються, а надсилання їх ігнорує. Синхронізуйте сторінки в цільовому середовищі, перш ніж надсилати проєкції їхніх метаданих. - Автори за замовчуванням ігноруються, оскільки користувачі не синхронізуються. З
authors: "login"файли публікацій зберігають логін автора, а під час надсилання даних система знаходить відповідного наявного користувача; якщо його немає, попередня перевірка завершується помилкою. pullніколи не видаляє файли. Якщо об’єкт більше не існує в базі даних, під час отримання даних його файл позначається як застарілий, а очищення залишається за вами.
Коли не варто використовувати
Content Sync підходить для відібраного контенту, що рідко змінюється: десятків або сотень записів, а також кількох тисяч, якщо дані структуровано й розподілено між спеціалізованими типами записів. Він не замінює резервне копіювання баз даних або міграції. Замовлення, надсилання форм, журнали, аналітика й редакційний контент у великих обсягах належать до інших інструментів. Визначення таксономій, бінарні файли медіа та ID у розмітці блоків не входять до його сфери застосування.
Наступні кроки
- Довідка з Content Sync: усі ключі конфігурації, формати файлів і збережений стан синхронізації.
- Створення сайту документації: контент починається у файлах і синхронізується в WordPress у зворотному напрямку.
- Створення сторінок на основі файлів: сторінки, структуру яких визначають шаблони в темі.