---
title: "WPGraphQL – headless WordPress z GraphQL"
url: https://dh-pomoc.redzioch.pl/baza-wiedzy/wpgraphql-headless-wordpress-z-graphql/
modified: 2025-09-29
group: "Wiedza dla twórców"
category: "Wtyczki Wordpress"
type: "Wyjaśnienie"
description: "Spis treści Czym jest WPGraphQL i kiedy ma sensInstalacja i szybki startSchema – jak WordPress mapuje się na GraphQLZapytania, mutacje i filtrowanieIntegracje: ACF, WooCommerce i multisiteAutoryzacja i bezpieczeństwoWydajność i cacheREST API czy GraphQL – co wybraćNajczęstsze problemy i diagnozaDobre praktyki…"
language: pl
---

# WPGraphQL – headless WordPress z GraphQL

## Czym jest WPGraphQL i kiedy ma sens

WPGraphQL dodaje do WordPressa warstwę GraphQL, czyli typowany interfejs do pobierania i modyfikowania danych jednym, precyzyjnym zapytaniem. Dzięki temu frontendy w React, Next.js, Gatsby czy mobilne aplikacje mogą pracować z WordPressem jak z nowoczesnym headless CMS. WPGraphQL upraszcza pobieranie dokładnie tych pól, które są potrzebne, co ogranicza transfer i liczbę żądań w porównaniu z klasycznym REST API.

Z wtyczki skorzystasz szczególnie wtedy, gdy masz rozbudowane widoki oparte o wiele źródeł danych, potrzebujesz filtrować i paginować treści w jednym żądaniu oraz planujesz skalowanie na wiele kanałów – web, PWA, aplikacje mobilne, kiosk czy digital signage.

## Instalacja i szybki start

Instalację przeprowadzisz jak zwykle w WordPressie – dodaj wtyczkę i aktywuj. Po uruchomieniu pojawi się interfejs testowy GraphiQL dostępny z panelu, gdzie od ręki sprawdzisz zapytania. Domyślny endpoint GraphQL jest publiczny do odczytu treści, które i tak są publiczne w WordPressie. Operacje wymagające uprawnień, w tym mutacje, wymagają autoryzacji użytkownika.

Na start wykonaj proste zapytanie o listę wpisów z tytułem, slugiem i wyróżnionym obrazem. Zwróć uwagę, że od razu wybierasz tylko potrzebne pola, a paginacja opiera się na kursorach, co jest stabilniejsze niż paginacja offsetowa przy dużych witrynach.

## Schema – jak WordPress mapuje się na GraphQL

Schema w WPGraphQL odzwierciedla kluczowe byty WordPressa: wpisy, strony, typy niestandardowe, taksonomie, użytkowników, media i ustawienia. Dla niestandardowych typów treści i taksonomii pola pojawiają się automatycznie, jeżeli zostały zarejestrowane z odpowiednimi flagami. Możesz też dodawać własne typy i pola poprzez rejestrację w PHP, expose’ując metadane lub wyniki własnych funkcji.

Pola niestandardowe stanowią ważną część schemy. Dla popularnych rozwiązań jak ACF istnieją rozszerzenia, które mapują pola na typy GraphQL. Dzięki temu pobierzesz w jednym zapytaniu zarówno dane wpisu, jak i strukturę złożonych pól powtarzalnych, galerii czy relacji między treściami.

## Zapytania, mutacje i filtrowanie

WPGraphQL dostarcza gotowe operacje do pobierania list i pojedynczych obiektów po ID, slugach i kursorach. Filtrowanie działa po taksonomiach, meta i atrybutach publikacji. Relacje można rozwijać zagnieżdżając kolejne poziomy, co eliminuje problem N+1 znany z tradycyjnych API, o ile schema i resolvery są rozsądnie zaprojektowane.

Mutacje obejmują podstawowe operacje edycji, tworzenia i usuwania treści, mediów czy taksonomii. Nie wszystkie wtyczki dodają mutacje automatycznie, dlatego w projektach headless warto z góry ustalić, które procesy edycyjne zostają w panelu WordPress, a które mają być dostępne przez GraphQL, na przykład publikacja komentarzy czy obsługa koszyka w sklepie.

## Integracje: ACF, WooCommerce i multisite

W praktyce najczęściej łączysz WPGraphQL z ACF, aby wygodnie budować modele treści. Rozszerzenie do ACF odwzorowuje pola i grupy w schemie, łącznie z repeaterami i polami relacyjnymi. Na e-commerce przydaje się integracja ze sklepem – odpowiednia wtyczka udostępnia typy produktów, wariantów, koszyków i zamówień po GraphQL. W środowiskach multisite WPGraphQL pozwala pobierać dane z kontekstem konkretnej strony sieci, co ułatwia budowę portali i serwisów wielojęzycznych.

Warto pamiętać, że niektóre integracje udostępniają jedynie odczyt. Jeśli potrzebujesz pełnych mutacji, sprawdź dokumentację rozszerzenia lub przygotuj własne resolvery.

## Autoryzacja i bezpieczeństwo

Autoryzacja opiera się na sesji WordPressa lub tokenach – najczęściej wykorzystywane są ciasteczka logowania panelu lub integracja z JWT. W projekcie headless rozdziel interfejs publiczny i panel administracyjny, ograniczając mutacje tylko do zaufanych klientów. Minimalny zestaw praktyk to wyłączenie mutacji dla niezalogowanych użytkowników, sprawdzanie ról i możliwości użytkownika przy każdym resolverze oraz ograniczanie wrażliwych pól w schemie.

GraphQL umożliwia introspekcję schemy, co bywa pomocne w dewelopmencie. W środowisku produkcyjnym możesz ograniczyć introspekcję dla niezalogowanych, wprowadzić limity głębokości zapytań i budżet kosztu pola, a także monitorować czas wykonania. Dobrym nawykiem jest logowanie najcięższych zapytań wraz z identyfikatorem klienta.

## Wydajność i cache

- cache obiektowy WordPress – poprawia czas odpowiedzi resolverów,
- CDN lub reverse proxy dla zapytań tylko do odczytu – można kechować odpowiedzi na podstawie treści zapytania,
- mechanizmy batchowania i kolejkowania w resolverach – ograniczają liczbę zapytań SQL,
- persisted queries – zapisane po stronie serwera operacje z hashami, które upraszczają cache i podnoszą bezpieczeństwo,
- paginacja kursorem – stabilna przy dużych zbiorach i modyfikacjach treści.

Zadbaj o indeksy w bazie, zwłaszcza w tabelach postmeta i term\_relationships, oraz o sensowną strukturę pól. Nieużywane lub bardzo ciężkie pola trzymaj poza domyślnymi fragmentami, aby uniknąć przypadkowego dociągania dużych kolekcji.

## REST API czy GraphQL – co wybrać

REST jest prosty, klarowny i dobrze wspierany przez narzędzia, ale często wymaga wielu żądań do złożonych widoków. GraphQL pozwala pobrać wszystko jednym wywołaniem i precyzyjnie kontrolować zakres danych. Jeśli tworzysz klasyczny motyw PHP lub korzystasz z małych integracji, REST wystarczy. Gdy budujesz złożony frontend SPA, hybrydowy SSR lub aplikacje mobilne, WPGraphQL daje większą elastyczność i niższy narzut komunikacyjny.

W realnych projektach oba podejścia często współistnieją. Drobne integracje i webhooki obsługuje REST, a widoki klienckie i listingi działają na GraphQL.

## Najczęstsze problemy i diagnoza

Jeśli zapytania są wolne, sprawdź czy nie prosisz o zbyt głębokie relacje lub duże kolekcje bez limitów. Objawem jest długi TTFB przy pierwszym żądaniu. Włącz logi zapytań SQL i profiluj resolvery. Gdy brakuje pól w schemie, upewnij się, że typy niestandardowe i pola mają odpowiednie flagi ekspozycji, a rozszerzenia są aktywne. Błędy uprawnień zwykle wynikają z braku ról lub niestandardowych polityk zdolności – przetestuj zapytanie na koncie o minimalnych uprawnieniach.

Konflikty z innymi wtyczkami zdarzają się, gdy modyfikują one globalne zapytanie WordPressa lub filtry autoryzacji. Izoluj problem, wyłączając dodatki i testując schema w GraphiQL. W razie potrzeby dodaj własne resolvery, które omijają kosztowne hooki.

## Dobre praktyki wdrożenia headless

Na etapie projektowania modeli treści planuj strukturę pól tak, aby odzwierciedlała komponenty frontendu. Stosuj fragmenty GraphQL do ponownego użycia selektorów i trzymaj wspólne zestawy pól w jednym miejscu. Wprowadź persisted queries dla kluczowych widoków i trzymaj ich wersje w repozytorium wraz z kodem frontendu. Mierz rzeczywisty czas odpowiedzi na brzegu i w serwerze aplikacyjnym, a nie tylko w narzędziach deweloperskich.

W pipeline CI buduj testy zapytań – sprawdzaj, czy schema nie uległa niezamierzonej zmianie i czy krytyczne operacje zwracają wymagane pola. Dla treści dynamicznych łącz GraphQL z webhooks, aby odświeżać cache po publikacji. Taki setup zapewni przewidywalną wydajność i stabilność nawet przy dużych zasięgach.
