{"id":15390,"date":"2025-09-29T13:16:17","date_gmt":"2025-09-29T11:16:17","guid":{"rendered":"https:\/\/dhosting.pl\/pomoc\/?post_type=manual_kb&#038;p=15390"},"modified":"2025-09-29T13:16:17","modified_gmt":"2025-09-29T11:16:17","slug":"wpgraphql-headless-wordpress-z-graphql","status":"publish","type":"manual_kb","link":"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/","title":{"rendered":"WPGraphQL &#8211; headless WordPress z GraphQL"},"content":{"rendered":"<p><!-- Meta description: Przewodnik po WPGraphQL w WordPress: instalacja, schema, autoryzacja, wydajno\u015b\u0107, integracje z ACF i WooCommerce oraz dobre praktyki headless. --><\/p>\n<div id=\"ez-toc-container\" class=\"ez-toc-v2_0_83 ez-toc-wrap-left counter-flat ez-toc-counter ez-toc-custom ez-toc-container-direction\">\n<div class=\"ez-toc-title-container\">\n<p class=\"ez-toc-title\" style=\"cursor:inherit\">Spis tre\u015bci<\/p>\n<span class=\"ez-toc-title-toggle\"><\/span><\/div>\n<nav><ul class='ez-toc-list ez-toc-list-level-1 ' ><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-1\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Czym_jest_WPGraphQL_i_kiedy_ma_sens\" >Czym jest WPGraphQL i kiedy ma sens<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-2\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Instalacja_i_szybki_start\" >Instalacja i szybki start<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-3\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Schema_%E2%80%93_jak_WordPress_mapuje_sie_na_GraphQL\" >Schema &#8211; jak WordPress mapuje si\u0119 na GraphQL<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-4\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Zapytania_mutacje_i_filtrowanie\" >Zapytania, mutacje i filtrowanie<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-5\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Integracje_ACF_WooCommerce_i_multisite\" >Integracje: ACF, WooCommerce i multisite<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-6\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Autoryzacja_i_bezpieczenstwo\" >Autoryzacja i bezpiecze\u0144stwo<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-7\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Wydajnosc_i_cache\" >Wydajno\u015b\u0107 i cache<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-8\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#REST_API_czy_GraphQL_%E2%80%93_co_wybrac\" >REST API czy GraphQL &#8211; co wybra\u0107<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-9\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Najczestsze_problemy_i_diagnoza\" >Najcz\u0119stsze problemy i diagnoza<\/a><\/li><li class='ez-toc-page-1'><a class=\"ez-toc-link ez-toc-heading-10\" href=\"https:\/\/dhosting.pl\/pomoc\/baza-wiedzy\/wpgraphql-headless-wordpress-z-graphql\/#Dobre_praktyki_wdrozenia_headless\" >Dobre praktyki wdro\u017cenia headless<\/a><\/li><\/ul><\/nav><\/div>\n<h2><span class=\"ez-toc-section\" id=\"Czym_jest_WPGraphQL_i_kiedy_ma_sens\"><\/span>Czym jest WPGraphQL i kiedy ma sens<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>WPGraphQL dodaje do WordPressa warstw\u0119 GraphQL, czyli typowany interfejs do pobierania i modyfikowania danych jednym, precyzyjnym zapytaniem. Dzi\u0119ki temu frontendy w React, Next.js, Gatsby czy mobilne aplikacje mog\u0105 pracowa\u0107 z WordPressem jak z nowoczesnym headless CMS. WPGraphQL upraszcza pobieranie dok\u0142adnie tych p\u00f3l, kt\u00f3re s\u0105 potrzebne, co ogranicza transfer i liczb\u0119 \u017c\u0105da\u0144 w por\u00f3wnaniu z klasycznym REST API.<\/p>\n<p>Z wtyczki skorzystasz szczeg\u00f3lnie wtedy, gdy masz rozbudowane widoki oparte o wiele \u017ar\u00f3de\u0142 danych, potrzebujesz filtrowa\u0107 i paginowa\u0107 tre\u015bci w jednym \u017c\u0105daniu oraz planujesz skalowanie na wiele kana\u0142\u00f3w &#8211; web, PWA, aplikacje mobilne, kiosk czy digital signage.<\/p>\n<div id=\"dhost-1674300993\" class=\"dhost-inpost dhost-entity-placement\"><a href=\"https:\/\/dhosting.pl\/opieka-stron.html?utm_source=pomoc&utm_medium=artykul&utm_campaign=pomoc\" target=\"_blank\">\r\n\t<img decoding=\"async\" src=\"https:\/\/dhosting.pl\/pomoc\/wp-content\/uploads\/2025\/01\/baner-opieka.png\" alt=\"opieka stron www\">\r\n<\/a>\r\n<br \/>\r\n<br \/><\/div><h2><span class=\"ez-toc-section\" id=\"Instalacja_i_szybki_start\"><\/span>Instalacja i szybki start<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>Instalacj\u0119 przeprowadzisz jak zwykle w WordPressie &#8211; dodaj wtyczk\u0119 i aktywuj. Po uruchomieniu pojawi si\u0119 interfejs testowy GraphiQL dost\u0119pny z panelu, gdzie od r\u0119ki sprawdzisz zapytania. Domy\u015blny endpoint GraphQL jest publiczny do odczytu tre\u015bci, kt\u00f3re i tak s\u0105 publiczne w WordPressie. Operacje wymagaj\u0105ce uprawnie\u0144, w tym mutacje, wymagaj\u0105 autoryzacji u\u017cytkownika.<\/p>\n<p>Na start wykonaj proste zapytanie o list\u0119 wpis\u00f3w z tytu\u0142em, slugiem i wyr\u00f3\u017cnionym obrazem. Zwr\u00f3\u0107 uwag\u0119, \u017ce od razu wybierasz tylko potrzebne pola, a paginacja opiera si\u0119 na kursorach, co jest stabilniejsze ni\u017c paginacja offsetowa przy du\u017cych witrynach.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Schema_%E2%80%93_jak_WordPress_mapuje_sie_na_GraphQL\"><\/span>Schema &#8211; jak WordPress mapuje si\u0119 na GraphQL<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>Schema w WPGraphQL odzwierciedla kluczowe byty WordPressa: wpisy, strony, typy niestandardowe, taksonomie, u\u017cytkownik\u00f3w, media i ustawienia. Dla niestandardowych typ\u00f3w tre\u015bci i taksonomii pola pojawiaj\u0105 si\u0119 automatycznie, je\u017celi zosta\u0142y zarejestrowane z odpowiednimi flagami. Mo\u017cesz te\u017c dodawa\u0107 w\u0142asne typy i pola poprzez rejestracj\u0119 w PHP, expose&#8217;uj\u0105c metadane lub wyniki w\u0142asnych funkcji.<\/p>\n<p>Pola niestandardowe stanowi\u0105 wa\u017cn\u0105 cz\u0119\u015b\u0107 schemy. Dla popularnych rozwi\u0105za\u0144 jak ACF istniej\u0105 rozszerzenia, kt\u00f3re mapuj\u0105 pola na typy GraphQL. Dzi\u0119ki temu pobierzesz w jednym zapytaniu zar\u00f3wno dane wpisu, jak i struktur\u0119 z\u0142o\u017conych p\u00f3l powtarzalnych, galerii czy relacji mi\u0119dzy tre\u015bciami.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Zapytania_mutacje_i_filtrowanie\"><\/span>Zapytania, mutacje i filtrowanie<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>WPGraphQL dostarcza gotowe operacje do pobierania list i pojedynczych obiekt\u00f3w po ID, slugach i kursorach. Filtrowanie dzia\u0142a po taksonomiach, meta i atrybutach publikacji. Relacje mo\u017cna rozwija\u0107 zagnie\u017cd\u017caj\u0105c kolejne poziomy, co eliminuje problem N+1 znany z tradycyjnych API, o ile schema i resolvery s\u0105 rozs\u0105dnie zaprojektowane.<\/p>\n<p>Mutacje obejmuj\u0105 podstawowe operacje edycji, tworzenia i usuwania tre\u015bci, medi\u00f3w czy taksonomii. Nie wszystkie wtyczki dodaj\u0105 mutacje automatycznie, dlatego w projektach headless warto z g\u00f3ry ustali\u0107, kt\u00f3re procesy edycyjne zostaj\u0105 w panelu WordPress, a kt\u00f3re maj\u0105 by\u0107 dost\u0119pne przez GraphQL, na przyk\u0142ad publikacja komentarzy czy obs\u0142uga koszyka w sklepie.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Integracje_ACF_WooCommerce_i_multisite\"><\/span>Integracje: ACF, WooCommerce i multisite<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>W praktyce najcz\u0119\u015bciej \u0142\u0105czysz WPGraphQL z ACF, aby wygodnie budowa\u0107 modele tre\u015bci. Rozszerzenie do ACF odwzorowuje pola i grupy w schemie, \u0142\u0105cznie z repeaterami i polami relacyjnymi. Na e-commerce przydaje si\u0119 integracja ze sklepem &#8211; odpowiednia wtyczka udost\u0119pnia typy produkt\u00f3w, wariant\u00f3w, koszyk\u00f3w i zam\u00f3wie\u0144 po GraphQL. W \u015brodowiskach multisite WPGraphQL pozwala pobiera\u0107 dane z kontekstem konkretnej strony sieci, co u\u0142atwia budow\u0119 portali i serwis\u00f3w wieloj\u0119zycznych.<\/p>\n<p>Warto pami\u0119ta\u0107, \u017ce niekt\u00f3re integracje udost\u0119pniaj\u0105 jedynie odczyt. Je\u015bli potrzebujesz pe\u0142nych mutacji, sprawd\u017a dokumentacj\u0119 rozszerzenia lub przygotuj w\u0142asne resolvery.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Autoryzacja_i_bezpieczenstwo\"><\/span>Autoryzacja i bezpiecze\u0144stwo<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>Autoryzacja opiera si\u0119 na sesji WordPressa lub tokenach &#8211; najcz\u0119\u015bciej wykorzystywane s\u0105 ciasteczka logowania panelu lub integracja z JWT. W projekcie headless rozdziel interfejs publiczny i panel administracyjny, ograniczaj\u0105c mutacje tylko do zaufanych klient\u00f3w. Minimalny zestaw praktyk to wy\u0142\u0105czenie mutacji dla niezalogowanych u\u017cytkownik\u00f3w, sprawdzanie r\u00f3l i mo\u017cliwo\u015bci u\u017cytkownika przy ka\u017cdym resolverze oraz ograniczanie wra\u017cliwych p\u00f3l w schemie.<\/p>\n<p>GraphQL umo\u017cliwia introspekcj\u0119 schemy, co bywa pomocne w dewelopmencie. W \u015brodowisku produkcyjnym mo\u017cesz ograniczy\u0107 introspekcj\u0119 dla niezalogowanych, wprowadzi\u0107 limity g\u0142\u0119boko\u015bci zapyta\u0144 i bud\u017cet kosztu pola, a tak\u017ce monitorowa\u0107 czas wykonania. Dobrym nawykiem jest logowanie najci\u0119\u017cszych zapyta\u0144 wraz z identyfikatorem klienta.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Wydajnosc_i_cache\"><\/span>Wydajno\u015b\u0107 i cache<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<ul>\n<li>cache obiektowy WordPress &#8211; poprawia czas odpowiedzi resolver\u00f3w,<\/li>\n<li>CDN lub reverse proxy dla zapyta\u0144 tylko do odczytu &#8211; mo\u017cna kechowa\u0107 odpowiedzi na podstawie tre\u015bci zapytania,<\/li>\n<li>mechanizmy batchowania i kolejkowania w resolverach &#8211; ograniczaj\u0105 liczb\u0119 zapyta\u0144 SQL,<\/li>\n<li>persisted queries &#8211; zapisane po stronie serwera operacje z hashami, kt\u00f3re upraszczaj\u0105 cache i podnosz\u0105 bezpiecze\u0144stwo,<\/li>\n<li>paginacja kursorem &#8211; stabilna przy du\u017cych zbiorach i modyfikacjach tre\u015bci.<\/li>\n<\/ul>\n<p>Zadbaj o indeksy w bazie, zw\u0142aszcza w tabelach postmeta i term_relationships, oraz o sensown\u0105 struktur\u0119 p\u00f3l. Nieu\u017cywane lub bardzo ci\u0119\u017ckie pola trzymaj poza domy\u015blnymi fragmentami, aby unikn\u0105\u0107 przypadkowego doci\u0105gania du\u017cych kolekcji.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"REST_API_czy_GraphQL_%E2%80%93_co_wybrac\"><\/span>REST API czy GraphQL &#8211; co wybra\u0107<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>REST jest prosty, klarowny i dobrze wspierany przez narz\u0119dzia, ale cz\u0119sto wymaga wielu \u017c\u0105da\u0144 do z\u0142o\u017conych widok\u00f3w. GraphQL pozwala pobra\u0107 wszystko jednym wywo\u0142aniem i precyzyjnie kontrolowa\u0107 zakres danych. Je\u015bli tworzysz klasyczny motyw PHP lub korzystasz z ma\u0142ych integracji, REST wystarczy. Gdy budujesz z\u0142o\u017cony frontend SPA, hybrydowy SSR lub aplikacje mobilne, WPGraphQL daje wi\u0119ksz\u0105 elastyczno\u015b\u0107 i ni\u017cszy narzut komunikacyjny.<\/p>\n<p>W realnych projektach oba podej\u015bcia cz\u0119sto wsp\u00f3\u0142istniej\u0105. Drobne integracje i webhooki obs\u0142uguje REST, a widoki klienckie i listingi dzia\u0142aj\u0105 na GraphQL.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Najczestsze_problemy_i_diagnoza\"><\/span>Najcz\u0119stsze problemy i diagnoza<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>Je\u015bli zapytania s\u0105 wolne, sprawd\u017a czy nie prosisz o zbyt g\u0142\u0119bokie relacje lub du\u017ce kolekcje bez limit\u00f3w. Objawem jest d\u0142ugi TTFB przy pierwszym \u017c\u0105daniu. W\u0142\u0105cz logi zapyta\u0144 SQL i profiluj resolvery. Gdy brakuje p\u00f3l w schemie, upewnij si\u0119, \u017ce typy niestandardowe i pola maj\u0105 odpowiednie flagi ekspozycji, a rozszerzenia s\u0105 aktywne. B\u0142\u0119dy uprawnie\u0144 zwykle wynikaj\u0105 z braku r\u00f3l lub niestandardowych polityk zdolno\u015bci &#8211; przetestuj zapytanie na koncie o minimalnych uprawnieniach.<\/p>\n<p>Konflikty z innymi wtyczkami zdarzaj\u0105 si\u0119, gdy modyfikuj\u0105 one globalne zapytanie WordPressa lub filtry autoryzacji. Izoluj problem, wy\u0142\u0105czaj\u0105c dodatki i testuj\u0105c schema w GraphiQL. W razie potrzeby dodaj w\u0142asne resolvery, kt\u00f3re omijaj\u0105 kosztowne hooki.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Dobre_praktyki_wdrozenia_headless\"><\/span>Dobre praktyki wdro\u017cenia headless<span class=\"ez-toc-section-end\"><\/span><\/h2>\n<p>Na etapie projektowania modeli tre\u015bci planuj struktur\u0119 p\u00f3l tak, aby odzwierciedla\u0142a komponenty frontendu. Stosuj fragmenty GraphQL do ponownego u\u017cycia selektor\u00f3w i trzymaj wsp\u00f3lne zestawy p\u00f3l w jednym miejscu. Wprowad\u017a persisted queries dla kluczowych widok\u00f3w 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\u0119dziach deweloperskich.<\/p>\n<p>W pipeline CI buduj testy zapyta\u0144 &#8211; sprawdzaj, czy schema nie uleg\u0142a niezamierzonej zmianie i czy krytyczne operacje zwracaj\u0105 wymagane pola. Dla tre\u015bci dynamicznych \u0142\u0105cz GraphQL z webhooks, aby od\u015bwie\u017ca\u0107 cache po publikacji. Taki setup zapewni przewidywaln\u0105 wydajno\u015b\u0107 i stabilno\u015b\u0107 nawet przy du\u017cych zasi\u0119gach.<\/p>\n","protected":false},"author":6,"featured_media":10957,"parent":0,"menu_order":0,"template":"","format":"standard","manualknowledgebasecat":[118,5649],"manual_kb_tag":[6069,1004,166,6072,6067,6068,6074,6073,6071,6075,6070,1555,76,5068,3537],"class_list":["post-15390","manual_kb","type-manual_kb","status-publish","format-standard","has-post-thumbnail","hentry","manualknowledgebasecat-pozostale","manualknowledgebasecat-wtyczki-wordpress","manual_kb_tag-acf","manual_kb_tag-autoryzacja","manual_kb_tag-cache","manual_kb_tag-graphiql","manual_kb_tag-graphql","manual_kb_tag-headless-cms","manual_kb_tag-paginacja-kursorem","manual_kb_tag-persisted-queries","manual_kb_tag-resolver","manual_kb_tag-rest-vs-graphql","manual_kb_tag-schema","manual_kb_tag-woocommerce","manual_kb_tag-wordpress","manual_kb_tag-wpgraphql","manual_kb_tag-wydajnosc"],"_links":{"self":[{"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/manual_kb\/15390","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/manual_kb"}],"about":[{"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/types\/manual_kb"}],"author":[{"embeddable":true,"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/users\/6"}],"version-history":[{"count":1,"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/manual_kb\/15390\/revisions"}],"predecessor-version":[{"id":15391,"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/manual_kb\/15390\/revisions\/15391"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/media\/10957"}],"wp:attachment":[{"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/media?parent=15390"}],"wp:term":[{"taxonomy":"manualknowledgebasecat","embeddable":true,"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/manualknowledgebasecat?post=15390"},{"taxonomy":"manual_kb_tag","embeddable":true,"href":"https:\/\/dhosting.pl\/pomoc\/wp-json\/wp\/v2\/manual_kb_tag?post=15390"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}