Mover conteúdo do banco de dados para arquivos com Content Sync
Blocos, templates e páginas baseadas em arquivos já vivem no seu repositório. Parte do conteúdo não se encaixa nesse modelo, porque os editores o criam no painel administrativo: membros da equipe, locais de escritório, estudos de caso. Esse conteúdo continua sendo importante para o projeto. Um site de staging precisa ter a mesma página da equipe que o site de produção, um novo desenvolvedor precisa de dados realistas e um revisor deve perceber quando alguém altera o título de uma vaga. Dumps do banco de dados não resolvem bem nenhum desses problemas. Eles contêm tudo, os IDs diferem entre ambientes e ninguém revisa um diff SQL.
Content Sync preenche essa lacuna. Um comando WP-CLI projeta uma lista permitida de posts, termos, relações e metadados em arquivos JSON e HTML no seu tema. Outro comando aplica esses arquivos a um banco de dados diferente. Cada entidade recebe um UID portátil, e as referências entre entidades são reescritas somente onde você as declara.
Este guia percorre um diretório de equipe: exportá-lo para arquivos, revisá-lo, editar um arquivo, transferi-lo para um ambiente novo e fazer a limpeza com segurança.
O exemplo
O tema registra um tipo de post acme_member e uma taxonomia acme_team em
todos os ambientes. Cada post de membro pode conter:
| Chave de metadados | Contém |
|---|---|
_acme_role |
O cargo, uma string simples |
_acme_mentor |
O ID do post de outro membro |
_thumbnail_id |
O ID do anexo do retrato |
_acme_api_token |
Um token de integração que nunca deve chegar a git |
Content Sync nunca registra tipos de post nem taxonomias. Eles precisam existir em todos os ambientes para os quais você envia dados.
Etapa 1: configurar o Content Sync
O Content Sync fica desativado até você habilitá-lo em blockstudio.json. Até lá, todo
comando retorna uma única linha 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.
Adicione um 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 chave define um limite:
postTypesetaxonomiessão listas de permissões. Nada fora delas é lido, gravado ou removido. UmpostTypesvazio significa que nenhum post será afetado.meta.includedefine as chaves de metadados permitidas, com curingas*.meta.excludesempre prevalece, e_edit_lock,_edit_laste_wp_old_slugsão excluídos por padrão.meta.referencesdeclara quais valores de metadados são IDs. Content Sync nunca presume que um número inteiro seja um ID.idnomeia o conjunto de conteúdo. Ele é armazenado em cada entidade sincronizada, e a limpeza só afeta entidades do mesmo conjunto.pathé a pasta de saída, relativa ao diretório do tema ativo.
Etapa 2: exportar
Primeiro, visualize a projeção. Nada é gravado, e os UIDs exibidos ainda não estão armazenados:
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
Depois, faça a exportação de verdade. Isso atribui um _blockstudio_content_uid permanente a cada
entidade que ainda não tenha um e grava os arquivos:
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
O resultado no tema:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Os nomes dos arquivos combinam o slug com o início do UID. O post JSON contém os campos, as relações com termos e os metadados 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"
}
}
A relação com o termo e a imagem em destaque são UIDs, não IDs locais. O corpo do post
fica ao lado dele em jane.5d4bf9b5.html, como marcação de blocos bruta. Um post sem conteúdo,
como o de Sam, não recebe um arquivo .html. O _acme_mentor de Sam é armazenado como
UID de Jane, pois a chave está declarada como referência post.
Etapa 3: revisar antes de confirmar as alterações
Execute status antes de confirmar as alterações. Ele compara os arquivos com o banco de dados e também sinaliza
dados arriscados:
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.
O curinga _acme_* detectou o token. Considere meta.include um limite para as alterações confirmadas e exclua a chave explicitamente:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
O próximo pull regrava sam.208db72e.json sem o token e deixa os outros arquivos intactos. status também alerta sobre IDs numéricos no conteúdo da marcação de blocos, pois Content Sync não reescreve IDs em arquivos .html.
Confirme as alterações na pasta content/.
Etapa 4: editar um arquivo e enviar
Os arquivos são a fonte de verdade do push. Altere o cargo de Jane no arquivo JSON
de Design Lead para Head of Design e confira o que aconteceria:
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 exibe o mesmo plano na ordem de envio. Aplique-o:
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
O envio valida o plano completo antes de gravar. Referências declaradas não resolvidas, conflitos de slug, tipos de post ausentes e arquivos malformados interrompem o processo.
WordPress atribui um novo horário de modificação a um post atualizado, enquanto o arquivo ainda contém
o valor modified antigo. Portanto, uma execução de status logo após esse envio informa que
o post de Jane está conflict com “Banco de dados alterado desde a última sincronização.” Execute pull
uma vez após o envio para registrar o novo horário; então, status informa unchanged.
Etapa 5: transferir o conteúdo para outro ambiente
Em um ambiente novo, os arquivos descrevem posts que ainda não existem. Neste exemplo, o termo e o anexo do retrato já existem nesse ambiente com os mesmos UIDs, então apenas os dois membros estão ausentes:
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
Os posts receberam novos IDs locais, 536 e 537. As referências acompanharam a mudança: o
_acme_mentor de Sam agora contém 536, Jane voltou ao termo leadership, e o
_thumbnail_id dela aponta para o anexo local com o UID correspondente. Os posts pais,
os termos pais e as relações com termos são sempre armazenados como UIDs; os valores de metadados são reescritos somente para as chaves em meta.references.
Remover com segurança
Excluir um arquivo não exclui nada durante o envio, a menos que você solicite. Remova
sam.208db72e.json e tente fazer a limpeza:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
A execução simulada mostra o que seria removido:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes então move o post de Sam para a lixeira e informa
pruned-trash. Várias proteções mantêm o escopo restrito:
- Apenas entidades pertencentes a este conjunto de conteúdo (
content.id) são candidatas. - Apenas os tipos de post e as taxonomias configurados são considerados.
- Todo o plano de origem é analisado e validado antes que algo seja gravado ou
removido. Se houver um arquivo JSON malformado na pasta, o envio informa uma linha
error, comocould not be read: Syntax error, e nada é removido.
A ação padrão é trash. O filtro blockstudio/content/orphan_action
pode retornar trash, delete ou keep para cada entidade. Assim, os termos são mantidos,
enquanto os posts continuam com a ação padrão:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Com isso, um termo órfão é informado como would-prune-keep em vez de
would-prune-trash.
Mídia
Os arquivos de mídia nunca são copiados. content.media determina o que acontece com as referências declaradas
a anexos:
"manifest"(padrão) armazena os UIDs dos anexos e os lista emcontent/media/manifest.jsoncom o caminho, o tipo MIME e o texto alternativo. O envio exige que cada UID de anexo referenciado exista no destino; portanto, transfira os arquivos enviados usando primeiro o fluxo de trabalho de mídia habitual."none"exclui dos arquivos as referências declaradas a anexos. O JSON de Jane passa a conter apenas_acme_role. Como uma chave omitida não é aplicada no envio, um post já existente no destino mantém sua imagem em destaque atual.
Bloquear uma entidade
Às vezes, um ambiente de destino precisa manter sua própria versão de um post. Defina
_blockstudio_content_locked nos metadados desse post com um valor verdadeiro, e o envio
vai ignorá-lo, com uma linha locked e a mensagem “Entidade bloqueada ignorada.” Exclua os metadados para incluí-lo novamente.
Regras de propriedade
- Por padrão, as publicações gerenciadas por páginas baseadas em arquivos são excluídas. Com
includePageSyncManaged: true, o Content Sync pode sincronizar os metadados configurados delas, mas o Page Sync continua responsável pelopost_content. Essas projeções de JSON carregambodyOwner: "page-sync", e a busca informa explicitamente que o corpo foi ignorado. As cópias de revisão.htmlexistentes são preservadas e ignoradas pelo envio. Sincronize as páginas em um ambiente de destino antes de enviar as projeções de metadados. - Por padrão, os autores são ignorados porque os usuários não são sincronizados. Com
authors: "login", os arquivos de publicação armazenam o login do autor, e o envio o associa a um usuário existente; a ausência de um usuário gera um erro de pré-verificação. pullnunca exclui arquivos. Quando uma entidade do banco de dados deixa de existir, a busca informa que o arquivo está obsoleto e deixa a limpeza por sua conta.
Quando não usar
Content Sync é adequado para conteúdo selecionado e com poucas alterações: dezenas ou centenas de entradas, até alguns milhares quando os dados são estruturados e divididos em tipos de post específicos. Não substitui backups nem migrações de banco de dados. Pedidos, envios de formulários, registros, análises e conteúdo editorial de alto volume devem ser gerenciados por essas ferramentas. Definições de taxonomias, arquivos de mídia binários e IDs dentro da marcação de blocos estão fora do escopo.
Próximas etapas
- Referência do Content Sync: todas as chaves de configuração, formatos de arquivo e o estado de sincronização armazenado.
- Criação de um site de documentação: conteúdo que começa em arquivos e é sincronizado com WordPress na direção inversa.
- Criação de páginas baseadas em arquivos: páginas cuja estrutura é controlada por modelos no tema.