Custom Fields Não Aparecem no Frontend (ACF): correção

Tipo Page Builders

Nome do erro Custom Fields do ACF PRO não aparecem no frontend EN: ACF PRO custom fields not showing on frontend

Severidade Grave

Descrição Custom fields do ACF PRO que não aparecem no frontend acontecem quando get_field() ou the_field() retorna vazio porque o field group não cobre o post atual, o post_id passado está errado ou o return format não bate com o que o template tenta imprimir.

O que é Custom Fields que não aparecem no frontend (ACF)?

Custom Fields que não aparecem no frontend é quando o campo tem valor salvo no editor do ACF PRO, mas a página pública mostra branco no lugar dele. O valor existe no banco (na tabela wp_postmeta), só não chega ao HTML. Na prática, a função get_field() ou the_field() do tema está sendo chamada com o nome de campo certo, mas no contexto errado: outro post, fora do The Loop, antes de o field group carregar, ou esperando um tipo de dado diferente do que o campo devolve. Por isso o erro é silencioso, sem mensagem fatal: o PHP só imprime uma string vazia.

Como identificar

A área do campo renderiza em branco no frontend, mas o valor aparece preenchido ao editar o post no painel.
var_dump( get_field(‘nome_do_campo’) ) imprime bool(false) ou string vazia em vez do valor salvo.
the_field(‘imagem’) imprime um ID numérico cru ou um array em vez da URL da imagem.
O campo aparece em um post e some em outro do mesmo tipo, ou some apenas no arquivo (archive) e na home.
Depois de migrar de staging para produção, todos os campos passam a vir vazios de uma vez.

Como prevenir

Sempre passe o segundo parâmetro post_id em get_field() e the_field() quando o código rodar fora do single do próprio post.
Versione a pasta acf-json no tema para que field groups viajem com o código e sincronizem automaticamente em cada ambiente.
Escape toda saída de campo com esc_html(), esc_url() ou wp_kses_post() antes de imprimir, evitando que dados quebrem o HTML.
Padronize o uso de field name em vez de field key nas chamadas, reservando o key apenas para registro de campos via PHP.

Causa

O field group está com as Location Rules apontando para outro alvo (ex.: regra Post Type igual a Página, mas o template que imprime é single de Post), então o ACF nem registra o campo para aquele objeto.
A chamada get_field('campo') roda fora do The Loop ou em um template de archive, onde o post atual não é o que tem o valor, e o segundo parâmetro post_id foi omitido.
O nome passado em get_field() é o field name errado ou trocado pelo field key (formato field_xxxxxxxx), que só resolve quando o grupo está sincronizado.
O return format do campo não bate com o template: um campo Image configurado como Array é tratado como se fosse URL, um campo True/False devolve 1 ou 0, e um campo WYSIWYG precisa de the_field() para aplicar os filtros de conteúdo.
Em campos dentro de um Options Page, o get_field() foi chamado sem o segundo parâmetro option, então o ACF procura o valor no post atual e não na tela de opções.
Após migração, o Local JSON em acf-json não foi sincronizado, então o field group existe no banco do staging mas não está registrado no código de produção, e o ACF deixa de devolver o valor.

Como resolver

Confirme que o campo tem valor e descubra o nome real: Edite o post no painel e confirme que o campo está preenchido. Depois imprima o conteúdo direto no template para ver o que o ACF devolve naquele contexto. Se vier vazio aqui, o problema é de contexto ou de registro, não de exibição.
```
var_dump( get_field('nome_do_campo') );
```
Revise as Location Rules do field group: No painel do ACF, abra o field group e confira a aba de localização. A regra precisa cobrir exatamente o objeto que está sendo renderizado (tipo de post, template, taxonomia). Caminho no menu: Custom Fields -> Field Groups -> seu grupo -> Settings -> Location.
```
Custom Fields -> Field Groups -> [grupo] -> Settings -> Location Rules
```
Passe o post_id correto quando estiver fora do post: Se a chamada acontece em archive, home, sidebar ou shortcode, o post atual não é o dono do valor. Informe o ID do post, ou option para Options Page, no segundo parâmetro.
```
the_field('subtitulo', 123);
$valor = get_field('telefone', 'option');
```
Use o return format certo para o tipo de campo: Imagem como Array precisa acessar a chave url, True/False devolve booleano, e WYSIWYG deve sair por the_field() para aplicar os filtros. Ajuste o template ou troque o Return Format na configuração do campo.
```
$img = get_field('imagem');
echo esc_url( $img['url'] );
```
Sincronize o Local JSON depois de migrar: Se os campos sumiram após subir para produção, o field group pode estar só no acf-json e não registrado. Abra a tela de sincronização e importe os grupos pendentes. Caminho no menu: Custom Fields -> Field Groups -> Sync available.
```
Custom Fields -> Field Groups -> Sync available -> Sync changes
```

PHP

<?php
// Exibe um campo ACF com segurança, mesmo fora do post atual.
$post_id = get_the_ID(); // ou um ID fixo / 'option' para Options Page
$valor   = get_field( 'subtitulo', $post_id );

if ( $valor ) {
    echo esc_html( $valor );
}

// Campo de imagem configurado como Array -> use a chave 'url'.
$imagem = get_field( 'imagem_destaque', $post_id );
if ( $imagem && ! empty( $imagem['url'] ) ) {
    printf( '<img src="%s" alt="%s">', esc_url( $imagem['url'] ), esc_attr( $imagem['alt'] ) );
}

Perguntas frequentes

Por que get_field() retorna vazio se o campo está preenchido?

Quase sempre é contexto: a chamada roda fora do The Loop ou em outro post, então o post_id padrão não é o dono do valor. Passe o ID correto no segundo parâmetro ou confira as Location Rules do field group.

Qual a diferença entre get_field() e the_field() para exibir o campo?

get_field() retorna o valor para você usar no PHP, e the_field() já imprime na tela, equivalente a echo get_field(). Para campos WYSIWYG, the_field() é preferível porque aplica os filtros de formatação do conteúdo.

Meu campo de imagem mostra um número em vez da foto, o que é?

O campo está com Return Format igual a ID ou Array. Troque para URL na configuração do campo, ou acesse a chave url do array no template antes de imprimir com esc_url().

Os campos sumiram depois que migrei o site, como recupero?

Os valores continuam no banco, mas o field group não está registrado em produção. Abra Custom Fields -> Field Groups e use Sync available para importar os grupos do acf-json, ou recrie a regra de localização.

Preciso usar field name ou field key na chamada?

Use o field name (ex.: subtitulo) nas chamadas do tema. O field key (field_xxxxxxxx) só resolve com o grupo registrado e serve para registro de campos via PHP, não para leitura no template.

Como exibo um campo de uma Options Page do ACF PRO?

Passe a string option como segundo parâmetro: get_field('telefone', 'option'). Sem isso o ACF procura o valor no post atual e devolve vazio, porque a Options Page não é um post.

Por que o campo aparece no editor mas não no frontend?

O editor lê o valor direto pelo field key, mas o frontend depende do field group estar registrado e da chamada estar no contexto certo. Verifique Location Rules, post_id e se o Local JSON foi sincronizado.

Grave

Como corrigir o Listing Grid vazio no JetEngine

O Listing Grid vazio no JetEngine ocorre quando a query (Post Status, Meta Query, Tax Query, Offset ou Cache Query) não retorna nenhum item para o Listing template. Corrige-se alinhando os parametros do Query Builder a dados que existem no site.

Atenção

Como corrigir o Mega Menu que não exibe submenus no Astra Pro

O Mega Menu do Astra Pro deixa de exibir submenus quando o módulo Nav Menu está inativo, quando o toggle Enable Mega Menu não foi ligado no item pai ou quando os itens de submenu não estão aninhados sob o pai em Aparência -> Menus. Sem submenu aninhado, o Astra não monta as colunas e o menu abre vazio.

Atenção

Como corrigir a incompatibilidade do ACF PRO com o editor Gutenberg

A incompatibilidade do ACF PRO com o Gutenberg ocorre quando o plugin Gutenberg standalone, uma versão defasada do ACF ou um block.json mal registrado impedem que campos e ACF Blocks apareçam no editor de blocos.

Atenção

Como corrigir o Cross Domain Copy Paste que não funciona no Happy Addons

O Happy Addons copy paste não funciona entre sites quando o navegador bloqueia o acesso à área de transferência, a licença Pro não está ativa nos dois domínios ou as versões do Happy Addons Pro estão diferentes, impedindo o X Paste de colar o elemento do Elementor.

Atenção

Como corrigir o Mini Cart que não exibe corretamente no Astra Pro com WooCommerce

O Astra mini cart do WooCommerce que não aparece deixa o icone ausente no header, abre um dropdown vazio ou exibe a janela transparente. A causa quase sempre e o elemento Cart não adicionado no Header Builder, o script wc-cart-fragments bloqueado pelo cache, ou o filtro de fundo do outline cart desligado após migrar do header antigo.

Atenção

Como corrigir o layout quebrado do Blog Pro no Astra Pro no WordPress

O layout quebrado do Blog Pro no Astra Pro acontece quando o módulo Blog Pro não esta ativado nas Astra Options, quando o cache serve um CSS antigo, ou quando um layout personalizado sobrepoe o arquivo do blog, fazendo o grid e as colunas não aplicarem no frontend.

Setores

Extensões

Integrações

Como corrigir Custom Fields que não aparecem no frontend no ACF PRO

O que é Custom Fields que não aparecem no frontend (ACF)?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o Listing Grid vazio no JetEngine

Como corrigir o Mega Menu que não exibe submenus no Astra Pro

Como corrigir a incompatibilidade do ACF PRO com o editor Gutenberg

Como corrigir o Cross Domain Copy Paste que não funciona no Happy Addons

Como corrigir o Mini Cart que não exibe corretamente no Astra Pro com WooCommerce

Como corrigir o layout quebrado do Blog Pro no Astra Pro no WordPress

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos