ACF dla początkujących: kompletny przewodnik do pól własnych w WordPress krok po kroku

Czas czytania: ~12 min · Poziom: średnio zaawansowany

Natywny edytor WordPressa kończy się na tytule, treści i obrazku wyróżniającym. Chcesz dorzucić podtytuł wpisu, cenę promocyjną produktu albo logo marki przypięte do taksonomii? Klikalne opcje się skończyły. Advanced Custom Fields rozwiązuje ten problem od ponad dekady — ponad 2 mln aktywnych instalacji w repozytorium WordPress.org mówi samo za siebie. Ten przewodnik prowadzi od fundamentu — czym są surowe Custom Fields — przez instalację ACF i pierwszą grupę pól, aż po scenariusze ACF PRO, WooCommerce i rejestrację Custom Post Types bez dodatkowych wtyczek. Aktualizuję też kontekst 2026 roku: WordPress 6.5–7.0, PHP 8.x, fork Secure Custom Fields i konsekwencje, które z niego wynikają dla aktualizacji.

1. ACF zastępuje surowe Custom Fields graficznym interfejsem do pól tekstowych, obrazów, dat, galerii i relacji — bez pisania własnej wtyczki.
2. Dane z ACF lądują w tabeli wp_postmeta. Po dezaktywacji wtyczki zostają w bazie — tracisz tylko wygodne API.
3. Od wersji 6.1 ACF (Free i PRO) rejestruje Custom Post Types oraz taksonomie z panelu — bez Custom Post Type UI.
4. ACF PRO (od 49 USD/rok) dokłada Repeater, Flexible Content, Gallery, Clone, Options Pages i ACF Blocks pod własne bloki Gutenberga.
5. Środowisko 2026: WordPress 6.5–7.0, PHP 7.4 minimum, w praktyce 8.3, ACF 6.1+. Pamiętaj o forku Secure Custom Fields w repozytorium WordPress.org.

Czym są pola własne w WordPress i dlaczego natywny mechanizm nie wystarcza?

Pola własne (Custom Fields) to wbudowany mechanizm WordPressa — zapisuje pary klucz–wartość przypięte do posta, strony albo innego typu treści. Dane lądują w tabeli wp_postmeta jako metadane, a w motywie odczytujesz je funkcją get_post_meta(). Mechanizm istnieje od najwcześniejszych wersji WordPressa. Dziś jest zbyt surowy dla redaktora, który nie chce klepać kluczy meta z palca.

Jak włączyć natywny panel Custom Fields w edytorze Gutenberg i klasycznym?

W edytorze blokowym Gutenberg panel Custom Fields jest domyślnie ukryty. Włączysz go w trzech kliknięciach: trzy kropki w prawym górnym rogu edytora, „Preferences”, zakładka „General”, sekcja „Advanced”, przełącznik „Custom fields”, przycisk „Enable & Reload Page”. Strona się przeładuje i pod treścią pojawi się klasyczny panel klucz–wartość.

W klasycznym edytorze TinyMCE ścieżka jest krótsza. Kliknij „Screen Options” w prawym górnym rogu i zaznacz checkbox „Custom Fields”. Panel pojawi się pod edytorem tekstu od razu, bez przeładowania strony.

Jakie są ograniczenia surowych Custom Fields dla redaktora treści?

Surowe Custom Fields to dwa pola tekstowe: „Name” i „Value”. Wszystko jest tekstem. Bez walidacji, bez typów, bez podpowiedzi. Redaktor musi pamiętać dokładną nazwę meta key (np. subtitle), wpisać ją bez literówki, a wartość traktować jak zwykły string — nawet wtedy, gdy to ma być data albo URL.

Częsty błąd: redaktor wpisuje wartość pod kluczem subTitle z dużą literą, a motyw oczekuje subtitle. Pole istnieje w bazie, ale na froncie nigdy się nie wyświetli — bo nazwa meta jest case-sensitive. Surowy panel nic Ci nie podpowie.

Brakuje pól typu image picker, date picker, select, gallery, relacji do innych postów. Brakuje grupowania w logiczne sekcje — „Dane SEO” oddzielnie od „Dane CTA”. Brakuje reguł warunkowych w stylu „pokaż to pole tylko dla typu produktu”. Wszystko to dokłada ACF.

Czym jest Advanced Custom Fields i jak rozszerza możliwości WordPressa?

Advanced Custom Fields to wtyczka, która dokłada do WordPressa graficzny interfejs do tworzenia grup pól własnych. Każda grupa (Field Group) to logiczny zestaw pól, który przypisujesz do konkretnych ekranów edycji — postów, stron, produktów WooCommerce, taksonomii albo Options Pages.

Advanced Custom Fields is a WordPress plugin which allows you to add extra content fields to your WordPress edit screens.

Oficjalna dokumentacja ACF — Getting Started with ACF

Czym różni się ACF Free od ACF PRO?

ACF Free to wersja z repozytorium WordPress.org. Darmowa, z podstawowymi typami pól: Text, Textarea, Number, Email, Image, File, Select, Checkbox, Radio, True/False, Page Link, Post Object, Taxonomy, User, Date Picker, Color Picker. Od wersji 6.1 obsługuje też rejestrację Custom Post Types i taksonomii — wcześniej była to wyłączna funkcja PRO.

ACF PRO dokłada pola, których nie da się sensownie zastąpić: Repeater (powtarzalne wiersze), Flexible Content (modułowe layouty), Gallery, Clone (kopiowanie definicji pól), Options Pages (globalne ustawienia witryny) oraz ACF Blocks (własne bloki Gutenberga oparte o pola ACF).

Dlaczego ACF stało się standardem rozszerzania edytora WordPress?

Ponad 2 mln aktywnych instalacji w repozytorium WordPress.org to twardy dowód społeczny. Powody są trzy. Po pierwsze, dane zapisują się w natywnej tabeli wp_postmeta — żadnego vendor lock-in, żadnego własnego formatu. Po drugie, API front-endowe (get_field(), the_field()) jest spójne i przewidywalne. Działa identycznie w klasycznym motywie i w blokach Gutenberga. Po trzecie, dokumentacja i przykłady są obszerne, a społeczność rozwiązała większość typowych problemów na forach i Stack Overflow.

Czym jest Secure Custom Fields (SCF) i co oznacza konflikt z 2024 roku dla użytkownika?

Secure Custom Fields to fork ACF utrzymywany od jesieni 2024 w ramach projektu WordPress.org. Powstał na fali konfliktu między Automattic a WP Engine — WordPress.org tymczasowo przejęło repozytorium ACF i podstawiło w aktualizacjach forka pod tą samą nazwą wtyczki w panelu admina. Po wyroku sądu WP Engine odzyskało kontrolę nad oryginałem, ale SCF został jako równoległa wtyczka pod adresem developer.wordpress.org/secure-custom-fields/.

Pułapka: jeśli aktualizowałeś ACF z poziomu panelu WordPressa jesienią 2024, możliwe że masz teraz zainstalowanego forka SCF, a nie oryginalny ACF. Sprawdź w „Wtyczki” — jeśli widnieje „Secure Custom Fields” zamiast „Advanced Custom Fields”, to fork. Dane pól są zgodne, ale aktualizacje funkcji idą innym torem.

Jakie są wymagania środowiska dla ACF w 2026 roku?

Wymagania środowiska dla ACF są pochodną wymagań WordPressa. WordPress 6.5+ wymaga PHP 7.4 jako minimum, a WordPress 7.0 (planowany na maj 2026) podnosi rekomendację do PHP 8.3. ACF w aktualnych wydaniach 6.x wymaga WordPressa 6.2+ i nie podaje sztywnego minimum PHP w changelogach. W praktyce trzymaj się rekomendacji WordPressa.

Jaką wersję PHP rekomendować dla ACF 6.x?

W 2026 roku PHP 8.3 to bezpieczny standard dla produkcyjnej instalacji z ACF. PHP 7.4 wystarczy do startu, ale od listopada 2022 nie dostaje już łatek bezpieczeństwa — używaj go tylko na hostingu, na którym nie masz wyboru. PHP 8.0 i 8.1 działają stabilnie. PHP 8.3 daje najlepszą wydajność i najdłuższą perspektywę wsparcia.

Wersję PHP sprawdzisz w panelu admina: „Narzędzia > Stan witryny > Informacje > Serwer > Wersja PHP”. Zmianę robisz po stronie hostingu — w cPanelu, DirectAdminie albo panelu hostera (Cloudways, SiteGround, Kinsta).

Co zmienia nadchodzący WordPress 7.0 dla użytkowników ACF?

WordPress 7.0 (maj 2026) przynosi współpracę w czasie rzeczywistym w edytorze, zmiany w panelach admina i odświeżone API bloków. Dla ACF to potencjalne przesunięcia w UI Gutenberga — ścieżka włączania panelu „Custom Fields” przez „Preferences” może się zmienić, a ACF Blocks zyskają lepszą integrację z Block API v3. Aktualne instrukcje (w tym ten artykuł) odnoszą się do WordPressa 6.5–6.6. Po stabilnym wydaniu 7.0 sprawdź ścieżki menu na własnej instalacji.

Jak zainstalować i aktywować ACF krok po kroku?

Instalacja ACF to standardowa procedura wtyczki WordPress — z repozytorium dla wersji Free albo z pliku ZIP dla PRO. Cały proces zajmuje 2–3 minuty.

Jak zainstalować darmowy ACF z repozytorium WordPress.org?

Wejdź w „Wtyczki > Dodaj nową”, w wyszukiwarce wpisz „Advanced Custom Fields” lub „ACF”. Pierwszy wynik to wtyczka od WP Engine — kliknij „Zainstaluj”, po chwili „Włącz”. W menu bocznym pojawi się nowa pozycja „ACF” (w starszych wersjach „Custom Fields”) z podstronami „Field Groups”, „Post Types”, „Taxonomies” i „Tools”.

Pro tip: jeśli widzisz w wyszukiwarce wyniki „Advanced Custom Fields” i „Secure Custom Fields” obok siebie — to pozostałość po konflikcie z 2024 roku. Wybierz „Advanced Custom Fields” autorstwa WP Engine, chyba że świadomie chcesz forka.

Jak zainstalować ACF PRO z pliku ZIP i wprowadzić klucz licencyjny?

ACF PRO kupujesz na advancedcustomfields.com. Po zakupie w panelu klienta zobaczysz link do pliku ZIP i klucz licencyjny. Pobierz ZIP, wejdź w „Wtyczki > Dodaj nową > Wyślij wtyczkę”, wskaż plik, kliknij „Zainstaluj teraz”, potem „Włącz”. Jeśli wcześniej miałeś darmowe ACF, instalator zastąpi je wersją PRO bez utraty danych pól.

Klucz licencyjny wprowadzasz w „ACF > Updates” — wklej klucz w pole „License Key” i kliknij „Activate License”. Bez aktywacji wtyczka działa, ale automatyczne aktualizacje nie przyjdą.

Jak bezpiecznie zdefiniować klucz PRO w wp-config.php?

Klucz licencyjny PRO możesz zdefiniować jako stałą w wp-config.php zamiast wpisywać go w panelu admina. Wygodne przy wielu środowiskach (staging, produkcja) z tego samego kodu — klucz trzymasz w pliku konfiguracyjnym, nie w bazie. Dodaj poniższą linię nad komentarzem /* That's all, stop editing! */:

define( 'ACF_PRO_LICENSE', 'twoj-klucz-licencyjny-tutaj' );

Po zapisaniu pliku wejdź w „ACF > Updates”. W polu „License Key” zobaczysz informację, że klucz pochodzi z wp-config.php i nie da się go edytować z poziomu panelu. To intencjonalne zachowanie.

Jak utworzyć pierwszą grupę pól (Field Group) w ACF?

Field Group to podstawowa jednostka konfiguracji w ACF — kontener na pola, przypięty do konkretnych ekranów edycji przez reguły Location. Pojedyncze pole nie istnieje samodzielnie. Zawsze jest częścią grupy.

Wejdź w „ACF > Field Groups > Add New”. Nadaj grupie nazwę widoczną tylko w panelu admina — np. „Post Subtitle”. Kliknij „+ Add Field” i wypełnij minimum dwa pola: „Field Label” (etykieta widoczna dla redaktora, np. „Podtytuł”) i „Field Name” (klucz programistyczny, np. subtitle). Wybierz typ pola — dla podtytułu wystarczy „Text”.

Jak nazwać pole, żeby uniknąć problemów na froncie?

Field Name to klucz, którym identyfikujesz pole w kodzie. Trzy reguły, które oszczędzą Ci godzin debugowania:

• tylko małe litery, cyfry i podkreślenia — bez spacji, myślników, polskich znaków,
• krótko i opisowo: subtitle, hero_image, price_promo. Nie field_1, nie moje_pole_do_podtytulu,
• bez prefiksów ACF (typu acf_) — ACF dokleja swoje wewnętrznie, podwojenie rozjedzie bazę z wywołaniem get_field().

Uwaga: Field Name jest case-sensitive i niezmienialny po zapisie. Jeśli zmienisz subtitle na Subtitle po publikacji, wszystkie wartości zapisane wcześniej w bazie zostaną pod starym kluczem i znikną z edytora. Planuj nazwę od początku.

Jakie reguły Location pozwalają precyzyjnie umieścić pola w edytorze?

Sekcja Location w edytorze Field Group decyduje, na jakich ekranach pole się pojawi. Domyślna reguła brzmi „Post Type is equal to Post” — pole pojawia się przy każdym wpisie blogowym. Dorzucisz AND i OR, żeby precyzyjnie zawęzić zasięg.

• Post Type is equal to Product — pola pokazują się tylko przy produktach WooCommerce.
• Taxonomy is equal to Category — pola pokazują się przy edycji kategorii (np. dla pola „opis SEO kategorii”).
• Page Template is equal to page-landing.php — pola tylko dla stron używających konkretnego szablonu.
• User Role is equal to Editor — pola widoczne tylko dla redaktorów, ukryte dla autorów.

Jakie są najpopularniejsze typy pól i kiedy ich używać?

Jak wyświetlić wartości pól ACF w motywie WordPress?

Field Group masz, wartości w edytorze wypełnione — pora pokazać je na froncie. ACF daje do tego dwie główne funkcje: get_field() i the_field(). Obie wywołujesz z motywu — najlepiej z motywu potomnego, żeby aktualizacja motywu rodzica nie nadpisała Twoich zmian.

Czym różni się get_field() od the_field()?

Różnica jest semantyczna i identyczna jak między get_the_title() a the_title() w core WordPressa. get_field( 'subtitle' ) zwraca wartość pola — przypiszesz ją do zmiennej, sprawdzisz warunkiem, przekształcisz. the_field( 'subtitle' ) od razu wypisuje wartość na ekran, bez możliwości obsługi pustej wartości.

The get_field() and the_field() functions are some of the most important parts of the ACF API.

WPLake — ACF get_field() and the_field() Functions: Detailed Explanation

Jak bezpiecznie wyświetlać pola z walidacją pustej wartości?

Wartość pola bywa pusta — bo redaktor jej nie wypełnił, bo pole jest opcjonalne, bo post tego pola nie ma. Pisz kod, który to przewiduje. Wzorzec jest prosty: pobierz wartość, sprawdź warunek, escapuj przed wypisaniem. Wklej poniższy snippet do single.php motywu potomnego, w miejscu gdzie podtytuł ma się pojawić (np. tuż pod the_title()):

<?php
// Pobierz wartość pola "subtitle" dla aktualnego wpisu.
$subtitle = get_field( 'subtitle' );

// Wypisz tylko jeśli pole zostało wypełnione.
if ( ! empty( $subtitle ) ) {
    echo '<p class="post-subtitle">' . esc_html( $subtitle ) . '</p>';
}
?>

Trzy elementy są krytyczne: get_field() (pobranie), ! empty() (warunek na pustą wartość), esc_html() (escape przed XSS). Pomiń którykolwiek i albo dostaniesz pusty tag <p></p> w HTML, albo lukę bezpieczeństwa, gdy wartość zawiera HTML.

Jak działa relacja ACF z get_post_meta() i czemu to ważne?

ACF nie tworzy własnej tabeli. Wszystko ląduje w natywnej wp_postmeta. Wartość pola subtitle dla posta o ID 42 znajdziesz w SQL pod kluczem meta subtitle. To znaczy, że get_post_meta( 42, 'subtitle', true ) zwróci tę samą wartość co get_field( 'subtitle', 42 ) — z drobną różnicą.

Drobna różnica wygląda tak: get_field() dodatkowo przetwarza wartość zgodnie z typem pola (np. dla pola Image zwraca obiekt z URL, alt, sizes; dla Date Picker formatuje datę). get_post_meta() zwraca surowy string. Dla pól prostych (Text, Textarea) wynik jest identyczny. Dla pól złożonych używaj get_field().

Pro tip: jeśli dezaktywujesz ACF, dane w wp_postmeta zostają. Odczytasz je natywnym get_post_meta() i przepiszesz motyw bez ACF. To gwarancja, że nie wpadasz w lock-in — wtyczka jest opcjonalna, nie obowiązkowa dla Twoich danych.

Jak ACF integruje się z WooCommerce i Custom Post Types?

WooCommerce i CPT to dwa najczęstsze scenariusze użycia ACF poza zwykłymi postami. Oba opierają się na regule Location „Post Type is equal to …” i działają z minimalną konfiguracją.

Jak dodać dodatkowe pole do produktu WooCommerce krok po kroku?

Załóżmy, że chcesz dodać do produktów pole „Brand” (marka). Procedura:

1. Wejdź w „ACF > Field Groups > Add New”, nadaj grupie nazwę „Product Brand”.
2. Kliknij „+ Add Field”. Label: „Marka”. Name: brand. Typ: „Text”.
3. W sekcji Location ustaw regułę „Post Type is equal to Product”.
4. Zapisz grupę. Wejdź w „Produkty > Wszystkie produkty” i otwórz dowolny produkt — pod opisem zobaczysz nową sekcję „Product Brand” z polem „Marka”.
5. Wypełnij pole i zapisz produkt.

Wyświetlenie pola na froncie produktu wymaga edycji szablonu — najlepiej przez hook WooCommerce, żeby nie nadpisywać single-product.php. Dodaj poniższy snippet do functions.php motywu potomnego:

add_action( 'woocommerce_single_product_summary', 'akst_show_product_brand', 25 );

function akst_show_product_brand() {
    $brand = get_field( 'brand' );
    if ( ! empty( $brand ) ) {
        echo '<p class="product-brand"><strong>Marka:</strong> ' . esc_html( $brand ) . '</p>';
    }
}

Priorytet 25 wstawia pole między ceną (priorytet 10) a przyciskiem dodaj do koszyka (priorytet 30). Odśwież stronę produktu — marka pojawi się w opisanym miejscu.

Jak zarejestrować Custom Post Type w ACF 6.1+ bez osobnej wtyczki?

Do wersji 6.1 rejestracja CPT wymagała kodu w functions.php albo dedykowanej wtyczki Custom Post Type UI. Od 6.1 zrobisz to bezpośrednio w panelu ACF — bez kodu i bez dodatkowej wtyczki.

Registering custom taxonomies and post types can be done in both the free and PRO versions of ACF.

WP Engine — Custom Post Types and Taxonomies in ACF 6.1

Procedura dla CPT „Project” (portfolio):

1. „ACF > Post Types > Add New”.
2. Plural Label: „Projects”. Singular Label: „Project”. Post Type Key: project.
3. W zakładce „Advanced Configuration” zaznacz „Hierarchical: no”, „Has Archive: yes”, „Show in REST: yes” (dla Gutenberga).
4. Zapisz. W menu bocznym pojawi się nowa pozycja „Projects”.

Jak połączyć CPT z własną taksonomią i polami opisującymi taksonomię?

Realny scenariusz: katalog produktów B2B z taksonomią „Brand”. Każda marka ma logo, rok założenia i lokalizację HQ. Procedura:

1. „ACF > Taxonomies > Add New”. Plural: „Brands”, Singular: „Brand”, Key: brand. Przypisz do Post Type „Product”.
2. „ACF > Field Groups > Add New”. Nazwa: „Brand Meta”.
3. Dodaj 3 pola: brand_logo (typ Image), founded_year (typ Number), headquarters (typ Text).
4. W Location: „Taxonomy is equal to Brand”.
5. Zapisz. Wejdź w „Products > Brands > Add New” — przy formularzu dodawania marki zobaczysz 3 nowe pola.

Na froncie wartości taksonomii odczytujesz przez get_field( 'brand_logo', 'brand_' . $term_id ). Drugi argument to nie ID posta, tylko prefiks brand_ (nazwa taksonomii) + ID terma. To różnica w stosunku do pól na poście.

Jakie zaawansowane funkcje oferuje ACF PRO?

ACF PRO dodaje funkcje, których nie da się sensownie zastąpić w wersji Free. Najważniejsze trzy to Repeater, Flexible Content i ACF Blocks — każde rozwiązuje inną klasę problemów.

Do czego służy pole Repeater i kiedy ma sens?

Repeater to powtarzalne wiersze pól. Definiujesz raz strukturę (np. „pytanie + odpowiedź” dla sekcji FAQ), a redaktor dodaje tyle wierszy, ile chce. Bez Repeatera musiałbyś klepać 10 osobnych pól faq_1_question, faq_1_answer, faq_2_question… i godzić się na sztywny limit z góry.

Snippet wyświetlający Repeater „faq” w szablonie:

<?php if ( have_rows( 'faq' ) ) : ?>
    <dl class="faq-list">
    <?php while ( have_rows( 'faq' ) ) : the_row(); ?>
        <dt><?php echo esc_html( get_sub_field( 'question' ) ); ?></dt>
        <dd><?php echo esc_html( get_sub_field( 'answer' ) ); ?></dd>
    <?php endwhile; ?>
    </dl>
<?php endif; ?>

Pętla have_rows() + the_row() + get_sub_field() to wzorzec, który zobaczysz przy każdym Repeaterze i Flexible Content. Zapamiętaj raz, używaj wszędzie.

Jak Flexible Content zastępuje page buildery w prostych projektach?

Flexible Content to Repeater na sterydach. Zamiast jednej powtarzalnej struktury definiujesz kilka „layoutów” do wyboru. Redaktor składa stronę z bloków: „Hero Section”, „Text + Image”, „Testimonials”, „CTA Banner”. Każdy layout ma własne pod-pola.

W prostszych projektach to pełnoprawna alternatywa dla page builderów typu Elementor czy Divi. Plusy: pełna kontrola nad HTML (sam piszesz template part dla każdego layoutu), zerowe zależności od ciężkich frameworków front-endowych, dane w natywnym wp_postmeta. Minusy: redaktor nie widzi „podglądu na żywo” — zapisz i sprawdź na froncie.

Pętla w szablonie wygląda tak:

<?php if ( have_rows( 'page_builder' ) ) : ?>
    <?php while ( have_rows( 'page_builder' ) ) : the_row();
        $layout = get_row_layout();
        get_template_part( 'template-parts/blocks/' . $layout );
    endwhile; ?>
<?php endif; ?>

Każdy layout to osobny plik w template-parts/blocks/ — np. hero-section.php, text-image.php. Nowy layout dodajesz w dwóch ruchach: stworzenie pliku + rejestracja layoutu w polu Flexible Content w panelu ACF.

Czym są ACF Blocks i jak budują własne bloki Gutenberga?

ACF Blocks to mechanizm rejestrowania bloków Gutenberga opartych o pola ACF, a nie o React i Block API. Redaktor wstawia blok w edytorze, wypełnia pola po prawej, widzi podgląd na żywo — wszystko bez znajomości JavaScriptu.

Workflow wygląda tak: utwórz Field Group z regułą Location „Block is equal to [nazwa bloku]”, zarejestruj blok przez acf_register_block_type() w functions.php, napisz template (PHP), który renderuje wartości pól. Od ACF 6.x mechanizm jest kompatybilny z Block API v3 core WordPressa.

Rejestracja prostego bloku „testimonial”:

add_action( 'acf/init', 'akst_register_blocks' );

function akst_register_blocks() {
    if ( ! function_exists( 'acf_register_block_type' ) ) {
        return;
    }

    acf_register_block_type( array(
        'name'            => 'testimonial',
        'title'           => 'Testimonial',
        'description'     => 'Pojedynczy testimonial klienta.',
        'render_template' => 'template-parts/blocks/testimonial.php',
        'category'        => 'formatting',
        'icon'            => 'format-quote',
        'keywords'        => array( 'testimonial', 'opinia', 'cytat' ),
        'mode'            => 'preview',
    ) );
}

Dodaj kod, stwórz plik template-parts/blocks/testimonial.php — blok pojawi się w wyszukiwarce bloków Gutenberga w kategorii „Formatting”.

Jakie są najczęstsze błędy początkujących i jak je rozwiązać?

Większość problemów z ACF sprowadza się do trzech kategorii: konfiguracja (Location, nazwa pola), kontekst (zły $post_id) i środowisko (cache, konflikt wtyczek). Poniższa tabela diagnostyczna pomoże Ci szybko zlokalizować przyczynę.

Dlaczego moje pole jest puste w the_field() mimo że wpisałem wartość?

Trzy najczęstsze przyczyny:

• Literówka w Field Name. Wpisałeś w kodzie the_field( 'subTitle' ), a w panelu nazwa to subtitle. Field Name jest case-sensitive. Skopiuj dokładną nazwę z panelu.
• Edytujesz inny post niż myślisz. Wywołujesz the_field() w pętli archive zamiast w single.php? ACF czyta wtedy dane głównego query, a nie aktualnej iteracji. Przekaż jawnie get_the_ID() jako drugi argument.
• Cache motywu lub strony. Wtyczki cache WP Rocket i LiteSpeed Cache potrafią zacache’ować pustą wersję strony. Wyczyść cache po wprowadzeniu wartości pola.

Dlaczego pola nie pojawiają się w edytorze posta lub produktu?

Najczęściej winna jest reguła Location. Sprawdź w „ACF > Field Groups > [nazwa grupy] > Location” — jeśli reguła brzmi „Post Type is equal to Post”, a edytujesz produkt WooCommerce, pole się nie pojawi. Zmień na „Post Type is equal to Product” albo dodaj drugą regułę z OR.

Druga możliwość: Field Group ma status „Inactive” — w liście grup pól po prawej stronie jest przełącznik. Aktywuj grupę i odśwież edytor.

Jak rozwiązywać konflikty ACF z page builderami i cache?

Page buildery (Elementor, Divi, Bricks) mają własne mechanizmy dynamicznego pobierania pól ACF. Konflikt pojawia się, gdy builder cache’uje wartość pola i nie odświeża jej po edycji. Rozwiązanie: w ustawieniach buildera włącz „regeneruj CSS po zapisie” i wyczyść cache buildera po zmianie wartości pola.

Konflikt z cache czyścisz sekwencyjnie:

1) wyczyść cache wtyczki cache,

2) wyczyść cache hostingu (Cloudways i Kinsta mają osobny),

3) wyczyść cache CDN (Cloudflare),

4) hard refresh przeglądarki (Ctrl+Shift+R).

Pole nadal jest puste? Problem nie leży w cache.

Jakie jest podsumowanie kluczowych informacji?

Najważniejsze punkty z całego artykułu — zwięźle:

• ACF zastępuje surowe Custom Fields graficznym interfejsem — bez kodowania własnej wtyczki.
• Dane lądują w wp_postmeta i zostają po dezaktywacji wtyczki — żadnego vendor lock-in.
• Instalacja: „Wtyczki > Dodaj nową > Advanced Custom Fields” (Free) lub upload ZIP (PRO).
• Field Group + Field Name + Location to trzy filary każdej konfiguracji ACF.
• W motywie: get_field() (do logiki) lub the_field() (do prostego wypisania), zawsze z esc_html().
• PRO daje Repeater, Flexible Content, Gallery, Options Pages i ACF Blocks — kupuj, gdy potrzebujesz modułowych layoutów.
• Najczęstsze błędy: literówka w Field Name, zła reguła Location, cache. Diagnostyka w kolejności: nazwa → Location → cache.

Pełna dokumentacja ACF jest pod advancedcustomfields.com/resources. Dla forka Secure Custom Fields osobna ścieżka: developer.wordpress.org/secure-custom-fields.

Jakie są najczęściej zadawane pytania (FAQ)?