SEO w Astro: jak sprawić, by witryna w Astro zajmowała wysokie pozycje w wynikach wyszukiwania

TL;DR: Astro zapewnia solidne podstawy SEO, ponieważ domyślnie pre-renderuje statyczny HTML i usuwa po stronie klienta JavaScript. Ustaw site w astro.config.mjs, trzymaj treści, które mają być indeksowane, poza komponentami client:only, a następnie skonfiguruj unikalne metadane, absolutne canonicals, sitemapę oraz jeden spójny format adresów URL. Na koniec sprawdź wygenerowany HTML. Czysta struktura komponentów nie dowodzi, że wdrożona strona jest crawlable.

Astro jest dobre dla SEO, ale nie robi SEO za Ciebie

Najmocniejsza strona SEO w Astro nie jest żadnym pakietem SEO. To model renderowania Astro.

„Domyślnie Astro automatycznie renderuje każdy komponent interfejsu tylko do HTML i CSS, automatycznie usuwając całego client-side JavaScript.”

To jest opis samego Astro z jego dokumentacji architektury Islands. Astro „hydratuje” tylko te komponenty, które zostały jawnie oznaczone do uruchamiania w przeglądarce, a resztę strony zostawia jako statyczny HTML.

Ta różnica ma znaczenie, ponieważ Google nie traktuje pobrania JavaScript i jego uruchomienia jako tego samego procesu.

„Google przetwarza aplikacje webowe z JavaScriptem w trzech głównych fazach: 1. Crawlowanie 2. Renderowanie 3. Indeksowanie”

Google Search Central dodatkowo wyjaśnia, że headless Chromium renderuje stronę wtedy, gdy zasoby Google na to pozwolą. Google potrafi renderować JavaScript, ale treści, które istnieją dopiero po wykonaniu kodu, zależą od tej dodatkowej fazy. Domyślny tryb Astro z statycznym HTML usuwa tę zależność, ponieważ sensowna treść może już być obecna w odpowiedzi. Nasz przewodnik po SEO pod JavaScript omawia mechanizm dokładniej.

To realna przewaga techniczna. Nie jest to automatyczna przewaga w rankingu. Styczny HTML nie uratuje cienkich stron, zduplikowanych title, słabego wewnętrznego linkowania, przypadkowej canonicalizacji ani treści, których nikt nie potrzebuje.

Astro dostarcza wyjątkowo dobre „okablowanie”. Wciąż musisz je poprawnie podłączyć.

Najpierw ustaw URL produkcyjnego serwisu

Zanim dodasz komponent SEO, skonfiguruj site w astro.config.mjs:

Ustaw ją raz w konfiguracji Astro, aby canonicals i mapa strony wskazywały prawdziwe adresy URL:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',   // zasila canonical URL i sitemapę
  integrations: [sitemap()],
});

W Configuration Reference Astro site jest zdefiniowane jako docelowy URL po wdrożeniu i jest tam wskazane, że Astro wykorzystuje tę wartość do generowania sitemap i canonical URL. Domyślnie jest to undefined, a Astro zdecydowanie rekomenduje ustawienie tej opcji.

Jedna linia steruje kilkoma systemami:

• Astro.site jest niezdefiniowane bez tej wartości.
• @astrojs/sitemap potrzebuje jej, aby generować URL-e w sitemap.
• @astrojs/rss korzysta z niej do tworzenia linków do artykułów.
• Canonical i URL-e do obrazów społecznościowych potrzebują jej jako pewnego originu produkcyjnego.

Widzieliśmy obraz tego uzależnienia podczas migracji z seojuice.io do seojuice.com w styczniu 2026. Canonicals, wpisy w sitemap, URL-e Open Graph oraz wewnętrzne odniesienia musiały zejść się w jeden origin produkcyjny. Migracja robi ten problem oczywistym; zapomniane ustawienie site ukrywa tę samą klasę błędu wewnątrz pozornie udanego builda.

Ustaw URL produkcyjny, wykonaj build i sprawdź wynik, zanim zaczniesz debugować integracje „w dół łańcucha” (jeden origin, kilka symptomów).

Zbuduj jeden komponent head, a nie dziesiątki wariantów

Astro nie dostarcza specjalnej abstrakcji do metadanych. Title i opisy to zwykłe tagi HTML. Dla większości serwisów podejściem, które da się utrzymać w czasie, jest wspólny layout, który przyjmuje wartości specyficzne dla strony przez Astro.props.

Pierwsza i trzecia linia to „ogrodzenia” frontmatter Astro. Każda strona albo wpis treści powinna dostarczyć własny title i opis. Fallback jest przydatny do łapania niekompletnych danych, ale nie pozwól, by domyślna wartość dla całej witryny cicho stała się metadanymi dla każdego URL.

Preferuję walidację wymaganych metadanych podczas builda zamiast odkrywania braków w Search Console dopiero tygodnie później. Jeśli publiczna strona z treścią nie ma title ani opisu, to często bardziej „przyjazne” jest przerwać build niż wypuszczać stronę z pustymi metadanymi.

Czy używać pakietu astro-seo?

Społecznościowy pakiet astro-seo może opakować te typowe tagi. Instalujesz go komendą npm install astro-seo, importujesz SEO z paczki i renderujesz komponent w sekcji head dokumentu. W repozytorium znajdziesz wsparcie dla tytułów, opisów, canonicali, dyrektyw robots, Open Graph, Twitter cards, template’ów title, alternatyw językowych oraz niestandardowych tagów.

Bądź precyzyjny: astro-seo to komponent strony trzeciej utrzymywany przez jonasmerlin, a nie oficjalna integracja @astrojs. Użyłbym go wtedy, gdy jego API usuwa realną powtarzalność. Dla małej strony marketingowej lokalny komponent head często jest łatwiejszy do audytu i trudniej go „przewymiarować” w przyszłości (mniej zależności może być zaletą, nie preferencją estetyczną).

Trzymaj metadane social obok metadanych pod wyszukiwarki

Open Graph i Twitter cards to standardowe tagi meta. Generuj je w tym samym wspólnym komponencie head, żeby title strony, opis, canonical URL i obraz nie rozjeżdżały się niezależnie. Obrazy social powinny używać absolutnych URL opartych o Astro.site; relatywne ścieżki to częsty powód, dla którego podglądy działają w jednej usłudze, a nie działają w drugiej.

Generuj canonicals z originu produkcyjnego i aktualnej ścieżki

Astro udostępnia dwie wartości potrzebne do canonicala. Astro.site zwraca URL bazujący na skonfigurowanym miejscu produkcyjnym, a Astro.url reprezentuje bieżący adres URL z requestu.

Oficjalna API Reference podaje taki wzorzec:

To łączy aktualną ścieżkę z originem produkcyjnym, zapobiegając temu, by hostname z developmentu albo podglądu stał się canonical tylko dlatego, że obsłużył request (hosty podglądowe nie powinny „dostać głosu”).

Zwróć uwagę, że wzorzec używa Astro.url.pathname, a nie pełnego adresu URL z requestu. W efekcie odrzuca parametry zapytania. To zwykle poprawne dla parametrów śledzących i zwykłych stron z treścią, ale nie zawsze. Paginacja, filtrowane kolekcje oraz faktycznie różne strony oparte o parametry wymagają jawnej polityki canonicali.

Canonical nie jest ogólną „flagą SEO”. To deklaracja, który URL jest wersją autorytatywną danej strony. Sprawdź finalną wartość.

Trailing slashes traktuj jako świadomą decyzję

Opcja Astro trailingSlash domyślnie ma wartość ignore. Ustawienia always i never wymuszają jedną formę dla produkcyjnych tras na żądanie, a domyślna wartość pozwala przyjąć dowolny format w development i w renderowaniu on-demand.

Przy wyjściu statycznym wynik wpływa też zachowanie hosta i wygenerowane pliki. Wybierz jedną, kanoniczną formę, generuj linki wewnętrzne w tej formie i przetestuj, jak wdrożony host obsługuje oba warianty. Zmiana samego ustawienia Astro nie gwarantuje, że każdy host statyczny zastosuje przekierowania, których oczekujesz.

Celem jest spójność: linki wewnętrzne, canonicals, wpisy w sitemap i przekierowania powinny wskazywać na ten sam format URL. Nasz przewodnik SEO dla developerów opisuje szerszą dyscyplinę wdrożeniową stojącą za tą decyzją.

Zainstaluj oficjalną integrację sitemap

Uruchom npx astro add sitemap, aby zainstalować oficjalną integrację Astro @astrojs/sitemap.

Zgodnie z oficjalną dokumentacją sitemap integracja potrzebuje URL-a wdrożonej strony, zaczynającego się od http:// albo https://. Bez site nie wygeneruje mapy strony.

Po buildzie Astro dodaje do katalogu wyjściowego sitemap-index.xml oraz sitemap-0.xml. Index odsyła do ponumerowanych plików sitemap. Domyślny limit to 45 000 wpisów na plik; po przekroczeniu tworzone są kolejne ponumerowane pliki (45 000 to próg podziału, a nie rekomendacja, by produkować strony).

Po wdrożeniu sprawdź kilka wpisów. Zweryfikuj protokół, hostname, ścieżki, konwencję slash oraz to, czy nie wślizgnęły się prywatne lub pomocnicze strony. Otwórz też index sitemap i przejdź po linkach podrzędnych. Widziałem technicznie poprawne pliki sitemap wdrożone pod ścieżkami, których nikt nie testował.

Sitemap pomaga w odkrywaniu; nie wymusza indeksowania. Jak wygląda reszta procesu, zobacz jak działa indeksowanie w Google.

Astro island trap dotyczy konkretnie client:only

Astro islands nie są z definicji złe dla SEO. Takie stwierdzenie miesza selektywne „hydration” z renderowaniem wyłącznie po stronie klienta.

W directives reference Astro jest napisane, że client:only „pomija renderowanie HTML po stronie serwera i renderuje tylko po stronie klienta”. To, co umieścisz w tym komponencie, nie trafia do początkowego HTML-a renderowanego na serwerze i zależy od wykonania JavaScriptu.

Nie wkładaj kopiowanego tekstu artykułu, opisów produktów, odpowiedzi do FAQ, głównej nawigacji, linków wewnętrznych ani innych treści, które mają być indeksowane, do client:only. Rezerwuj to miejsce dla interfejsów, których nie da się wyrenderować na serwerze i których zawartość nie musi pojawić się w początkowej odpowiedzi.

client:load, client:idle i client:visible to coś innego. One renderują początkowy HTML po stronie serwera, a dopiero potem kontrolują moment hydration. Problemem nie są same React, Vue, Svelte ani islands. Problemem jest pomijanie renderowania po stronie serwera albo pobieranie kluczowych tekstów wyłącznie w przeglądarce.

Z tego, co widzimy na stronach sprawdzanych przez SEOJuice, ujawniająca się awaria w buildach na frameworkach JavaScript zwykle nie wynika z braku sitemap. To raczej strona wyglądająca na kompletnej w przeglądarce, podczas gdy sensowna treść body nie ma jej w surowej odpowiedzi HTML. W Astro jednym oczywistym miejscem do sprawdzenia jest granica client:only, ale wyłącznie dane ładowane po stronie przeglądarki mogą dać ten sam efekt.

Ten błąd zrobiłem, bo sprawdzałem tylko stronę po renderowaniu. Dokładniej: przejrzałem to, co odtworzyła przeglądarka, a nie to, co zwrócił serwer. Obejrzenie źródła odpowiedzi zakończyłoby dochodzenie dużo wcześniej. To ta sama awaria typu „app-shell”, o której piszemy w naszym SPA SEO best practices.

Używaj wyjścia statycznego, chyba że renderowanie w czasie requestu rozwiązuje realny problem

„Domyślnie cała Twoja strona Astro zostanie pre-renderowana, a statyczne strony HTML trafią do przeglądarki.”

To pochodzi z przewodnika po renderowaniu na żądanie w Astro. Domyślny tryb output: 'static' generuje strony podczas builda. To prosta i sensowna opcja dla dokumentacji, artykułów, landing page’ów i treści produktowych, które nie zależą od danych specyficznych dla konkretnego requestu.

output: 'server' renderuje strony na żądanie i wymaga adaptera dla docelowego runtime, np. Node, Netlify, Vercel lub Cloudflare. Renderowanie po stronie serwera może zwracać kompletne HTML i nie jest z natury gorsze dla SEO. Po prostu dokładamy infrastrukturę runtime, opóźnienia i kolejną powierzchnię awarii. Używaj tego wtedy, gdy strona tego wymaga, a nie dlatego, że SSR brzmi „bardziej kompetentnie”.

Możesz łączyć oba zachowania. W trybie statycznym wyeksportuj prerender = false z tej strony, która musi renderować się na żądanie. W trybie serwerowym wyeksportuj prerender = true dla strony, którą chcesz wygenerować wcześniej.

Starsze poradniki mogły polecać output: 'hybrid'. Astro 5 złożyło stare hybrydowe zachowanie do 'static'; Astro 5 upgrade guide opisuje, że 'hybrid' i 'static' zostały połączone w jedną konfigurację statyczną. Aktualne projekty powinny używać static albo server i nadpisywać prerender per strona.

Dodaj RSS, jeśli serwis publikuje cykliczne treści

Astro udostępnia oficjalny pakiet @astrojs/rss do feedów generowanych przez endpointy API. Zainstaluj go komendą npm install @astrojs/rss, a potem utwórz endpoint, np. src/pages/rss.xml.js, który zwraca helper RSS z site: context.site oraz elementami feeda.

Dokumentacja RSS w Astro wymaga skonfigurowanego site, ponieważ origin jest używany do budowania linków do artykułów. To kolejny powód, aby traktować site jako fundament konfiguracji, a nie tylko opcję specyficzną dla sitemap.

Sprawdzaj zbudowaną stronę, a nie tylko komponenty w kodzie

Komponenty w Astro mogą wyglądać poprawnie, mimo że wdrożony output jest zły. Zrób build i deploy, a potem zweryfikuj:

1. Surowa odpowiedź HTML zawiera główną treść i kluczowe linki.
2. Każda strona indeksowalna ma odpowiedni title i meta description.
3. Canonical jest absolutny, używa HTTPS i wskazuje na hostname produkcyjny.
4. Canonicals, linki wewnętrzne, przekierowania i URL-e w sitemap używają tej samej konwencji trailing slash.
5. Obrazy Open Graph i Twitter mają absolutne URL-e produkcyjne.
6. sitemap-index.xml istnieje i odwołuje się do osiągalnych sitemap podrzędnych.
7. Nie ma indeksowalnych treści wyłącznie wewnątrz komponentów client:only.
8. Strony, które mają być statyczne, pojawiają się w wygenerowanym output builda.
9. Hosty podglądu i staging nie emitują się same jako canonical.
10. Przekierowania zachowują się tak, jak oczekujesz na realnej platformie hostingowej.

Użyj „view source”, pobierz URL bez polegania na wykonaniu kodu w przeglądarce i przejrzyj wdrożone pliki. Panel Elements w DevTools pokazuje DOM po wykonaniu skryptów, co jest przydatne, ale odpowiada na inne pytanie (nadal łapię się na tym, że najpierw sprawdzam ten „niewłaściwy”).

Astro dobrze obsługuje fundament renderowania. Powtarzalna praca polega na utrzymaniu metadanych, linków wewnętrznych, schemy i spójności stron, gdy serwis rośnie. SEOJuice może działać na Astro dzięki snippetowi JavaScript i stale wdrażać poprawki na stronie, takie jak linki wewnętrzne, meta title i opisy, schema markup oraz tekst alternatywny obrazów. darmowy SEO audit to też sposób bez rejestracji, by przejrzeć dostarczone metadane i canonicals.

To nie jest zamiennik dla ustawienia site, wygenerowania sitemap ani dla trzymania treści indeksowalnych w początkowym HTML. Automatyzacja powinna stać na wierzchu poprawnego builda.

Często zadawane pytania

Czy Astro jest dobre dla SEO?

Tak. Astro pre-renderuje statyczny HTML i domyślnie usuwa po stronie klienta JavaScript, więc treść może być obecna w początkowej odpowiedzi zamiast zależeć od odroczonej fazy renderowania JavaScriptu w Google. Ranking nadal zależy od tego, czy treści są użyteczne, czy metadane są poprawne, jak wygląda wewnętrzne linkowanie, canonicals i inne decyzje wdrożeniowe.

Jak dodać meta title i opisy w Astro?

Dodaj standardowe tagi title i meta-description do wspólnego layoutu, a potem przekazuj unikalne wartości przez Astro.props dla każdej strony. Alternatywą jest społecznościowy pakiet astro-seo, ale nie jest to oficjalna integracja w Astro.

Jak dodać sitemapę do strony w Astro?

Uruchom npx astro add sitemap i ustaw site na wdrożony URL w astro.config.mjs. Następnie build wygeneruje sitemap-index.xml i sitemap-0.xml. Bez konfiguracji site integracja nie będzie w stanie wygenerować sitemap.

Jak ustawić canonical URL w Astro?

Użyj opisanego w dokumentacji wzorca Astro: zbuduj URL za pomocą new URL(Astro.url.pathname, Astro.site), a potem wypisz tę wartość w tagu canonical. Ustaw najpierw site, bo w przeciwnym razie Astro.site jest niezdefiniowane.

Jaka jest różnica między wyjściem statycznym a SSR w Astro?

output: 'static' jest domyślnym ustawieniem i pre-renderuje strony do HTML podczas builda. output: 'server' renderuje na żądanie i wymaga adaptera. Możesz mieszać zachowania per strona, używając w trybie statycznym prerender = false albo w trybie serwerowym prerender = true.

Dlaczego moja sitemap albo canonical URL w Astro nie działa?

Sprawdź najpierw site. Domyślnie jest niezdefiniowane, a generowanie sitemap, budowanie Astro.site, konstrukcja canonicali, linki RSS do artykułów oraz wiele absolutnych adresów social na tym polega. Ustaw je na finalny origin po HTTPS, zrób rebuild i sprawdź wygenerowany output.