Pasar el contenido de la base de datos a archivos con Content Sync
Los bloques, las plantillas y las páginas basadas en archivos ya están en el repositorio. Parte del contenido no encaja en ese modelo porque los editores lo crean en el panel de administración: miembros del equipo, ubicaciones de oficinas y casos de estudio. Ese contenido sigue siendo importante para el proyecto. Un sitio de pruebas necesita la misma página del equipo que producción, un nuevo desarrollador necesita datos realistas y un revisor debería ver si alguien cambia el nombre de un puesto. Las copias de la base de datos no resuelven bien nada de esto: incluyen todo, los IDs varían entre entornos y nadie revisa un diff SQL.
Content Sync cubre esa carencia. Un comando WP-CLI proyecta una lista permitida de entradas, términos, relaciones y metadatos en archivos JSON y HTML dentro del tema. Otro comando aplica esos archivos a otra base de datos. Cada entidad recibe un UID portátil y las referencias entre entidades se reescriben solo cuando usted las declara.
Esta guía recorre un directorio de equipo: exportarlo a archivos, revisarlos, editar un archivo, trasladarlo a un entorno nuevo y depurarlo de forma segura.
El ejemplo
El tema registra un tipo de entrada acme_member y una taxonomía acme_team en cada entorno. Cada entrada de miembro puede incluir:
| Clave meta | Contenido |
|---|---|
_acme_role |
El cargo, una cadena de texto simple |
_acme_mentor |
El ID de entrada de otro miembro |
_thumbnail_id |
El ID del adjunto del retrato |
_acme_api_token |
Un token de integración que nunca debe llegar a git |
Content Sync nunca registra tipos de entrada ni taxonomías. Deben existir allí donde se haga el envío.
Paso 1: Configurar Content Sync
Content Sync está desactivado hasta que lo habilite en blockstudio.json. Hasta entonces, cada comando devuelve una única fila 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.
Añada un grupo 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"
}
}
Cada clave marca un límite:
postTypesytaxonomiesson listas permitidas. No se lee, escribe ni depura nada fuera de ellas. SipostTypesestá vacío, no se toca ninguna entrada.meta.includeespecifica las claves meta permitidas, con comodines*.meta.excludesiempre tiene prioridad y_edit_lock,_edit_lasty_wp_old_slugse excluyen de forma predeterminada.meta.referencesdeclara qué valores meta son IDs. Content Sync nunca supone que un entero sea un ID.idnombra el conjunto de contenido. Se almacena en cada entidad sincronizada y la depuración solo afecta a entidades del mismo conjunto.pathes la carpeta de salida, relativa al directorio del tema activo.
Paso 2: Exportar
Primero, obtenga una vista previa de la proyección. No se escribe nada y los UID mostrados aún no se han almacenado:
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
Después, exporte de verdad. Esto asigna un _blockstudio_content_uid permanente a cada entidad que aún no lo tenga y escribe los archivos:
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
El resultado en el tema:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Los nombres de archivo combinan el slug con la primera parte del UID. La entrada JSON contiene los campos, las relaciones con términos y los metadatos permitidos:
{
"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"
}
}
La relación con el término y la miniatura son UID, no ID locales. El contenido de la entrada está junto a ella, en jane.5d4bf9b5.html, como marcado de bloques sin procesar. Una entrada sin contenido, como la de Sam, no genera ningún archivo .html. El _acme_mentor de Sam se almacena como el UID de Jane, porque la clave está declarada como referencia post.
Paso 3: Revisar antes de confirmar
Ejecute status antes de confirmar. Compara los archivos con la base de datos y también señala datos de riesgo:
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.
El comodín _acme_* detectó el token. Considere meta.include un límite para las confirmaciones y excluya la clave explícitamente:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
El siguiente pull vuelve a escribir sam.208db72e.json sin el token y deja intactos los demás archivos. status también advierte sobre los ID numéricos en el contenido del marcado de bloques, porque Content Sync no reescribe los ID en archivos .html.
Confirme la carpeta content/.
Paso 4: Editar un archivo y enviarlo
Los archivos son la fuente de verdad para push. Cambie el cargo de Jane en el archivo JSON de Design Lead a Head of Design y compruebe qué ocurriría:
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 muestra el mismo plan en el orden de envío. Aplíquelo:
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
El envío valida el plan completo antes de escribir. Si hay referencias declaradas sin resolver, conflictos de slug, tipos de entrada ausentes o archivos malformados, se detiene.
WordPress asigna una nueva hora de modificación a una entrada actualizada, mientras que el archivo conserva el valor anterior de modified. Por eso, una ejecución de status justo después de este envío informa que la entrada de Jane está conflict con el mensaje «La base de datos cambió desde la última sincronización». Ejecute pull una vez después del envío para guardar la nueva hora; entonces status informa unchanged.
Paso 5: Trasladar el contenido a otro entorno
En un entorno nuevo, los archivos describen entradas que aún no existen. En este ejemplo, el término y el adjunto del retrato ya existen allí con los mismos UID, así que solo faltan los dos miembros:
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
Las entradas recibieron nuevos ID locales, 536 y 537. Las referencias también se actualizaron: el _acme_mentor de Sam ahora contiene 536, Jane vuelve a estar en el término leadership y su _thumbnail_id apunta al adjunto local con el UID correspondiente. Los padres de entradas, los padres de términos y las relaciones con términos siempre se almacenan como UID; los valores meta solo se reescriben para las claves de meta.references.
Depurar de forma segura
Eliminar un archivo no elimina nada al hacer el envío, a menos que lo solicite. Elimine sam.208db72e.json e intente depurar:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
La ejecución de prueba muestra qué se eliminaría:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
A continuación, push --prune --yes mueve la entrada de Sam a la papelera e informa pruned-trash. Varias medidas de seguridad mantienen acotada la operación:
- Solo pueden seleccionarse entidades pertenecientes a este conjunto de contenido (
content.id). - Solo se tienen en cuenta los tipos de entrada y las taxonomías configurados.
- Se analiza y valida todo el plan de origen antes de escribir o depurar nada. Si hay un archivo JSON malformado en la carpeta, el envío informa una fila
error, comocould not be read: Syntax error, y no depura nada.
La acción predeterminada es trash. El filtro blockstudio/content/orphan_action puede devolver trash, delete o keep para cada entidad. Así se conservan los términos y se deja el valor predeterminado para las entradas:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Con ello, un término huérfano se informa como would-prune-keep en vez de would-prune-trash.
Medios
Los archivos multimedia nunca se copian. content.media determina qué ocurre con las referencias declaradas a adjuntos:
"manifest"(predeterminado) almacena los UID de los adjuntos y los enumera encontent/media/manifest.jsoncon la ruta, el tipo MIME y el texto alternativo. El envío requiere que cada UID de adjunto referenciado exista en el destino, así que primero traslade los archivos subidos con su flujo de trabajo habitual para medios."none"omite de los archivos las referencias declaradas a adjuntos. Entonces el JSON de Jane solo contiene_acme_role. Como una clave omitida no se aplica al hacer el envío, una entrada existente en el destino conserva su miniatura actual.
Bloquear una entidad
A veces, un entorno de destino debe conservar su propia versión de una entrada. Asigne un valor verdadero a los metadatos _blockstudio_content_locked de esa entrada y el envío la omitirá con una fila locked y el mensaje «Se omitió la entidad bloqueada». Elimine los metadatos para volver a incluirla.
Reglas de propiedad
- Las entradas gestionadas por páginas basadas en archivos se excluyen de forma predeterminada. Con
includePageSyncManaged: true, Content Sync puede sincronizar sus metadatos configurados, pero Page Sync sigue siendo responsable de supost_content. Esas proyecciones JSON llevanbodyOwner: "page-sync", y la extracción informa explícitamente del cuerpo omitido. Las copias de revisión existentes de.htmlse conservan y se ignoran al enviar cambios. Sincroniza las páginas en un entorno de destino antes de enviar sus proyecciones de metadatos. - Los autores se ignoran de forma predeterminada porque los usuarios no se sincronizan. Con
authors: "login", los archivos de entradas almacenan el nombre de usuario del autor y el envío resuelve ese nombre a un usuario existente; si falta el usuario, se produce un error en la comprobación previa. pullnunca elimina archivos. Cuando una entidad de la base de datos ya no existe, la extracción informa que su archivo está obsoleto y deja la limpieza en tus manos.
Cuándo no usarlo
Content Sync es adecuado para contenido seleccionado que cambia poco: decenas o cientos de entradas, hasta unos pocos miles si los datos están estructurados y divididos en tipos de entrada específicos. No reemplaza las copias de seguridad ni las migraciones de bases de datos. Los pedidos, envíos de formularios, registros, análisis y el contenido editorial de gran volumen corresponden a esas herramientas. Las definiciones de taxonomías, los archivos binarios multimedia y los ID dentro del marcado de bloques quedan fuera de su alcance.
Próximos pasos
- Referencia de Content Sync: todas las claves de configuración, los formatos de archivo y el estado de sincronización almacenado.
- Crear un sitio de documentación: contenido que empieza en archivos y se sincroniza con WordPress en sentido inverso.
- Crear páginas basadas en archivos: páginas cuya estructura pertenece a las plantillas del tema.