Saltar al contenido

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:

Shell
wp bs content status
Código
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:

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

Cada clave marca un límite:

  • postTypes y taxonomies son listas permitidas. No se lee, escribe ni depura nada fuera de ellas. Si postTypes está vacío, no se toca ninguna entrada.
  • meta.include especifica las claves meta permitidas, con comodines *. meta.exclude siempre tiene prioridad y _edit_lock, _edit_last y _wp_old_slug se excluyen de forma predeterminada.
  • meta.references declara qué valores meta son IDs. Content Sync nunca supone que un entero sea un ID.
  • id nombra el conjunto de contenido. Se almacena en cada entidad sincronizada y la depuración solo afecta a entidades del mismo conjunto.
  • path es 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:

Shell
wp bs content pull --dry-run
Código
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:

Shell
wp bs content pull
Código
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:

Código
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:

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

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:

Shell
wp bs content status
Código
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:

JSON
"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:

Shell
wp bs content status
Código
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:

Shell
wp bs content push
Código
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:

Shell
wp bs content status
Código
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
Shell
wp bs content push
Código
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:

Shell
wp bs content push --prune
Código
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:

Shell
wp bs content push --prune --dry-run
Código
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, como could 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:

PHP
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 en content/media/manifest.json con 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 su post_content. Esas proyecciones JSON llevan bodyOwner: "page-sync", y la extracción informa explícitamente del cuerpo omitido. Las copias de revisión existentes de .html se 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.
  • pull nunca 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