Преместване на съдържание от базата данни във файлове със синхронизиране на съдържание
Блоковете, шаблоните и страниците от файлове вече се намират във вашето хранилище. Част от съдържанието не се вписва в този модел, защото редакторите го създават в административния панел: членове на екипа, офиси, казуси. Това съдържание също е важно за проекта. Сайта за тестване му е нужна същата страница за екипа като на продукционния сайт, нов разработчик има нужда от реалистични данни, а проверяващият трябва да вижда кога някой променя длъжност. Дъмповете на базата данни не решават добре нито една от тези задачи. Те съдържат всичко, ID се различават между средите и никой не преглежда разлика 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
След това извлечете данните наистина. Това присвоява постоянен _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
Преди запис изпращането валидира целия план. Неразрешени зададени препратки, конфликти в 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, изпращането отчита ред
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 в обратната посока.
- Изграждане на страници въз основа на файлове: страници, чиято структура се управлява от шаблони в темата.