Перенос содержимого базы данных в файлы с помощью синхронизации содержимого
Блоки, шаблоны и страницы на основе файлов уже хранятся в репозитории. Некоторое содержимое не вписывается в эту модель, потому что его создают редакторы в административной панели: участники команды, расположение офисов, истории клиентов. Эти данные по-прежнему важны для проекта. На тестовом сайте нужна та же страница команды, что и на рабочем, новому разработчику нужны реалистичные данные, а проверяющий должен видеть изменения в названии должности. Дампы баз данных с этой задачей не справляются: в них попадает всё, ID различаются в разных средах, а изменения никто не проверяет в SQL-diff.
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
Имена файлов состоят из ярлыка и начальной части 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
Перед записью отправка проверяет весь план. Неразрешённые объявленные ссылки, конфликты ярлыков, отсутствующие типы записей и некорректные файлы останавливают процесс.
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, отправка сообщает строку
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 и альтернативным текстом. При отправке требуется, чтобы каждое вложение с указанным UID существовало в целевой среде, поэтому сначала перенесите загрузки обычным способом."none"исключает объявленные ссылки на вложения из файлов. Тогда в записи JSON Джейн остаётся только_acme_role. Поскольку пропущенный ключ не применяется при отправке, существующая целевая запись сохраняет текущую миниатюру.
Блокировка сущности
Иногда целевой среде нужно сохранить собственную версию записи. Задайте метаданным _blockstudio_content_locked этой записи
истинное значение, и отправка пропустит её, указав строку locked и сообщение «Заблокированная сущность пропущена». Удалите метаданные, чтобы снова включить запись.
Правила владения
- Записи, которыми управляют файловые страницы, по умолчанию исключены. С параметром
includePageSyncManaged: trueContent Sync может синхронизировать заданные для них метаданные, но Page Sync по-прежнему отвечает за ихpost_content. В этих проекциях JSON содержитсяbodyOwner: "page-sync", а при pull явно сообщается о пропущенном содержимом записи. Существующие проверочные копии.htmlсохраняются, а push их игнорирует. Перед отправкой проекций метаданных синхронизируйте страницы в целевом окружении. - Авторы по умолчанию игнорируются, поскольку пользователи не синхронизируются. С параметром
authors: "login"файлы записей хранят логин автора, а push сопоставляет его с существующим пользователем; если пользователь не найден, проверка перед выполнением завершается ошибкой. pullникогда не удаляет файлы. Если сущность в базе данных удалена, pull сообщает об устаревшем файле и оставляет его удаление вам.
Когда не следует использовать
Content Sync подходит для отобранного содержимого, которое редко меняется: десятки или сотни записей, вплоть до нескольких тысяч, если данные структурированы и разделены по специализированным типам записей. Это не замена резервным копиям базы данных или миграциям. Заказы, отправленные формы, журналы, аналитика и редакционное содержимое большого объёма относятся к другим инструментам. Определения таксономий, бинарные медиафайлы и ID внутри разметки блоков не входят в область действия.
Следующие шаги
- Справочник Content Sync: все ключи конфигурации, форматы файлов и сохранённое состояние синхронизации.
- Создание сайта документации: содержимое, которое изначально хранится в файлах и синхронизируется в WordPress в обратном направлении.
- Создание страниц на основе файлов: страницы, структуру которых определяют шаблоны в теме.