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

Quando os ACF custom fields não aparecem no frontend, o valor existe no banco mas o tema chama o campo de forma incorreta: nome errado, fora do Loop, sem post ID ou com Location Rules que não casam com a tela atual. A correção é alinhar a chamada the_field() ou get_field() ao contexto real do template.

## O que é ACF custom fields que não aparecem no frontend?

ACF custom fields que não aparecem no frontend é a situação em que um campo do Advanced Custom Fields PRO foi preenchido no editor do WordPress, mas o valor não é renderizado na página pública. Na maioria dos casos o dado está salvo corretamente no postmeta; o que falha é a forma como o tema solicita esse valor com as funções the_field() ou get_field(). O ACF só retorna o valor quando a função recebe o nome exato do campo e sabe a qual post ele pertence.

O problema também aparece quando o grupo de campos (Field Group) tem Location Rules que não correspondem à tela onde você está editando ou exibindo. Se o grupo está restrito a um post type ou template que não é o atual, o campo nem é carregado para aquele contexto, e a função do tema devolve um valor vazio.

## Como identificar

- A página pública mostra um espaço em branco ou nada no lugar onde o campo deveria aparecer, mesmo com o valor preenchido no admin.
- Ao usar var_dump(get_field('nome_do_campo')) no template, o retorno é exatamente "bool(false)" ou "NULL".
- O campo aparece corretamente no editor do post, mas some no tema (single.php, page.php ou template do page builder).
- Com WP_DEBUG ativo, surge "Notice: Trying to get property of non-object" ou "Undefined variable" na linha que chama the_field().
- O shortcode [acf field="nome_do_campo"] renderiza vazio dentro de um conteúdo ou widget.

## Como prevenir

- Padronize os nomes dos campos em minúsculas com underscore e copie o Field Name direto do painel ao escrever o template, evitando erros de digitação.
- Sempre que chamar get_field() fora do Loop, passe explicitamente o post ID ou 'option' como segundo parâmetro.
- Antes de publicar, valide cada novo campo com var_dump no template e WP_DEBUG ativo em ambiente de staging.
- Documente o Return Format de cada campo de imagem ou link no Field Group para que o time saiba se deve ecoar a URL ou tratar o array.

## Causa

- A função do tema usa o field key (formato field_5f8a1b2c3d4e) em vez do field name legível; the_field() e get_field() esperam o nome do campo, não a chave.
- A chamada the_field() ou get_field() está fora do The Loop e sem o segundo parâmetro de post ID, então o ACF não sabe de qual post buscar o valor e retorna false.
- As Location Rules do Field Group apontam para outro post type, template ou taxonomia, de modo que o grupo não é atribuído à tela atual e o campo não existe naquele contexto.
- O nome do campo na função não bate com o nome real cadastrado no Field Group (diferença de underscore, acento, maiúscula ou plural, como meu_campo versus meucampo).
- O Return Format do campo está como Array ou Image Array, então the_field() imprime vazio porque tenta ecoar uma estrutura em vez de uma string de texto ou URL.
- O valor está em um post diferente (por exemplo um Options Page ou outro post ID) e a função foi chamada sem informar 'option' ou o ID correto como segundo argumento.

## Como resolver

1. Confirme se o valor está salvo no banco com var_dump: No template do tema (por exemplo single.php), antes de qualquer formatação, imprima o valor cru do campo. Se o retorno for false ou NULL, o problema é de contexto ou de nome; se vier o valor, o problema é só de formatação na exibição. Ative WP_DEBUG no wp-config.php para ver os avisos.

```
var_dump( get_field('nome_do_campo') );
```

2. Use o nome do campo, não o field key: Abra Custom Fields, edite o Field Group e confira o valor exato em Field Name (coluna do meio, em minúsculas com underscore). Use esse nome na função, nunca a string que começa com field_. O nome é o identificador legível; a chave field_ é interna do ACF.

```
the_field('preco_promocional');
```

3. Garanta o contexto do post passando o post ID: Se a chamada está fora do Loop (em um header, sidebar, footer ou template de page builder), informe o post ID como segundo parâmetro. Para campos de uma Options Page, passe a string 'option'. Isso elimina o retorno false por falta de contexto.

```
$preco = get_field('preco_promocional', get_the_ID());
$logo = get_field('logo_rodape', 'option');
```

4. Revise as Location Rules do Field Group: Em Custom Fields, edite o grupo e role até Settings -> Location. Confirme que a regra (Post Type igual a, Page Template igual a, Taxonomy etc.) corresponde exatamente à tela onde o campo deve aparecer. Se o grupo aponta para outro contexto, o campo não é atribuído à página atual e nunca retorna valor. Confirme também que o grupo está Ativo (Active).
5. Ajuste o Return Format conforme o tipo de campo: Para campos Image, Link ou Post Object, the_field() pode imprimir vazio quando o Return Format é Array. Defina o Return Format como URL ou ID quando quiser ecoar direto, ou use get_field() e acesse a chave do array no tema. Salve o Field Group após a mudança.

```
$img = get_field('imagem_destaque');
echo esc_url( $img['url'] );
```


## Código

```php
<?php
// Exibir um campo ACF com segurança, dentro ou fora do Loop.
// Passa o post ID explicitamente para evitar retorno false fora do Loop.

$post_id = get_the_ID();
$subtitulo = get_field( 'subtitulo', $post_id );

if ( $subtitulo ) {
    echo '<p class="subtitulo">' . esc_html( $subtitulo ) . '</p>';
}

// Campo de imagem com Return Format = Array: acessar a chave 'url'.
$imagem = get_field( 'imagem_destaque', $post_id );

if ( $imagem && ! empty( $imagem['url'] ) ) {
    echo '<img src="' . esc_url( $imagem['url'] ) . '" alt="' . esc_attr( $imagem['alt'] ) . '">';
}

// Campo global de uma Options Page: usar 'option' como segundo argumento.
$telefone = get_field( 'telefone_contato', 'option' );

if ( $telefone ) {
    echo '<span class="tel">' . esc_html( $telefone ) . '</span>';
}
?>
```

## Perguntas frequentes

### Por que get_field() retorna false mesmo com o campo preenchido?

Quase sempre é contexto ou nome. Se a chamada está fora do Loop, o ACF não sabe de qual post buscar e devolve false; passe o post ID como segundo parâmetro. Se o nome do campo difere do cadastrado no Field Group, o retorno também é false. Confirme com var_dump antes de formatar.

### Qual a diferença entre the_field() e get_field() no ACF?

the_field() imprime o valor direto na página, ideal para texto simples. get_field() retorna o valor como variável, para você tratar, validar ou escapar antes de exibir. Para imagens, links e relacionamentos use get_field() e trabalhe o array ou a URL retornada.

### Devo usar o field name ou o field key na função do tema?

Use o field name, o identificador legível em minúsculas com underscore que aparece na coluna Field Name do grupo. A field key, que começa com field_ seguido de caracteres aleatórios, é de uso interno do ACF e faz the_field() e get_field() retornarem vazio quando usada no tema.

### Por que o campo aparece no admin mas some no frontend?

O valor está salvo, então o problema é a chamada no template. Verifique se o nome do campo está correto, se a função está dentro do Loop ou recebe o post ID, e se as Location Rules do Field Group casam com o template que renderiza essa página. Um único desses fatores fora do lugar zera a saída.

### Como exibir um campo do ACF dentro de um header ou sidebar?

Header, sidebar e footer rodam fora do Loop principal, então a função não tem contexto de post. Passe o ID explicitamente, por exemplo get_field('subtitulo', get_the_ID()), ou use get_queried_object_id() para a página atual. Para campos globais, use uma Options Page e passe 'option' como segundo argumento.

### Por que um campo de imagem do ACF imprime vazio com the_field()?

Campos Image costumam ter Return Format definido como Array, e the_field() não consegue ecoar uma estrutura como string. Mude o Return Format para URL ou ID no Field Group, ou use get_field() e acesse a chave url do array antes de exibir com esc_url.

### Preciso ativar WP_DEBUG para resolver campos vazios do ACF?

Ajuda muito. Com WP_DEBUG em true no wp-config.php, o WordPress mostra avisos como Trying to get property of non-object na linha exata da chamada, apontando se o campo retorna null ou se você está acessando um array como string. Use apenas em staging, nunca em produção.

### As Location Rules afetam se o campo aparece no frontend?

Sim, de forma indireta. As Location Rules determinam a quais telas o Field Group é atribuído. Se a regra aponta para um post type ou template diferente do atual, o campo nem é carregado naquele contexto e a função do tema retorna vazio, mesmo que o nome esteja correto.

**Fonte:** [Advanced Custom Fields — Displaying Custom Field Values in Your Theme](https://www.advancedcustomfields.com/resources/displaying-custom-field-values-in-your-theme/)