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

Migracja przy rozsądnym planie zamyka się w 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 realnie wygrywasz na Astro

Migracja dla samej migracji to marnotrawstwo czasu, 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 dodatkowej wtyczki. To konsekwencja przemyślanej 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, szczególnie polem do popisu są wtyczki. 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 — to wszystko 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 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ż — lepsza opcja — użyć skryptu 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()

Po wyrenderowaniu przez WP REST API zwraca treść w HTML. Jest to z jednej strony zaleta, ponieważ dostajesz finalną zawartość, a z drugiej 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 i ma wszystko: 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 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, 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 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 przy transformacji

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

To 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 serwerowym (output: 'server' lub trasa z prerender = false) Astro bez problemu zwróci prawidłowy status HTTP 301. Pułapka czai się w czysto statycznym buildzie, 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 ruchem organicznym nie ma miejsca na kompromisy: jedynym słusznym rozwiązaniem są przekierowania na poziomie hostingu — przez plik _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), 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.

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.