Przejdź do treści

Migracja z WordPress na Astro i zachowanie pozycji SEO

Maciej Sala

Founder StriveLab

16 min czytaniaAktualizacja

Szybka odpowiedź: jak przenieść bloga z WordPressa na Astro bez utraty pozycji w Google?

  • Traktuj migrację jako projekt SEO, a nie przenoszenie plików.
  • Treści wyeksportuj przez REST API albo WXR i przekonwertuj do MDX w Content Collections, a obrazy przenieś do astro:assets.
  • Każdy stary adres zmapuj na równoważną stronę z przekierowaniem 301, zaczynając od tych z ruchem organicznym.
  • Przed zmianą DNS przetestuj całość na środowisku testowym i przygotuj plan wycofania.
  • Przez pierwsze 14 dni obserwuj indeksację, błędy 404 i przekierowania w Search Console i logach.

Migracja przy rozsądnym planie zamyka się w około 2–3 tygodniach i zwraca się w wydajności, stabilności SEO oraz niższych kosztach hostingu. Poniżej proces, który wielokrotnie przechodziłem przy projektach klientów pozwala skutecznie dokonać przeniesienia danych i adresów na nowy framework.

Jeśli zamiast Astro rozważasz Next.js jako cel migracji, zajrzyj do mojego równoległego artykułu o migracji WordPress → Next.js. Proces jest podobny, ale wiele szczegółów różni się przez architekturę frameworków.

Co daje migracja z WordPressa na Astro?

Migracja musi być bardzo dobrze przemyślaną decyzją, dlatego zanim zaczniesz, zdefiniuj mierzalne cele. Dopiero kolejnym krokiem jest właściwa część migracji.

Wydajność. W projektach, które migrowałem, typowy WordPress z cache osiągał 2–4 s, podczas gdy Astro naturalnie schodzi do 0,5–1,5 s bez jakiejkolwiek dodatkowej wtyczki. Jest to po prostu konsekwencja przemyślanej architektury, która oznacza mało JavaScriptu, statyczny HTML i obrazy optymalizowane podczas budowania.

Koszty. WordPress wymaga hostingu zarządzanego (60-300 złotych miesięcznie) albo VPS-a z własną obsługą, aktualizacjami i zabezpieczeniami. Astro na Cloudflare Workers może zaczynać od zera, a darmowy plan wystarcza dla większości małych i średnich blogów.

Bezpieczeństwo. WordPress to jedno z najczęściej atakowanych narzędzi w sieci, a szczególnym polem do popisu są różnego rodzaju wtyczki. Astro jako statyczny build ma znacznie mniejszą powierzchnię ataku, ponieważ nie ma PHP, ani bazy danych w runtime i nie ma panelu admina wystawionego publicznie.

Komfort pracy programistycznej. Edycja treści w MDX w VS Code, autouzupełnianie, własne komponenty i wersjonowanie w Git. To wszystko dla osób technicznych to duży skok jakościowy, mogę sam śmiało polecić takie podejście (ten artykuł właśnie tak powstał).

Ograniczenie dla zespołu bez programisty: jeśli treści edytuje nietechniczny copywriter bez dostępu do repozytorium, kombinacja Astro oraz pliki MDX nie wystarczą. Wtedy lepszą opcją jest Astro połączony z headless (Storyblok, Sanity, Contentful) albo pozostawienie WordPressa w roli źródła treści, a Astro jako frontendem.

Migracja z WordPressa na Astro krok po kroku

Cały proces dzielę na sześć etapów:

  1. Eksport treści z WordPressa.
  2. Transformacja i import do Content Collections.
  3. Migracja obrazów do astro:assets.
  4. Mapowanie URL-i i generowanie przekierowań 301.
  5. Wdrożenie na środowisko testowe i weryfikacja.
  6. Przełączenie produkcji i monitoring.

Każdy z tych etapów rozbijam niżej.

Zanim zaczniesz: inwentaryzacja URL-i i punkt odniesienia

Przed pierwszym eksportem zbierz pełną listę adresów starej strony, bo bez niej nie sprawdzisz później, czy mapa przekierowań jest kompletna. Najlepiej połączyć cztery źródła: crawl całej witryny (np. Screaming Frog), eksport stron z raportu Skuteczność w Google Search Console za ostatnie 12–16 miesięcy, strony wejścia z GA lub Plausible oraz listę adresów z linkami zwrotnymi (raport Linki w Search Console albo Ahrefs). Przy okazji zapisz punkt odniesienia, czyli kliknięcia, wyświetlenia i pozycje najważniejszych fraz. Po przełączeniu to z nim porównujesz wyniki, by jasno widzieć potencjalne spadki czy wzrosty pozycji.

Na tym etapie zdecyduj też, czego nie przenosisz. Słabe, nieaktualne wpisy bez ruchu i linków lepiej scalić z mocniejszym artykułem (przekierowanie 301 na niego) albo usunąć i zwracać dla nich status 410, niż przenosić je jeden do jednego.

1. Jak wyeksportować treści z WordPressa

Masz dwie główne opcje, albo .

Eksport treści przez WordPress REST API

REST API jest dostępne domyślnie w każdym WordPressie i możesz pobrać wszystkie posty:

Code
curl "https://twojastrona.pl/wp-json/wp/v2/posts?per_page=100&page=1" > posts-page-1.json
curl "https://twojastrona.pl/wp-json/wp/v2/posts?per_page=100&page=2" > posts-page-2.json
# itd. dla każdej strony wyników

Można też użyć skryptu Node do masowego eksportu co jest lepszą opcją:

Code
// export-posts.mjs
import fs from 'node:fs/promises'
 
const BASE_URL = 'https://twojastrona.pl/wp-json/wp/v2'
 
async function exportAll() {
  const posts = []
  let page = 1
 
  while (true) {
    const res = await fetch(`${BASE_URL}/posts?per_page=100&page=${page}`)
    if (res.status === 400) break // no more pages
 
    const batch = await res.json()
    if (batch.length === 0) break
 
    posts.push(...batch)
    console.log(`Fetched page ${page}, total: ${posts.length}`)
    page++
  }
 
  await fs.writeFile('wp-posts.json', JSON.stringify(posts, null, 2))
  console.log(`Saved ${posts.length} posts`)
}
 
exportAll()

Po wyrenderowaniu przez WP REST API zwraca treść w HTML. Jest to z jednej strony zaleta, z racji tego, że dostajesz finalną zawartość, a z drugiej wada, ponieważ musisz ją potem skonwertować na Markdown.

Pamiętaj, że endpoint /posts bez uwierzytelnienia zwraca tylko opublikowane wpisy. Strony pobierasz osobno z /wp-json/wp/v2/pages, własne typy treści z ich endpointów, a szkice i wpisy zaplanowane wymagają zalogowania, np. przez hasło aplikacji (ang. Application Password).

Eksport WordPressa w formacie WXR

Klasyczny export.xml z panelu WP (Narzędzia → Eksport) zawiera wszystko w jednym pliku XML. Jest to co prawda, starszy format, ale zupełny i ma wszystko: kategorie, tagi, komentarze, autorów i meta pola. Najważniejsza różnica względem REST API polega na tym, że WXR zawiera surową treść z bazy, czyli komentarze bloków Gutenberga i niewyrenderowane shortcode'y, które musisz przetworzyć sam.

Do parsowania WXR w Node rekomenduję wordpress-export-to-markdown albo własny skrypt z xml2js.

Osobiście dla prawie wszystkich migracji używam REST API, który jest prostszy, dostarcza lepiej wyrenderowaną treść, łatwiej ją wziąć do przetworzenia.

2. Konwersja treści WordPressa do MDX i import do Astro Content Collections

Mając JSON z WordPressa, konwertujesz każdy post do pliku MDX i jeśli chcesz przenieść tagi jako slugi, wyeksportuj też /wp-json/wp/v2/tags?per_page=100 do wp-tags.json, ponieważ standardowe pole post.tags zawiera ID, a nie nazwy ani slugi. Kluczowym krokiem jest konwersja HTML do Markdown. I tutaj używam turndown:

Code
npm install turndown turndown-plugin-gfm

Skrypt transformujący:

Code
// transform-to-mdx.mjs
import fs from 'node:fs/promises'
import path from 'node:path'
import TurndownService from 'turndown'
import { gfm } from 'turndown-plugin-gfm'
 
const td = new TurndownService({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
  bulletListMarker: '-',
})
td.use(gfm)
 
// Rozpakowuje kontenery WP (div, span, figure z klasami wp-*), zostawiając treść.
// Nagłówki, listy, cytaty i obrazy też mają klasy wp-* (np. wp-block-heading,
// wp-image-123), więc filtr nie może obejmować wszystkich elementów.
td.addRule('unwrapWPContainers', {
  filter: (node) =>
    ['DIV', 'SPAN', 'FIGURE'].includes(node.nodeName) &&
    (node.getAttribute('class') ?? '').includes('wp-'),
  replacement: (content, node) =>
    node.nodeName === 'SPAN' ? content : `\n\n${content}\n\n`,
})
 
const posts = JSON.parse(await fs.readFile('wp-posts.json', 'utf8'))
const tags = JSON.parse(await fs.readFile('wp-tags.json', 'utf8'))
const tagMap = new Map(tags.map((tag) => [tag.id, tag.slug]))
 
for (const post of posts) {
  // WP koduje polskie znaki w slugach (np. %c5%bc), dlatego dekodujemy je do nazwy pliku
  const slug = decodeURIComponent(post.slug)
  const title = decodeEntities(post.title.rendered)
  // Yoast SEO dodaje do odpowiedzi pole yoast_head_json z title i description,
  // które Google już zna. Excerpt jest tylko awaryjnym zamiennikiem.
  const seoTitle = post.yoast_head_json?.title ?? title
  const description =
    post.yoast_head_json?.description ??
    decodeEntities(stripHtml(post.excerpt.rendered)).slice(0, 160)
  const date = post.date.split('T')[0]
  const updated = post.modified.split('T')[0]
  const contentMd = td.turndown(post.content.rendered)
 
  // WordPress REST API zwraca tagi jako ID. Slugi pobierz osobno z /wp/v2/tags
  // albo przez _embed/custom field i zbuduj mapę id -> slug przed transformacją.
  const tagSlugs = (post.tags ?? []).map((id) => tagMap.get(id)).filter(Boolean)
 
  const frontmatter = `---
title: "${escapeQuotes(title)}"
seoTitle: "${escapeQuotes(seoTitle)}"
description: "${escapeQuotes(description)}"
date: ${date}
updated: ${updated}
author: "Maciej Sala"
tags: ${JSON.stringify(tagSlugs)}
legacyWpId: ${post.id}
---
 
${contentMd}
`
 
  const outputPath = path.join('src/content/blog', `${slug}.mdx`)
  await fs.mkdir(path.dirname(outputPath), { recursive: true })
  await fs.writeFile(outputPath, frontmatter)
  console.log(`Wrote ${outputPath}`)
}
 
function stripHtml(html) {
  return html.replace(/<[^>]+>/g, '').trim()
}
 
function escapeQuotes(str) {
  return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\s+/g, ' ')
}
 
function decodeEntities(str) {
  // Prosty decoder dla najczęstszych entities. Przy większym blogu użyj pakietu `he`.
  return str
    .replace(/&amp;/g, '&')
    .replace(/&#8211;/g, '–')
    .replace(/&#8217;/g, "'")
    .replace(/&#8220;|&#8221;/g, '"')
    .replace(/&hellip;|&#8230;/g, '…')
    .replace(/&nbsp;/g, ' ')
}

Zwróć uwagę na regułę unwrapWPContainers. Od WordPressa 6.2 Gutenberg dodaje klasy wp-block-* także do nagłówków, list i cytatów, a obrazy mają klasę wp-image-*. Reguła, która rozpakowuje każdy element z taką klasą, po cichu zamieniłaby nagłówki H2 w zwykły tekst i usunęła obrazy, dlatego obejmuje tylko kontenery.

Tak samo ważne jest pole seoTitle i description pobierane z Yoasta. To one były wyświetlane w wynikach wyszukiwania, więc zastąpienie ich automatycznym fragmentem wpisu (ang. excerpt) to niepotrzebna zmiana tuż przy migracji. Jeśli korzystasz z Rank Math, włącz w nim obsługę headless i pobierz te same dane z jego endpointu.

Po uruchomieniu, masz folder src/content/blog/ wypełniony plikami MDX i teraz potrzebujesz Content Collections, żeby Astro je rozumiało:

Code
// src/content.config.ts
import { defineCollection } from 'astro:content'
import { glob } from 'astro/loaders'
import { z } from 'astro/zod'
 
const blog = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/blog' }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      seoTitle: z.string().optional(),
      description: z.string(),
      date: z.coerce.date(),
      updated: z.coerce.date().optional(),
      author: z.string().default('Maciej Sala'),
      tags: z.array(z.string()).default([]),
      image: image().optional(), // obraz wyróżniający, optymalizowany przez astro:assets
      legacyWpId: z.number().optional(), // pomocne do debugowania
    }),
})
 
export const collections = { blog }

Szczegóły konfiguracji Content Collections opisuję w osobnym artykule.

Najczęstsze problemy podczas konwersji WordPressa do MDX

Shortcode'y WP (np. [gallery], [caption]). W treści z REST API większość z nich jest już wyrenderowana do HTML, bo content.rendered przechodzi przez filtry WordPressa. Jako tekst zostają shortcode'y wtyczek, które zostały wyłączone, oraz wszystkie shortcode'y przy eksporcie WXR. Trzeba je albo usunąć, albo przetłumaczyć na komponenty MDX. Poniżej masz prosty regex do usunięcia:

Code
contentMd = contentMd.replace(/\[caption[^\]]*\](.*?)\[\/caption\]/gs, '$1')
contentMd = contentMd.replace(/\[gallery[^\]]*\]/g, '')

Tabele z <table> zwykle konwertują się poprawnie przez gfm, ale problemy zaczynają się przy nietypowych strukturach, np. scalonych komórkach albo kolorowaniu. Takie fragmenty trzeba odtworzyć ręcznie albo zostawić jako bloki HTML w MDX.

Bloki kodu. W sytuacji gdy masz wtyczkę typu SyntaxHighlighter, pliki po transformacji będą miały dziwne klasy, a turndown z gfm daje radę, ale i tak wszystko trzeba później przejrzeć.

Składnia MDX jest bardziej rygorystyczna niż Markdown. Nawiasy klamrowe { i }, pojedynczy znak < w tekście oraz komentarze HTML <!-- --> przerwą kompilację. Takie miejsca trzeba poprawić albo zapisać starsze wpisy, które nie potrzebują komponentów, jako zwykłe pliki .md (wtedy w loaderze ustaw wzorzec **/*.{md,mdx}).

Linki wewnętrzne — posty często linkują do innych postów, a po migracji linki wciąż wskazują na stare URL WordPress. Ich przepisanie opisuję przy mapowaniu adresów w etapie 4.

3. Jak przenieść obrazy z WordPressa do Astro

WordPress trzyma obrazy w wp-content/uploads/rok/miesiąc/. Dwa podejścia:

Pobieranie obrazów do

Najlepsze dla SEO i wydajności, skrypt pobierający wszystkie obrazy z treści:

Code
// download-images.mjs
import fs from 'node:fs/promises'
import path from 'node:path'
 
await fs.mkdir('src/assets/blog', { recursive: true })
 
async function processFile(mdxPath) {
  let content = await fs.readFile(mdxPath, 'utf8')
  const images = [
    ...content.matchAll(
      /!\[([^\]]*)\]\((https:\/\/twojastrona\.pl\/wp-content\/uploads\/[^\)]+)\)/g,
    ),
  ]
 
  for (const [match, alt, url] of images) {
    // WP wstawia do treści pomniejszone wersje (np. -1024x683.jpg), więc próbujemy pobrać oryginał
    const originalUrl = url.replace(/-\d+x\d+(?=\.\w+$)/, '')
    let res = await fetch(originalUrl)
    if (!res.ok) res = await fetch(url)
    if (!res.ok) continue
 
    const filename = path.basename(new URL(res.url).pathname)
    const localPath = `../../assets/blog/${filename}`
    const buffer = await res.arrayBuffer()
    await fs.writeFile(`src/assets/blog/${filename}`, Buffer.from(buffer))
 
    // Replace in MDX
    content = content.replace(match, `![${alt}](${localPath})`)
  }
 
  await fs.writeFile(mdxPath, content)
}
 
const files = await fs.readdir('src/content/blog')
for (const file of files.filter((f) => f.endsWith('.mdx'))) {
  await processFile(path.join('src/content/blog', file))
}

Importy w MDX nie są potrzebne. Astro samo optymalizuje lokalne obrazy podane ścieżką względną w składni ![alt](../../assets/blog/obraz.jpg) i przepuszcza je przez astro:assets. Komponent <Image /> z importem przydaje się dopiero wtedy, gdy chcesz ręcznie ustawić np. widths albo sizes.

Skrypt obsługuje obrazy osadzone w treści, a do poprawienia zostają jeszcze dwie rzeczy:

  • Obraz wyróżniający nie jest częścią treści, tylko polem featured_media. Pobierz go osobno (najprościej dodając _embed do zapytania REST API), zapisz w src/assets/blog/ i podaj ścieżkę w polu image frontmattera. Zwykle to także obraz OG, więc jego brak widać od razu przy udostępnianiu linków.
  • Obrazy opakowane w link do pełnej wersji ([![alt](miniatura)](pełny-obraz.jpg)) po pobraniu miniatury dalej linkują do wp-content/uploads. Po wyłączeniu starego serwera taki link zwróci 404, więc usuń go albo podmień na lokalny plik.

Pozostawienie obrazów na serwerze WordPressa

Szybsze, ale gorsze dla SEO, ponieważ tracisz automatyczną optymalizację Astro, a może na tym ucierpieć. Bez automatycznego określania wymiarów obrazów i generowania responsywnych wersji, przeglądarka może nie zarezerwować odpowiedniej przestrzeni. W rezultacie, prowadzi to do nieprzyjemnych przesunięć layoutu podczas ładowania. Rozważ tylko, jeśli masz gigabajty zdjęć i stosunkowo krótki deadline na migrację. Pamiętaj też, że stary serwer musi wtedy działać dalej, bo jego wyłączenie zabierze wszystkie obrazy.

Niezależnie od podejścia sprawdź, czy obrazy z bloga nie przynoszą ruchu z Google Grafika albo linków zwrotnych. Zmiana ich adresów oznacza utratę tego ruchu, dlatego dla najważniejszych plików dodaj przekierowania 301 ze starych ścieżek wp-content/uploads/... albo zostaw je w public/ pod dotychczasowym adresem.

4. Mapowanie adresów URL i przekierowania 301 po migracji

To najbardziej krytyczny etap dla zachowania pozycji w Google, każdy stary URL musi:

  1. Zwracać odpowiedź (trwałe przekierowanie).
  2. Wskazywać na równoważną stronę na nowej platformie.
  3. Być obsłużony przez nowy serwer, zanim Google przecrawluje stronę.

Astro bez problemu odtworzy dotychczasową strukturę, np. /slug/ albo /rok/miesiąc/slug/, przez odpowiednie nazwy folderów w src/pages/. W sytuacji, kiedy nie masz ważnego powodu, żeby zmieniać adresy, zostaw je bez zmian, a przekierowania ogranicz do archiwów i adresów, które naprawdę znikają.

Gdy jednak zmieniasz strukturę, punktem wyjścia jest typowy układ WordPressa. Często spotkasz /2023/04/tytul-posta/ albo /category/slug/, a w Astro zwykle /blog/slug/. Mapowanie może wyglądać tak:

Code
/2023/04/jak-wybrac-framework/ → /blog/jak-wybrac-framework/
/category/astro/ → /blog/tag/astro/
/author/maciej/ → /o-mnie/

Jak wygenerować mapę przekierowań 301

Jeśli masz jednolity wzorzec, np. wszystkie stare URL-e mają format /rok/miesiąc/slug/, a nowe mają mieć /blog/slug/, generujesz przekierowania automatycznie:

Code
// generate-redirects.mjs
import fs from 'node:fs/promises'
 
const posts = JSON.parse(await fs.readFile('wp-posts.json', 'utf8'))
 
const redirects = posts
  .map((post) => ({
    oldUrl: new URL(post.link).pathname, // np. /2023/04/jak-wybrac-framework/
    newUrl: `/blog/${post.slug}/`,
  }))
  // Bez tego filtra adres, który się nie zmienia, przekierowałby sam na siebie
  .filter(({ oldUrl, newUrl }) => oldUrl !== newUrl)
  .map(({ oldUrl, newUrl }) => `${oldUrl} ${newUrl} 301`)
  .join('\n')
 
await fs.writeFile('public/_redirects', redirects)

Ten sam skrypt uruchom dla stron z wp-pages.json, a wynik porównaj z listą adresów z inwentaryzacji. Generator zna tylko wpisy, więc nie obejmie kilku typów adresów, które WordPress tworzy sam:

  • kanał RSS /feed/ (warto przekierować go na nowy kanał, np. /rss.xml, żeby nie stracić subskrybentów),
  • stronicowanie archiwów /page/2/ oraz archiwa tagów i autorów,
  • strony załączników, które WordPress tworzy dla każdego obrazu,
  • mapę witryny z Yoasta /sitemap_index.xml,
  • krótkie adresy /?p=123.

Adresów z parametrem ?p= plik _redirects na Cloudflare nie obsłuży, bo nie dopasowuje parametrów zapytania. Potrzebna jest wtedy reguła przekierowania w panelu Cloudflare albo middleware w Astro.

Przepisanie linków wewnętrznych

Przekierowania ratują ruch z zewnątrz, ale linki wewnętrzne w treści powinny od razu wskazywać na nowe adresy. Inaczej każde kliknięcie i każdy crawl przechodzi przez dodatkowy skok. Mając gotową mapę, możesz je podmienić jednym skryptem:

Code
// rewrite-internal-links.mjs
import fs from 'node:fs/promises'
import path from 'node:path'
 
const OLD_HOST = 'https://twojastrona.pl'
const redirectMap = new Map(
  (await fs.readFile('public/_redirects', 'utf8'))
    .split('\n')
    .filter(Boolean)
    .map((line) => line.split(' ').slice(0, 2)),
)
 
for (const file of await fs.readdir('src/content/blog')) {
  if (!file.endsWith('.mdx')) continue
  const filePath = path.join('src/content/blog', file)
  const content = await fs.readFile(filePath, 'utf8')
 
  const updated = content.replace(/\]\(([^)\s]+)\)/g, (match, href) => {
    const pathname = href.startsWith(OLD_HOST) ? href.slice(OLD_HOST.length) : href
    const target = redirectMap.get(pathname)
    return target ? `](${target})` : match
  })
 
  await fs.writeFile(filePath, updated)
}

Skrypt nie złapie linków z kotwicą (#sekcja) ani zapisanych bez końcowego ukośnika, dlatego po jego uruchomieniu i tak przecrawluj stronę testową i wyłap linki, które wciąż przechodzą przez przekierowanie.

Przekierowania 301 w pliku _redirects dla Cloudflare i Netlify

Code
/2023/04/jak-wybrac-framework/ /blog/jak-wybrac-framework/ 301
/2023/04/dlaczego-astro/ /blog/dlaczego-astro/ 301
/category/astro/ /blog/tag/astro/ 301
/category/nextjs/ /blog/tag/nextjs/ 301
/author/maciej/ /o-mnie/ 301
/feed/ /rss.xml 301

Plik public/_redirects Astro kopiuje do buildu. Netlify i Cloudflare potrafią zastosować taki plik na poziomie hostingu, ale szczegóły zależą od trybu wdrożenia. Dla migracji SEO najważniejsze jest, żeby przekierowanie było serwerowe i zwracało HTTP 301, a nie tylko klientowy meta refresh.

Na Cloudflare plik _redirects mieści maksymalnie 2000 przekierowań statycznych i 100 dynamicznych. Przy dużym blogu z wieloletnim archiwum szybko dojdziesz do tego limitu, dlatego zamiast wypisywać każdy adres osobno użyj reguł z placeholderami, po jednej na rok (np. /2023/:month/:slug/ /blog/:slug/ 301), albo przekierowań zbiorczych (ang. Bulk Redirects) w panelu Cloudflare.

Ustal też jedną politykę końcowego ukośnika. Opcja trailingSlash w Astro i zachowanie hostingu muszą ze sobą współgrać, inaczej stary adres przejdzie przez dwa skoki: najpierw na właściwą ścieżkę, a potem na wersję z ukośnikiem albo bez niego.

Przekierowania w konfiguracji Astro

Na adapterze Node lub Cloudflare Workers możesz zdefiniować przekierowania w astro.config.mjs:

Code
export default defineConfig({
  redirects: {
    '/2023/04/[slug]': '/blog/[slug]/',
    '/category/[slug]': '/blog/tag/[slug]/',
  },
})

Zwróć uwagę, że przykład obsługuje tylko wpisy z kwietnia 2023. Reguły '/[year]/[month]/[slug]': '/blog/[slug]/' nie zapiszesz, bo Astro wymaga, żeby stara i nowa trasa miały te same parametry. Przy strukturze z datą w adresie lepiej sprawdza się więc wygenerowany plik _redirects niż konfiguracja Astro.

W trybie serwerowym (output: 'server' lub trasa z prerender = false) Astro bez problemu zwróci prawidłowy status HTTP 301. Podobnie przy statycznym buildzie z adapterem, który to obsługuje (np. Netlify, Vercel), bo Astro zapisuje wtedy przekierowania do konfiguracji hostingu. Inaczej jest w czysto statycznym buildzie bez adaptera, gdzie domyślnie generowane są pliki HTML z meta refresh. Google traktuje natychmiastowy meta refresh jak przekierowanie trwałe, ale to wciąż rozwiązanie zastępcze: nie zwraca statusu 301, a inne roboty i narzędzia SEO nie zawsze interpretują je tak samo. Przy migracji serwisu z dużym ruchem organicznym trzeba ustawić przekierowania przez plik _redirects, reguły Cloudflare, Netlify redirects albo konfigurację serwera.

Jak sprawdzić poprawność przekierowań 301

Po wdrożeniu sprawdź każde przekierowanie komendą:

Code
curl -I https://twojastrona.pl/2023/04/jak-wybrac-framework/

Oczekiwana odpowiedź:

Code
HTTP/2 301
location: https://twojastrona.pl/blog/jak-wybrac-framework/

Dla wielu URL-i użyj skryptu, który przechodzi po liście i loguje te, które nie zwracają 301. Sprawdź też łańcuchy przekierowań poleceniem curl -sIL, które podąża za każdym skokiem. Stary adres powinien trafić na docelową stronę z kodem 200 w jednym kroku, a nie przez kolejne przekierowania z http na https, z wersji bez www na www i na wersję z końcowym ukośnikiem. Przekierowań nie usuwaj po kilku tygodniach. Google zaleca utrzymywać je co najmniej rok, a w praktyce najlepiej bezterminowo, bo stare adresy dalej żyją w linkach zwrotnych i zakładkach.

5. Test migracji WordPress–Astro przed wdrożeniem

Przed zmianą DNS rekomenduję pełny test na domenie testowej, np. staging.twojastrona.pl, albo na adresie podglądu z Cloudflare/Vercel.

Lista kontrolna:

  • Wszystkie posty wyświetlają się poprawnie (kod, obrazy, linki).

  • Sitemap generuje się i zawiera wszystkie strony.
  • Metadane (title, description, OG) są poprawne na każdej stronie.

  • Structured data (BlogPosting, FAQPage) walidują się w Rich Results Test.

  • Wyniki Lighthouse na przynajmniej 5 losowych stronach są w zieleni (dane terenowe Core Web Vitals pojawią się dopiero po starcie produkcji).

  • Środowisko testowe jest zablokowane przed indeksacją (hasło albo noindex), a canonicale nie wskazują na jego domenę.

  • Meta title i description najważniejszych stron są zgodne z tymi z WordPressa.

  • Crawl wersji testowej nie pokazuje linków wewnętrznych prowadzących przez przekierowania ani na stare adresy.

  • Kanał RSS działa, a stary /feed/ na niego przekierowuje.
  • Wszystkie przekierowania 301 działają i wskazują na właściwe strony.

  • robots.txt nie blokuje /blog/.
  • 404 error page wyświetla się dla nieistniejących URL (nie reloaduje do homepage).

  • Analytics (GA, Plausible) są zainstalowane i zbierają dane.

Szerzej o tym, co sprawdzać pod kątem SEO, piszę w osobnym artykule.

6. Wdrożenie migracji i monitoring SEO

Moment uruchomienia, czyli zmiana DNS, przez którą cały ruch przechodzi na nową wersję strony, wymaga kilku kroków wykonanych w odpowiedniej kolejności:

1. Obniż w DNS przed przełączeniem. Na 24 h przed migracją zmień TTL rekordów A/AAAA/CNAME na 300 s (5 min), a po przełączeniu propagacja zamiast 24-48 h zajmie kilka minut.

2. Zrób kopię zapasową WordPressa. Pełny backup plików i bazy przed wyłączeniem daje realną drogę powrotu i zmiany decyzji o migracji.

3. Zaktualizuj DNS. CNAME na nowy hosting (Cloudflare / Vercel / Netlify). Dla domeny głównej bez www zwykły rekord CNAME nie zadziała, więc użyj rekordu A wskazanego przez hosting albo spłaszczania CNAME (ang. CNAME flattening). Na Cloudflare Workers najprościej podpiąć domenę jako Custom Domain.

4. Usuń blokady z wersji testowej. Upewnij się, że produkcja nie dziedziczy noindex, hasła ani Disallow: / z robots.txt środowiska testowego. To najczęstsza przyczyna migracji, po której strona znika z Google.

5. Obserwuj Search Console. Raport Indeksowanie stron pokaże, jak Google przetwarza przekierowania. Nowe URL-e zaczną się pojawiać zwykle w ciągu 2-14 dni.

6. Sprawdzaj błędy 4xx/5xx. Analytics i Search Console pokażą URL-e, które dostają 404 — to znak, że jakieś przekierowanie się zgubiło i należy interweniować.

Plan wycofania migracji

Bywa też, że migracja nie idzie jak powinna, przez masowe 404 z powodu brakujących przekierowań, zerowy ruch przez błędną konfigurację DNS, zerwane zasoby statyczne (obrazy serwowane ze starego hosta, który jest już wyłączony) lub błąd buildu powodujący pusty deploy. W każdym z tych przypadków cofasz DNS do starego serwera i uruchamiasz WordPressa z kopii zapasowej (ona zawsze musi być pod ręką).

Uspokajająco dodam, że jeśli środowisko testowe przeszło pełną weryfikację, ryzyko wystąpienia tych scenariuszy jest bardzo niskie.

Monitoring SEO po migracji WordPress–Astro: pierwsze 14 dni

Największe ryzyko migracji nie kończy się w momencie podmiany DNS, dlatego przez pierwsze dwa tygodnie trzeba aktywnie obserwować, czy Google i użytkownicy trafiają w te same odpowiedniki treści. Sugeruję sprawdzać codziennie przez 14 dni, jak kształtuje się sytuacja:

  • Sprawdzaj raport Indeksowanie stron w Google Search Console: 404, soft 404, Crawled - currently not indexed oraz błędy przekierowań.

  • Przetestuj próbkę najważniejszych starych URL-i przez curl -I i potwierdź status 301 oraz poprawny location.

  • Porównaj najważniejsze strony wejścia z GA/Plausible sprzed migracji z nowymi adresami po migracji.

  • Monitoruj logi 404 z hostingu i dopisuj brakujące przekierowania, zanim Google utrwali błąd.

  • Wyślij nową sitemapę w Search Console dopiero wtedy, gdy przekierowania i linki kanoniczne są już poprawne.

  • Jeśli adresy się zmieniły, zostaw w Search Console przez kilka tygodni także starą sitemapę ze starymi URL-ami. Google szybciej odwiedzi stare adresy i odczyta przekierowania.

  • Porównuj kliknięcia i pozycje najważniejszych fraz z punktem odniesienia zapisanym przed migracją.

  • Nie zmieniaj jednocześnie slugów, struktury H1 i treści kluczowych sekcji, jeśli nie musisz. Jedna duża zmiana naraz jest łatwiejsza do zdiagnozowania.

Jak migracja z WordPressa na Astro wpływa na pozycje w Google?

Realistyczne oczekiwania:

Tydzień 1-2: możliwe są wahania widoczności, a ich skala zależy od wielkości serwisu, liczby URL-i, częstotliwości crawlowania, jakości przekierowań i tego, czy przy okazji zmieniłeś treść.

Kolejne tygodnie: Google stopniowo crawluje stare i nowe URL-e, przepisuje sygnały i stabilizuje indeks. Średni serwis często domyka większość migracji w kilka tygodni, ale większe lub bardziej złożone strony mogą potrzebować więcej czasu.

Miesiąc 2-3: jeśli przekierowania, linki kanoniczne i treści są poprawne, widoczność powinna się stabilizować. Lepsze Core Web Vitals mogą pomóc, ale też nas nie zbawią, gdy w grę wchodzi utraty treści, złe mapowanie URL-i i błędy indeksacji.

By wszystko odbyło się, jak należy, przekierowania 301 muszą działać niezawodnie, struktura informacyjna strony musi być zachowana, a treść nie może zostać zdegradowana podczas konwersji. Jeśli te warunki będą wypełnione, wtedy migracja jest neutralna dla SEO, a w dłuższej perspektywie - korzystna.

Kiedy nie warto migrować z WordPressa do Astro

Migracja nie jest dla każdego projektu i nie zawsze jest to dobry pomysł.

  • Jeśli treści edytuje zespół copywriterów bez dostępu do repozytorium, a nie chcesz wprowadzać headless CMS, po prostu zostań na WordPressie. Nie ma potrzeby utrudniać sobie życia.
  • Jeśli strona ma ciężko zależne od WP wtyczki (zaawansowany e-commerce albo multi-vendor marketplace), migracja oznacza przepisanie tych funkcji od zera.
  • Jeśli koszt migracji, czas programisty i ryzyko przekraczają potencjalne korzyści, nie ma sensu tego zmieniać. Zostań tam gdzie jesteś, bo nie każda strona potrzebuje Astro.

Jeśli nie wiesz jeszcze, czy migracja do Astro to dobry wybór, zacznij od matrycy decyzyjnej WordPress, Astro czy Next.js. Migrację mogę też przeprowadzić za Ciebie w ramach stron internetowych w Astro.

Ultraszybkie projekty, łączące lekkość ze skalowalnością.
Astro

Często zadawane pytania

Ile czasu zajmuje migracja bloga z WordPress na Astro?

Blog z 50–200 postami i prostą strukturą: 2–3 tygodnie. Większe witryny z niestandardowymi szablonami i wtyczkami: 6–8 tygodni. Eksport i transformacja to zwykle 2–3 dni, a reszta to mapowanie URL-i, migracja obrazów, testowanie i przełączenie produkcji z monitoringiem.

Czy stracę pozycje w Google po migracji?

Przy poprawnej migracji (przekierowania 301 dla każdego URL-a, zachowana struktura treści, działające metadane) pojawiają się tylko tymczasowe wahania. Google przepisuje sygnały na nowe adresy po re-crawlowaniu. Dla średnich serwisów trwa to kilka tygodni. Rozsypane przekierowania lub degradacja treści generują realne straty widoczności.

Czy mogę zostawić komentarze z WordPressa?

Astro nie ma wbudowanego systemu komentarzy, więc mamy różne opcje. Statyczny HTML z wyeksportowanymi komentarzami (bez nowych), system zewnętrzny (Giscus, Disqus, Cusdis) albo nie wprowadzanie niczego. Dobrym rozwiązaniem jest Giscus oparty na GitHub Discussions, który jest darmowy, bez reklam, z pełną kontrolą. Pamiętaj tylko, że komentujący potrzebuje konta GitHub, więc przy nietechnicznych czytelnikach lepiej sprawdzi się Cusdis.

Co z formularzami kontaktowymi z WordPressa?

Formularze WordPress (Contact Form 7, WPForms) nie migrują się automatycznie. W Astro wdrażaj rozwiązania serverless: Formspree, Basin, Cloudflare Workers z własnym endpointem albo Resend/SendGrid API. Pełny formularz kontaktowy z walidacją to 1–2 dni pracy.

Czy mogę przenieść konfigurację wtyczek SEO, takich jak Yoast albo Rank Math?

Samych wtyczek nie przeniesiesz, ale ich dane tak. Yoast dodaje do odpowiedzi REST API pole yoast_head_json z meta title i description, a Rank Math po włączeniu obsługi headless udostępnia własny endpoint z metadanymi. Wartości pobrane przy eksporcie trafiają do frontmatteru MDX. Po mapowaniu do schematu Content Collections metadane są gotowe do użycia, dodatkowo z walidacją Zod przy każdym buildzie.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat WordPress

Czytaj dalej

Zobacz więcej wpisów
Migracja WordPress do Next.js: SEO i przekierowania 301

Migracja na Next.js nie jest decyzją czysto techniczną, choć może na taką wyglądać. Wraz z nią zmienia się nie tylko sposób renderowania strony, ale często także hosting, model treści, adresy URL oraz narzędzia do redakcji. Ten przewodnik pokazuje, jak znacząco ograniczyć ryzyko związane z migracją WordPressa do Next.js , skutecznie przeprowadzić ten proces i kontrolować efekt po wdrożeniu.

Maciej Sala

Maciej Sala

Founder StriveLab

Czy warto zamienić WordPressa na Astro w projekcie?

WordPress i Astro nie stanowią bezpośrednich alternatyw. Pierwszy z nich to kompleksowy system CMS ze wbudowanym panelem administracyjnym, relacyjną bazą danych oraz rozbudowanym ekosystemem wtyczek, podczas gdy Astro pozostaje nowoczesnym frameworkiem do budowy frontendu. Ostateczny wybór dotyczy zatem całej architektury rozwiązania, czyli sposobu renderowania stron, modelu edycji treści, strategii integracji oraz podziału odpowiedzialności za późniejsze utrzymanie systemu.

Maciej Sala

Maciej Sala

Founder StriveLab

WordPress, Astro czy Next.js? Matryca decyzyjna, zanim ruszysz z migracją

Migracja jest poważnym przedsięwzięciem, ale zanim dodasz pierwsze przekierowanie , potrzebujesz czegoś ważniejszego niż plan techniczny. Musisz wiedzieć, jaki problem rozwiązujesz i po czym poznasz sukces. Ten artykuł daje Ci matrycę pięciu zmiennych, warunki brzegowe oraz sposób weryfikacji decyzji. Finalnie, być może migracja w ogóle nie ma większego sensu i spowoduje więcej problemów niż da korzyści.

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G