Перейти к содержимому

Перенос содержимого базы данных в файлы с помощью синхронизации содержимого

Блоки, шаблоны и страницы на основе файлов уже хранятся в репозитории. Некоторое содержимое не вписывается в эту модель, потому что его создают редакторы в административной панели: участники команды, расположение офисов, истории клиентов. Эти данные по-прежнему важны для проекта. На тестовом сайте нужна та же страница команды, что и на рабочем, новому разработчику нужны реалистичные данные, а проверяющий должен видеть изменения в названии должности. Дампы баз данных с этой задачей не справляются: в них попадает всё, 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:

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

Каждый ключ задаёт границу:

  • 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 содержит поля, связи с терминами и разрешённые метаданные:

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 границей фиксации и явно исключите ключ:

JSON
"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. Так можно сохранять термины, оставляя для записей действие по умолчанию:

PHP
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: true Content Sync может синхронизировать заданные для них метаданные, но Page Sync по-прежнему отвечает за их post_content. В этих проекциях JSON содержится bodyOwner: "page-sync", а при pull явно сообщается о пропущенном содержимом записи. Существующие проверочные копии .html сохраняются, а push их игнорирует. Перед отправкой проекций метаданных синхронизируйте страницы в целевом окружении.
  • Авторы по умолчанию игнорируются, поскольку пользователи не синхронизируются. С параметром authors: "login" файлы записей хранят логин автора, а push сопоставляет его с существующим пользователем; если пользователь не найден, проверка перед выполнением завершается ошибкой.
  • pull никогда не удаляет файлы. Если сущность в базе данных удалена, pull сообщает об устаревшем файле и оставляет его удаление вам.

Когда не следует использовать

Content Sync подходит для отобранного содержимого, которое редко меняется: десятки или сотни записей, вплоть до нескольких тысяч, если данные структурированы и разделены по специализированным типам записей. Это не замена резервным копиям базы данных или миграциям. Заказы, отправленные формы, журналы, аналитика и редакционное содержимое большого объёма относятся к другим инструментам. Определения таксономий, бинарные медиафайлы и ID внутри разметки блоков не входят в область действия.

Следующие шаги