--- title: "Como corrigir o Image Field no ACF PRO" url: https://full.services/wp-fixer/corrigir-image-field-acf-pro/ date: 2026-06-17 author: "Clayton Margiotti" --- # Como corrigir o Image Field no ACF PRO ## O que é Image Field do ACF que não retorna URL? O Image Field do ACF PRO tem três opções de Return Format na configuração do campo: Image Array, Image URL e Image ID. Cada opção devolve um tipo de dado diferente quando você lê o campo com get_field. O Image Array devolve um array com chaves como url, alt, width e height. O Image URL devolve só a string da URL. O Image ID devolve o número do anexo na biblioteca de mídia. O erro de não retornar URL acontece quando o template foi escrito esperando a string da URL, mas o campo está configurado como Array ou ID. Como o ACF não dispara erro fatal, o resultado é silencioso: a tag de imagem renderiza com o src vazio, com a palavra Array, ou com um número cru no lugar do caminho do arquivo. ## Como identificar - A imagem não aparece no frontend e o atributo src da tag fica vazio ao inspecionar o HTML. - No lugar da imagem o navegador imprime a palavra Array como texto, sinal de que o campo devolveu um array e foi tratado como string. - var_dump do campo imprime um array com as chaves url, alt e sizes em vez de uma string única com o caminho. - O src da imagem mostra um número inteiro como 482 em vez de um caminho de arquivo, sinal de Return Format igual a Image ID. - A mensagem Array to string conversion aparece no log de debug quando o template concatena o campo direto na URL. ## Como prevenir - Defina o Return Format do Image Field uma vez por projeto e padronize: Image URL para uso simples no src, Image Array quando precisar de alt e tamanhos. - Escape toda saída de imagem com esc_url no src e esc_attr no alt antes de imprimir, evitando HTML quebrado por valores inesperados. - Valide o retorno com uma checagem de vazio antes de montar a tag, porque a imagem pode ter sido apagada da biblioteca de mídia. - Dentro de Repeater e Flexible Content, sempre leia a imagem com get_sub_field, reservando get_field para campos de nível superior. --- ## Metadados Estruturados (Schema.org) ```json-ld { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://full.services/#org", "name": "FULL Services", "url": "https://full.services/", "sameAs": [ "https://www.instagram.com/fullservicesbr", "https://www.facebook.com/fullservices.br", "https://www.linkedin.com/company/fullservicesbr/" ], "knowsAbout": [ "WordPress", "WordPress Hosting", "Web Development", "Performance Optimization", "WordPress Security", "SEO para WordPress" ], "award": [ "Gold Medal - The WP Weekly Awards 2023", "Gold Medal - The WP Weekly Awards 2024" ], "logo": { "@type": "ImageObject", "url": "https://full.services/wp-content/uploads/full-services-logo.png", "width": 200, "height": 60 }, "hasCredential": { "@type": "EducationalOccupationalCredential", "credentialCategory": "certification", "name": "CVE Numbering Authority (CNA)", "description": "Autoridade de numeração de vulnerabilidades (CVE) para o ecossistema WordPress, autorizada a atribuir IDs CVE. Válida desde 2022-05-03, com abrangência global.", "url": "https://www.cve.org/PartnerInformation/ListofPartners/partner/FULL", "recognizedBy": { "@type": "Organization", "name": "CISA — Cybersecurity and Infrastructure Security Agency", "url": "https://www.cisa.gov/", "sameAs": "https://www.cisa.gov/" } } }, { "@type": "TechArticle", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#article", "headline": "Como corrigir o Image Field no ACF PRO", "url": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/", "inLanguage": "pt-BR", "datePublished": "2026-06-17T12:39:07-03:00", "dateModified": "2026-06-17T12:39:07-03:00", "author": { "@id": "https://full.services/#org" }, "publisher": { "@id": "https://full.services/#org" }, "isAccessibleForFree": false, "about": [ { "@type": "Thing", "@id": "https://www.wikidata.org/wiki/Q13166", "name": "WordPress", "sameAs": "https://www.wikidata.org/wiki/Q13166", "url": "https://wordpress.org/" }, { "@type": "Thing", "name": "Page Builders" } ], "mentions": { "@type": "Thing", "@id": "https://www.wikidata.org/wiki/Q13166", "name": "WordPress", "sameAs": "https://www.wikidata.org/wiki/Q13166", "url": "https://wordpress.org/" }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/" }, "wordCount": 842, "description": "O Image Field do ACF PRO não retorna a URL quando o Return Format do campo está como Image Array ou Image ID, mas o template usa o valor como se fosse a string da URL. O ACF devolve um array ou um número de anexo, então o atributo src da imagem sai quebrado ou vazio.", "articleSection": "Page Builders", "keywords": "acf get_field imagem retorna id, acf image field retorna array, acf image field src vazio, acf image return format url, the_field imagem acf imprime array", "proficiencyLevel": "Intermediate", "citation": { "@type": "CreativeWork", "url": "https://www.advancedcustomfields.com/resources/image/", "name": "Advanced Custom Fields — Image Field" }, "mainEntity": { "@type": "SoftwareSourceCode", "name": "Como corrigir o Image Field no ACF PRO", "programmingLanguage": "PHP", "codeRepository": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/", "isAccessibleForFree": false } }, { "@type": "FAQPage", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq", "isPartOf": { "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#article" }, "isAccessibleForFree": true, "mainEntity": [ { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q1", "name": "Por que o Image Field do ACF imprime a palavra Array em vez da imagem", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "O Return Format do campo está como Image Array e o template tenta imprimir o array inteiro como se fosse texto. Leia a chave url do array com get_field e escape com esc_url, ou troque o Return Format do campo para Image URL na configuração.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q2", "name": "Qual a diferença entre Image Array, Image URL e Image ID no ACF", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Image Array devolve um array com url, alt, width e sizes. Image URL devolve só a string da URL, pronta para o src. Image ID devolve o número do anexo, que você converte em caminho com wp_get_attachment_image_url. Escolha conforme o que o template precisa.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q3", "name": "Como pego só a URL quando o campo está como Image Array", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Guarde o retorno de get_field em uma variável e acesse a chave url do array. Imprima com esc_url para escapar a saída. O mesmo array traz alt e sizes caso você queira montar a tag de imagem completa com texto alternativo.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q4", "name": "O campo devolve um número em vez do caminho da imagem, o que é", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "O Return Format está como Image ID, então o ACF entrega o número do anexo. Passe esse ID para wp_get_attachment_image_url com o tamanho desejado para obter a URL, ou mude o Return Format do campo para Image URL se quiser o caminho direto.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q5", "name": "Posso usar the_field para exibir o Image Field", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Só funciona bem quando o Return Format é Image URL, porque the_field imprime a string direta. Com Image Array ou Image ID o the_field imprime a palavra Array ou um número. Para esses formatos use get_field, monte a tag e escape a saída.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q6", "name": "A imagem some dentro de um Repeater, como corrijo", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Dentro de Repeater ou Flexible Content a imagem só sai por get_sub_field, chamado dentro do laço have_rows. Usar get_field no campo pai não devolve a imagem da linha atual. Acesse a chave url do retorno e escape com esc_url antes de imprimir.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/wp-fixer/corrigir-image-field-acf-pro/#faq-q7", "name": "Por que a imagem aparecia e parou de aparecer de repente", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "O anexo selecionado pode ter sido removido da biblioteca de mídia. Com Image ID a função wp_get_attachment_image_url devolve false para um ID inexistente. Confirme se o arquivo ainda existe na mídia e selecione a imagem de novo no campo.", "author": { "@id": "https://full.services/#org" } } } ] } ] } ```