Template de Blocos Não Aplica no WordPress? Comece Pelo Banco de Dados

Seu arquivo de template está quase certamente sendo ignorado porque uma cópia no banco de dados está vencendo. No instante em que você abre um template no Editor do Site e clica em Salvar, o WordPress grava um registro de post wp_template, e a partir daí é esse registro que é servido no lugar do arquivo .html da pasta do seu tema — então toda edição feita no arquivo depois disso fica invisível no site. Apagar esse registro é a solução, e é a primeira coisa a verificar antes de mexer na hierarquia, no nome do arquivo ou no cache.

Confirme que a cópia no banco existe

Vá em Aparência → Editor → Modelos. Todo template que o WordPress está servindo do banco de dados aparece sinalizado na lista — dependendo da sua versão do WordPress o selo diz “Personalizado” ou o template aparece sob um filtro “Personalizado”. Esse selo é a resposta inteira. Se ele está lá, seu arquivo não está sendo usado.

Dá para checar a mesma coisa pela linha de comando, o que é mais rápido e funciona mesmo quando o Editor do Site está se comportando mal:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Cada linha é uma sobrescrita do banco de dados. O post_name corresponde ao slug do template, então uma linha chamada single está encobrindo o templates/single.html.

Um detalhe que confunde: esses registros são ligados a um tema por um termo de taxonomia, não por um caminho. Se você renomear a pasta do seu tema, os templates salvos continuam no banco mas param de casar com o tema ativo, e o site volta abruptamente a usar os arquivos. Isso parece “minhas personalizações sumiram” em vez de “meu arquivo está sendo ignorado” — mesmo mecanismo, sintoma oposto.

Limpe o registro

No Editor do Site, abra o menu de opções do template (os três pontinhos ao lado dele) e escolha Limpar personalizações — algumas versões chamam de Redefinir. Isso apaga o registro do banco de dados e o controle volta para o arquivo em disco.

Se o menu oferecer Excluir em vez de Limpar personalizações ou Redefinir, aquele template existe somente no banco de dados e não tem arquivo por trás. Excluir remove o template por completo e o WordPress cai para o próximo nível da hierarquia.

Pelo WP-CLI, usando um ID da listagem acima:

wp post delete 482 --force

Seja honesto consigo mesmo sobre o custo: limpar as personalizações descarta em definitivo tudo que você construiu no Editor do Site para aquele template, e não dá para desfazer. Se a versão do Editor do Site tem trabalho de verdade dentro, copie a marcação de blocos antes — abra o template no editor, mude para a visualização de código e cole o resultado no seu arquivo .html. Assim o arquivo vira a fonte da verdade e nada se perde.

Como o WordPress escolhe um template

Temas de blocos usam a mesma lógica de hierarquia dos temas clássicos, só que com arquivos .html em templates/ no lugar de arquivos .php na raiz do tema. O WordPress percorre do mais específico ao menos específico e usa o primeiro arquivo que existir.

Exibindo	Verificado nesta ordem
Um post individual	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Uma página	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Um arquivo de categoria	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Um tipo de post personalizado	single-{post-type}.html → single.html → singular.html → index.html
A página 404	404.html → index.html

Duas coisas passam por cima disso tudo. Primeiro, o registro no banco de dados descrito acima. Segundo, um template atribuído diretamente a um post ou página — abra o editor do post, procure o painel Modelo na barra lateral e veja se há algo específico selecionado ali. Uma atribuição explícita vence a hierarquia sempre, e é invisível a menos que você vá procurar.

Templates baseados em slug são frágeis de um jeito que vale internalizar. page-about.html só casa enquanto o slug da página for about. Renomeie a página para about-us e o template para de ser aplicado, sem aviso e sem erro.

Template versus parte de template

Um template renderiza uma visualização inteira e é selecionado pela hierarquia. Uma parte de template é um fragmento — cabeçalho, rodapé, barra lateral — que os templates puxam para dentro. Partes ficam em parts/, templates ficam em templates/, e as duas coisas são guardadas separadamente no banco como registros wp_template_part.

A confusão clássica: você edita o cabeçalho e a mudança aparece em páginas que você não queria mexer. Esse comportamento está correto. Uma parte é compartilhada por todo template que a inclui. Se você quer um cabeçalho diferente em um template só, precisa de um segundo arquivo de parte e de um template que faça referência a ele — editar a parte compartilhada nunca vai te dar variação por template.

O contrário também acontece. Você coloca um layout de página inteira em parts/ e fica sem entender por que a hierarquia nunca o escolhe. Partes não são candidatas na hierarquia; nada vai rotear diretamente para elas, nunca.

Nome e local do arquivo

Confira estes pontos antes de supor algo mais exótico:

• A pasta é templates/, no plural, na raiz do tema. Não template/, não block-templates/. block-templates/ era o nome correto na época do plugin Gutenberg, antes de temas de blocos entrarem no core, e muito tutorial ainda mostra isso — não funciona no WordPress atual.
• Partes de template vão em parts/, não em template-parts/ (essa é a convenção dos temas clássicos para partials em PHP).
• A extensão é .html. Um arquivo .php dentro de templates/ é ignorado.
• Nomes de arquivo são em minúsculas e usam hifens. single-Post.html ou single_post.html não vão casar. Em um sistema de arquivos que não diferencia maiúsculas, como o do macOS, isso funciona localmente e quebra em um servidor Linux — o clássico “na minha máquina funciona”.
• templates/index.html precisa existir. Sem ele, o WordPress não classifica o tema como tema de blocos e o Editor do Site pode nem aparecer.
• Se você trabalha em um tema filho, os templates dele têm prioridade sobre os do tema pai. Um arquivo esquecido no tema filho vai silenciosamente vencer o arquivo do pai que você está editando.

Templates personalizados que devem ficar selecionáveis no editor de posts também precisam ser declarados no theme.json em customTemplates, com o nome-base do arquivo, um título legível e os tipos de post aos quais se aplicam. Sem essa entrada o arquivo existe mas nunca aparece no painel Modelo.

Cache — verifique por último

Cache é um problema real, mas é a causa menos provável, e começar por ele é como se perde uma tarde inteira.

Limpe seu cache de página e, se você usa um cache de objeto persistente como Redis ou Memcached, esvazie ele também — os resultados da resolução de template podem ficar guardados ali. Depois recarregue ignorando o cache do navegador.

O que não vai ajudar: limpar o OPcache. Templates de blocos são arquivos .html e nunca são compilados pelo PHP, então o OPcache não tem nada a ver com eles. Se limpar o OPcache pareceu resolver isso uma vez, alguma outra coisa mudou ao mesmo tempo.

Ainda travado?

Sem registro no banco de dados, com o nome de arquivo correto, sem atribuição explícita de template no post e com os caches já limpos, olhe para os plugins. Qualquer coisa que filtre a resolução de template — um construtor de páginas, um plugin de área de membros, um plugin multilíngue, um LMS — pode trocar o template por outro no fim da requisição. Mude para um tema de blocos padrão e teste com os plugins desativados, depois reative um de cada vez.

E se o template está sendo aplicado mas renderiza vazio, o problema é outro: verifique se a marcação de blocos do arquivo é válida, já que um comentário de bloco malformado faz o editor descartar o conteúdo em silêncio em vez de exibir um erro.