Migracja bloga z WordPress na Astro — eksport treści, przekierowania 301 i zachowanie pozycji w Google

WordPress to solidny CMS dla redaktorów nietechnicznych, ale jako silnik bloga pod SEO w 2026 roku ma coraz więcej ograniczeń. Wtyczki spowalniają stronę, Core Web Vitals trudno doprowadzić do zieleni bez głębokiej optymalizacji, a utrzymanie aktualizacji, kopii zapasowych i bezpieczeństwa jest stałym kosztem.

Migracja na Astro nie jest trywialna, ale przy rozsądnym planie zwykle zamyka się w 2-3 tygodniach i szybko zwraca: w wydajności, stabilności SEO i niższych kosztach hostingu. W tym artykule pokazuję 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 realnie wygrywasz na Astro

Zanim zaczniesz, warto mieć jasno określone cele — migracja dla samej migracji to marnotrawstwo czasu.

Wydajność. Typowa strona WordPress z dobrą wtyczką do cache osiąga LCP 2-4 s. Astro naturalnie schodzi do 0.5-1.5 s bez dodatkowej wtyczki do cache. To nie marketing, tylko konsekwencja architektury: mało JavaScriptu, statyczny HTML i obrazy optymalizowane podczas budowania.

Koszty. WordPress wymaga hostingu zarządzanego (15-100 dolarów miesięcznie) albo VPS-a z własną obsługą, aktualizacjami i zabezpieczeniami. Astro na Cloudflare Workers może zaczynać od zera — 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. Astro jako statyczny build ma znacznie mniejszą powierzchnię ataku: nie ma PHP, nie ma 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 — dla osób technicznych to duży skok jakościowy.

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

Plan migracji — etapy

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. Eksport treści z WordPressa

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

WP REST API

REST API jest dostępne domyślnie w każdym WordPressie. Pobierasz 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

Albo lepiej — skrypt Node do masowego eksportu:

// 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()

REST API zwraca treść w HTML (po renderowaniu przez WP). To jest zaleta (dostajesz finalną, wyrenderowaną zawartość) i wada (musisz ją potem skonwertować na Markdown).

WXR export

Klasyczny export.xml z panelu WP (Narzędzia → Eksport) zawiera wszystko w jednym pliku XML. Format starszy, ale zupełny — ma kategorie, tagi, komentarze, autorów, meta pola.

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

Osobiście dla 95% migracji używam REST API — jest prostszy, dostarcza lepiej wyrenderowaną treść, łatwiej ją wziąć do przetworzenia.

2. Transformacja do MDX i import do Content Collections

Mając JSON z WordPressa, konwertujesz każdy post do pliku MDX. Jeśli chcesz przenieść tagi jako slugi, wyeksportuj też /wp-json/wp/v2/tags?per_page=100 do wp-tags.json, bo standardowe pole post.tags zawiera ID, nie nazwy ani slugi. Kluczowy krok — konwersja HTML → Markdown. Dla tego 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. 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 przy transformacji

Shortcode'y WP (np. [gallery], [caption]) wychodzą jako tekst. 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. 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 — jeśli masz wtyczkę typu SyntaxHighlighter, pliki po transformacji będą miały dziwne klasy. Turndown z gfm w większości ogarnia, ale sprawdź po ręcznym przeglądzie.

Linki wewnętrzne — posty często linkują do innych postów. Po migracji linki wciąż wskazują na stare URL WordPress. O tym za chwilę.

3. Migracja obrazów

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

A: Pobranie lokalne i użycie 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="...">.

B: Pozostawienie na starym serwerze

Szybsze, ale gorsze dla SEO — tracisz automatyczną optymalizację Astro, a CLS może cierpieć. Rozważ tylko, jeśli masz gigabajty zdjęć i krótki deadline na migrację.

4. Mapowanie URL-i i przekierowania 301Przekierowanie 301 to stałe przekierowanie HTTP, które informuje przeglądarkę i wyszukiwarkę, że zasób został przeniesiony pod nowy adres.

To jest najbardziej krytyczny etap dla zachowania pozycji w Google. Każdy stary URL musi:

• Zwracać odpowiedź 301 (trwałe przekierowanie).
• Wskazywać na równoważną stronę na nowej platformie.
• 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/

Generowanie mapy przekierowań

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)

Format _redirects dla Cloudflare / 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 klientowski meta refresh.

Alternatywnie — przekierowania w kodzie

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 SSR/hybrid Astro może zwrócić prawdziwy status HTTP 301. Przy czysto statycznym buildzie Astro domyślnie generuje pliki HTML z meta refresh. To może działać dla użytkownika, ale nie jest idealne dla migracji SEO. Jeśli migrujesz widoczny blog, preferuj przekierowania na poziomie hostingu: _redirects, reguły Cloudflare, Netlify redirects albo konfigurację serwera.

Weryfikacja przekierowań

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. Wdrożenie testowe i weryfikacja

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

Checklist:

• 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. Przełączenie produkcji i monitoring

Dzień D oznacza zmianę DNS i przekierowanie ruchu na nową wersję strony. Rekomenduję:

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

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

Plan wycofania zmian

Jeśli coś pójdzie krytycznie źle, cofasz DNS do starego serwera i uruchamiasz WordPressa z kopii zapasowej. W praktyce, jeśli środowisko testowe przeszło pełną weryfikację, ryzyko katastrofy jest niskie.

Monitoring po przełączeniu: pierwsze 14 dni

Największe ryzyko migracji nie kończy się w momencie podmiany DNS. Przez pierwsze dwa tygodnie trzeba aktywnie obserwować, czy Google i użytkownicy trafiają w te same odpowiedniki treści.

• Codziennie sprawdzaj raport Strony w Google Search Console: 404, soft 404, Crawled - currently not indexed, 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 canonicale 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.

Co się dzieje z rankingami?

Realistyczne oczekiwania:

Tydzień 1-2: możliwe wahania widoczności. 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ć dłużej.

Miesiąc 2-3: jeśli przekierowania, canonicale i treść są poprawne, widoczność powinna się stabilizować. Lepsze Core Web Vitals mogą pomóc, ale nie kompensują utraty treści, złego mapowania URL-i ani błędów indeksacji.

Warunek: 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 są spełnione, migracja jest neutralna dla SEO albo dodatnia.

Kiedy NIE migrować

Uczciwie — migracja nie dla każdego.

• Jeśli treści edytuje zespół copywriterów bez dostępu do repo, a nie chcesz wprowadzać headless CMS — zostań na WordPressie.
• Jeśli strona ma ciężko zależne od WP wtyczki (zaawansowany e-commerce, multi-vendor marketplace, kompleksowy forum), migracja oznacza przepisanie tych funkcji od zera.
• Jeśli koszt migracji, czas programisty i ryzyko przekraczają potencjalne korzyści — zostań, gdzie jesteś. Nie każda strona potrzebuje Astro.

Podsumowanie

Migracja WordPress → Astro to konkretny, mierzalny projekt, który przy dobrym planie zajmuje 2-3 tygodnie i daje wymierne zyski w wydajności, SEO i kosztach. Kluczowe elementy to pełny eksport treści, staranne mapowanie URL-i z przekierowaniami 301, migracja obrazów do astro:assets i dokładne testy na środowisku testowym przed przełączeniem produkcji.

Jeśli rozważasz taką migrację i chcesz zrobić to bezpiecznie, bez utraty pozycji w Google, z pełną gwarancją jakości — skontaktuj się ze mną. Przeprowadziłem takich migracji kilkanaście, mogę ocenić Twój konkretny przypadek i zaproponować plan skrojony pod Twoje potrzeby.