Migracja z WordPress na Astro i zachowanie pozycji SEO

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 StriveLab.

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.

Wydajność. Typowy WordPress z cache osiąga LCP 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łasnie 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 CMS (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.

1. Jak wyeksportować treści z WordPressa

Masz dwie główne opcje, WP REST API albo WXR (WordPress eXtended RSS).

Eksport treści przez WordPress REST API

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

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ą:

// 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.

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.

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:

npm install turndown turndown-plugin-gfm

Skrypt transformujący:

// 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)
 
// Usuwa klasy WP, które nie mają sensu w Astro
td.addRule('stripWPClasses', {
  filter: (node) =>
    node.hasAttribute?.('class') &&
    node.getAttribute('class').startsWith('wp-'),
  replacement: (content) => content,
})
 
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) {
  const slug = post.slug
  const title = decodeEntities(post.title.rendered)
  const excerpt = stripHtml(post.excerpt.rendered).slice(0, 160)
  const date = post.date.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)}"
description: "${escapeQuotes(excerpt)}"
date: ${date}
author: "Maciej Sala"
tags: ${JSON.stringify(tagSlugs)}
---
 
${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, '\\"')
}
 
function decodeEntities(str) {
  // Prosty decoder dla najczęstszych entities
  return str
    .replace(/&amp;/g, '&')
    .replace(/&#8211;/g, '–')
    .replace(/&#8217;/g, "'")
}

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

// 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: z.object({
    title: z.string(),
    description: z.string(),
    date: z.coerce.date(),
    author: z.string().default('Maciej Sala'),
    tags: z.array(z.string()).default([]),
    image: z.string().optional(),
    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]) wychodzą jako tekst i trzeba je albo usunąć, albo przetłumaczyć na komponenty MDX. Prosty regex do usunięcia:

contentMd = contentMd.replace(/\[caption[^\]]*\](.*?)\[\/caption\]/g, '$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ć.

Linki wewnętrzne — posty często linkują do innych postów, a po migracji linki wciąż wskazują na stare URL WordPress. Do tego jeszcze wrócę.

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 astro:assets

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

// download-images.mjs
import fs from 'node:fs/promises'
import path from 'node:path'
import fetch from 'node-fetch'
 
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) {
    const filename = path.basename(new URL(url).pathname)
    const localPath = `../../assets/blog/${filename}`
 
    // Download
    const res = await fetch(url)
    if (!res.ok) continue
    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))
}

W MDX dodajesz importy na górze każdego pliku (można to zautomatyzować skryptem) albo używasz wtyczki remark do automatycznej konwersji ![](...) na <Image src="...">.

Pozostawienie obrazów na serwerze WordPressa

Szybsze , ale gorsze dla SEO, ponieważ tracisz automatyczną optymalizację Astro, a CLS 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 krótki deadline na migrację.

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ź 301 (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ę.

WordPress domyślnie używa /2023/04/tytul-posta/ albo /category/slug/. Astro zwykle /blog/slug/. Mapowanie może wyglądać tak:

/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:

// 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) => {
    const oldUrl = new URL(post.link).pathname // np. /2023/04/jak-wybrac-framework/
    const newUrl = `/blog/${post.slug}/`
    return `${oldUrl} ${newUrl} 301`
  })
  .join('\n')
 
await fs.writeFile('public/_redirects', redirects)

Przekierowania 301 w pliku _redirects dla Cloudflare i Netlify

/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

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.

Przekierowania w konfiguracji Astro

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

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

W trybie serwerowym (output: 'server' lub trasa z prerender = false) Astro bez problemu zwróci prawidłowy status HTTP 301. Problemem będzie czysto statyczny build, gdzie domyślnie generowane są pliki HTML z meta refresh. Dla użytkownika strona się przekieruje, ale dla Google to sygnał o niższej randze, który osłabia transfer autorytetu. 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ą:

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

Oczekiwana odpowiedź:

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.

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.

• Core Web Vitals na przynajmniej 5 losowych stronach są w zieleni.

• 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.

Szczerzej 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ż TTL 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).

4. Obserwuj Search Console. Sekcja Strony → Zaindeksowane pokaże, jak Google przetwarza przekierowania. Nowe URL-e zaczną się pojawiać zwykle w ciągu 2-14 dni.

5. 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 z 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 Strony 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.

• 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.