Sincronización de contenido
Blockstudio se basa en un flujo de trabajo que prioriza los archivos: los bloques, campos, plantillas, recursos, patrones y páginas basadas en archivos pueden residir en tu proyecto. La sincronización de contenido amplía ese modelo al contenido seleccionado de la base de datos de WordPress para los equipos que también quieren mantener en git entradas, términos, relaciones y metadatos declarados seleccionados.
Es un flujo de trabajo WP-CLI, no una replicación activa de la base de datos. Al importar, la sincronización de contenido proyecta las entradas, postmeta, términos, termmeta y relaciones entre entradas y términos permitidos en archivos portátiles de tu tema. Al publicar, aplica esos archivos a otro entorno mediante UID estables y solo reescribe las referencias que declares explícitamente.
Nota
La sincronización de contenido se ejecuta bajo demanda. No se ejecuta con cada solicitud de administración. Los comandos devuelven una fila omitida hasta que
content.enabledestétrue.
Cuándo usar la sincronización de contenido
Usa la sincronización de contenido para conjuntos de contenido importantes para versionar, revisar y mover entre entornos:
- contenido estructurado, como miembros del equipo, ubicaciones, casos prácticos, productos, entradas de documentación o páginas de campañas
- taxonomías y relaciones asociadas a esos conjuntos de contenido
- metadatos permitidos que sea seguro confirmar y necesiten referencias estables
- conjuntos de contenido pequeños o medianos, cuyos archivos aún sea práctico revisar en git
Como regla general, la sincronización de contenido es adecuada para decenas o cientos de filas, y puede llegar a unos pocos miles si los datos están estructurados, cambian poco y se dividen en tipos de contenido centrados. No está pensada para replicar una base de datos de producción entera, contenido editorial de alto tráfico, registros, pedidos, analíticas, envíos de formularios, sesiones ni otros datos de gran volumen o que cambien con frecuencia. Si los archivos generados son demasiado ruidosos para revisar, cuesta demasiado evaluar las publicaciones o la mayoría de las filas cambia fuera de tu flujo de despliegue, usa en su lugar una copia de seguridad de la base de datos, una migración o una herramienta de importación y exportación.
Los archivos binarios multimedia no se copian. Las referencias a archivos adjuntos pueden registrarse en un manifiesto y validarse, pero los propios archivos deben existir en el entorno de destino.
Configuración
Activa la sincronización de contenido en blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"content": {
"enabled": true,
"id": "default",
"path": "content",
"includePageSyncManaged": false,
"authors": "ignore",
"postTypes": ["team_member"],
"meta": {
"include": ["_my_*"],
"exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
"references": {
"_thumbnail_id": { "kind": "attachment" },
"_related_posts": { "kind": "post", "path": "*" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
},
"taxonomies": [],
"media": "manifest"
}
}
postTypes es una lista de permitidos. Si está vacía, la sincronización de contenido no modifica las entradas. taxonomies es una lista de taxonomías ya registradas cuyos términos y relaciones con entradas deben sincronizarse. Blockstudio no registra definiciones de taxonomía a partir de archivos de sincronización de contenido. postmeta y termmeta se incluyen en la lista de permitidos mediante meta.include; meta.exclude siempre tiene prioridad.
Advertencia
Trata
meta.includecomo un límite de confirmación. Los archivos sincronizados están pensados para incluirse en git, así que no incluyas claves que contengan secretos, tokens, credenciales ni información personal identificable.wp bs content statusgenera filas de advertencia cuando una clave de metadatos permitida parece sensible.
content.id se almacena en las entidades sincronizadas como _blockstudio_content_set. Las comprobaciones de depuración y propiedad se limitan a ese valor, de modo que un conjunto de contenido no puede eliminar el contenido de otro.
Las entradas gestionadas por la sincronización de páginas se excluyen de forma predeterminada. Si se activa includePageSyncManaged, la sincronización de contenido puede sincronizar sus metadatos configurados, pero la sincronización de páginas sigue siendo responsable de post_content.
Estas proyecciones contienen "bodyOwner": "page-sync". Pull informa de la escritura de JSON como solo de metadatos y añade una fila de cuerpo skipped, en lugar de mostrar la entrada como si tuviera el cuerpo vacío. No escribe ni elimina un archivo .html asociado. Se conserva una copia de revisión existente y push la ignora. Los mismos mensajes de propiedad se incluyen en el resultado de la ejecución de prueba.
En otro entorno, ejecute primero Page Sync. Una proyección con
bodyOwner: "page-sync" debe hacer referencia a una entrada existente administrada por Page Sync;
push se niega a crear un sustituto vacío o a aplicar la copia de revisión de ese cuerpo.
Las proyecciones de versiones anteriores que no incluyen el marcador siguen siendo compatibles.
Los autores se ignoran de forma predeterminada porque los usuarios no se sincronizan. Establece authors: "login" para guardar el nombre de usuario del autor en los archivos de entradas y resolverlo con un usuario existente al publicar. La falta de usuarios genera un error en la comprobación previa; la sincronización de contenido no crea usuarios.
Comandos
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status
pull captura el contenido de la base de datos en archivos. Asigna _blockstudio_content_uid a las entradas dentro del alcance que aún no tengan uno e informa de los archivos obsoletos cuya fuente en la base de datos ya no existe. La importación no elimina los archivos obsoletos.
push aplica los archivos a la base de datos actual. Valida el plan antes de escribir y bloquea las referencias declaradas sin resolver, los conflictos de slugs, las entidades bloqueadas y los tipos de entrada que faltan.
status compara los archivos con la base de datos e informa del estado de cada entidad como unchanged, would-update, missing-db, conflict, locked o orphaned. También advierte sobre claves de metadatos permitidas que parecen secretos antes de que se confirmen esos valores, y sobre los ID numéricos dentro de los cuerpos del marcado de bloques, porque la sincronización de contenido no reescribe los ID en archivos .html.
Usa --dry-run para inspeccionar una importación o publicación sin escribir cambios. Usa push --prune --yes para eliminar entidades de la base de datos propiedad del conjunto de contenido que ya no existen en los archivos.
Seguridad ante fallos
push analiza y valida el plan de origen completo antes de escribir o
eliminar. Los JSON malformados, las referencias declaradas sin resolver, la propiedad no válida y
otros errores de prevalidación bloquean la fase destructiva. La eliminación sigue limitada
a los tipos de contenido, taxonomías y content.id configurados.
pull escribe cada archivo proyectado antes de registrar la entidad como sincronizada. Un
fallo al escribir en el sistema de archivos se devuelve como una fila de error y no actualiza el
estado de sincronización guardado para esa entidad.
La gestión de archivos adjuntos sigue content.media. Con "manifest", los UID de archivos adjuntos referenciados deben existir en el entorno de destino. Con "none", las referencias declaradas a archivos adjuntos se eliminan intencionadamente de la salida portable
en lugar de conservar los ID específicos del entorno.
Archivos
Content Sync escribe archivos en la ubicación content.path configurada:
content/
posts/
team_member/
jane.9b1c0e6e.json
jane.9b1c0e6e.html
terms/
category/
leadership.5e900000.json
media/
manifest.json
Los archivos .json de publicaciones almacenan la identidad, los campos de la publicación, las relaciones con términos, los metadatos declarados y la codificación de los metadatos. El archivo .html contiguo almacena post_content como marcado de bloques sin procesar y se omite cuando el contenido está vacío. Los archivos .json de términos almacenan la identidad, la taxonomía, el slug, el nombre, la descripción, el UID del término superior, los metadatos de término declarados y la codificación de los metadatos.
El otro caso en el que no hay ningún archivo .html es el de un cuerpo propiedad de Page Sync, identificado por
bodyOwner arriba. En las entradas normales cuyo cuerpo queda vacío, pull elimina
el archivo de cuerpo anterior y lo menciona en una fila separada de cuerpo deleted.
{
"uid": "9b1c0e6e-0000-4000-9000-000000000000",
"type": "team_member",
"status": "publish",
"slug": "jane",
"title": "Jane",
"parent": null,
"menuOrder": 0,
"terms": {
"category": ["5e900000-0000-4000-9000-000000000000"]
},
"meta": {
"_my_subtitle": "Creative Director",
"_thumbnail_id": "a1b2c3d4-0000-4000-9000-000000000000"
},
"metaEncoding": {
"_my_subtitle": "scalar",
"_thumbnail_id": "scalar"
}
}
El estado de sincronización guardado es:
| Clave de metadatos | Finalidad |
|---|---|
_blockstudio_content_uid |
Identidad de contenido portable |
_blockstudio_content_set |
Espacio de nombres del conjunto de contenido de content.id |
_blockstudio_content_source |
Ruta del archivo de origen relativa al tema |
_blockstudio_content_fingerprint |
Última huella digital sincronizada del archivo/base de datos |
_blockstudio_content_locked |
Un valor verdadero impide que push sobrescriba la entidad |
Referencias
Content Sync nunca supone que un entero sea un ID. Las referencias solo se reescriben cuando se configuran en meta.references.
{
"meta": {
"references": {
"_related_posts": { "kind": "post", "path": "*" },
"_topic": { "kind": "term" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
}
}
Al extraer, los ID locales de esas rutas se convierten en UID portables. Al insertar, los UID se resuelven de nuevo como ID locales en la base de datos actual.
Los padres de publicaciones, los padres de términos y las relaciones entre publicaciones y términos son referencias estructurales gestionadas por Content Sync y se almacenan automáticamente como UID. Las taxonomías configuradas se escriben en los archivos de publicaciones incluso si están vacías; una matriz vacía borra las relaciones de esa taxonomía al insertar.
Las referencias a archivos adjuntos se validan, no se importan. Con media: "manifest", los archivos adjuntos referenciados aparecen en content/media/manifest.json; al insertar, es necesario que el UID del archivo adjunto referenciado exista localmente. Con media: "none", las referencias declaradas a archivos adjuntos se omiten de los archivos portables. Como las claves omitidas no se aplican al insertar, una publicación de destino existente conserva sus metadatos de adjuntos actuales.
Flujo de trabajo de portabilidad
- Registre el tipo de contenido de destino en cada entorno.
- Configure
content.postTypes,meta.includey las referencias declaradas que haya. - Ejecute
wp bs content pullen el entorno de origen. - Confirme los archivos generados.
- Ejecute
wp bs content pushen el entorno de destino. - Ejecute
wp bs content statuspara verificar que la base de datos coincide con los archivos.
Los archivos son la fuente de verdad para push. La base de datos se vuelca de nuevo en archivos con pull.
Alcance
Content Sync admite:
- publicaciones de tipos de contenido permitidos
- metadatos de publicación permitidos
- términos de taxonomías registradas permitidas
- metadatos de término permitidos
- relaciones entre publicaciones y términos
- referencias
post,attachmentytermdeclaradas - UID portables para publicaciones y términos, y propiedad del conjunto de contenido
- exclusión de Page Sync de forma predeterminada
- validación previa y manifiesto de archivos adjuntos
- gestión de
pull,push,status,--dry-run,--pruney entidades bloqueadas
No se admite la captura de definiciones de taxonomías, la copia de archivos binarios multimedia ni la reescritura de ID en el marcado de bloques.