Przekierowanie 301 w .htaccess: mapa URL, testy i rollback

Przekierowanie 301 informuje, że adres został przeniesiony na stałe. Poprawne wdrożenie to jednak nie tylko odpowiedź 301: stary URL powinien prowadzić do właściwego odpowiednika, bez pętli i zbędnych skoków, a końcowy adres musi działać. W tym tutorialu przechodzimy od mapy URL do testu HTTP, wdrożenia i rollbacku.

Szybka ścieżka: jeden stary adres → nowa strona

Jeżeli potrzebujesz jednego przekierowania, zacznij tutaj. Wariant wymaga potwierdzonego Apache 2.4 z mod_rewrite i obsługą .htaccess w katalogu głównym witryny. Jeśli masz tylko panel przekierowań hostingu, użyj instrukcji operatora dla tego panelu; nie dodawaj równolegle drugiej reguły w pliku. Brak dostępu do plików lub niepewność co do serwera oznacza, że ten fragment należy przekazać administratorowi, a nie wklejać w edytor treści WordPressa.

1. Najpierw otwórz nową stronę i potwierdź, że zastępuje starą. W poniższym przykładzie jest to /oferta.html. Zapisz stan starego i nowego adresu przed zmianą.
2. Przez SFTP lub menedżer plików ustal DocumentRoot domeny; włącz widoczność plików ukrytych. Pobierz istniejący .htaccess jako prywatną kopię na komputer, poza WWW. Nie zastępuj całego pliku przykładem.
3. Na stagingu dodaj poniższy fragment poza blokiem generowanym przez CMS i przed jego wewnętrznym przepisaniem do aplikacji. Podstaw zatwierdzony stary adres i własną stałą domenę HTTPS. Istniejące RewriteEngine On nie musi być dopisywane drugi raz.
4. Wykonaj GET opisany w sekcji 6: stary adres ma dać 301 i dokładny Location, a nowy 200 bez następnego przekierowania. Sprawdź wariant z ukośnikiem, UTM oraz adres, który nie powinien pasować, np. /stara-oferta-dodatkowa.
5. Dopiero po teście wdrażaj uzgodniony fragment na produkcji i powtórz kontrolę. Przy 500, pętli lub błędnym celu przywróć prywatną kopię w tej samej warstwie; sprawdź też cache. Pełna procedura odbioru i wycofania znajduje się w sekcjach 8–9.

RewriteEngine On
RewriteRule ^stara-oferta/?$ https://sklep.example/oferta.html [R=301,END]

Ten wariant zachowuje przychodzące parametry, w tym UTM. Nie obejmuje całej domeny ani /stara-oferta/podstrona. Jeśli migrujesz wiele adresów, identyfikatory typu ?p=123 lub zmieniasz politykę parametrów, przejdź przez mapę i testy poniżej. Nie rozszerzaj regexu na całą witrynę bez takiej mapy.

1. Ustal, gdzie działa przekierowanie

Ten kod dotyczy Apache 2.4 i pliku .htaccess w katalogu głównym witryny, czyli DocumentRoot. Nginx nie odczytuje .htaccess. Zgodności konkretnej instalacji LiteSpeed nie zakładamy na podstawie testu Apache. Zanim zmienisz plik, potwierdź serwer i warstwę obsługującą dany URL w panelu hostingu lub u administratora. Sam nagłówek Server może pochodzić z proxy i nie rozstrzyga tej kwestii.

• Sprawdź: CDN/proxy → serwer WWW → reguły aplikacji/CMS-a. Każda warstwa może dodawać własne 301. Zmiana .htaccess nie usunie przekierowania ustawionego wcześniej w CDN.
• Potwierdź aktywny mod_rewrite albo mod_alias oraz uprawnienia AllowOverride/AllowOverrideList. Nie włączaj globalnie AllowOverride All tylko po to, aby przykład zaczął działać.
• Zidentyfikuj reguły HTTPS, www, końcowego ukośnika, front controllera i katalogi z własnym .htaccess. Kod dla DocumentRoot nie jest gotową konfiguracją witryny w podkatalogu /sklep/.
• Jeśli masz dostęp do konfiguracji serwera, rozważ umieszczenie reguł właśnie tam; kontekst wzorców jest wtedy inny i wymaga osobnego testu. Jeśli zarządzasz tylko plikami hostingu, potwierdź obsługę .htaccess z operatorem.

Apache opisuje kontekst i ograniczenia pliku w dokumentacji .htaccess. W naszym laboratorium serwer dopuszczał tylko konkretne dyrektywy przekierowań, bez zmiany ustawień systemowego Apache.

2. Zbuduj mapę URL, zanim napiszesz regex

Połącz adresy z istniejącej sitemap, crawla, stron docelowych w GSC i analityce oraz istotnych linków przychodzących. Przechowaj źródło informacji i decyzję właściciela treści. Brak kliknięć w krótkim okresie nie oznacza automatycznie, że URL można usunąć. Mapa ma wyjaśniać, który nowy zasób faktycznie zastępuje stary; podobieństwo nazwy sluga nie wystarcza.

Dla każdego wiersza dopisz warianty HTTP/HTTPS i www/bez www, jeśli są obsługiwane, politykę parametrów, odbiorcę treści oraz kryterium sukcesu. W pliku testowym zachowuj wielkość liter i kodowanie ścieżek. Część po #, np. #cennik, nie jest wysyłana do serwera i nie może stanowić warunku RewriteRule. Nazwę pliku z kropką trzeba potraktować jako dokładny tekst, a nie dowolny znak regex.

Zasady mapowania, unikania nietrafnych przekierowań i aktualizacji sygnałów opisuje Google: migracja witryny ze zmianą URL.

3. Wybierz 301, 308 albo brak przekierowania

Google traktuje zarówno 301, jak i 308 jako przekierowania stałe i sygnał wyboru adresu kanonicznego. To nie gwarancja pozycji, indeksacji ani zachowania konkretnej liczby kliknięć. Źródło: Google Search Central: przekierowania i wyszukiwarka.

W eksperymencie curl po 301 zmienił POST na GET i nie przesłał body; po 308 zachował POST oraz syntetyczne body. Nie używaliśmy opcji -X POST ani --post301, które zmieniłyby warunki testu. HTTP dopuszcza zmianę POST na GET przy 301, natomiast 308 zachowuje metodę. Sprawdź RFC 9110: 301 i 308. Nie testuj tego przez wysyłanie zamówień lub prawdziwych formularzy na produkcji.

4. Redirect czy RewriteRule? Różnica ma znaczenie

Dla prostych map bez warunków query string wystarcza mod_alias. Uważaj jednak: Redirect operuje na prefiksie pełnych segmentów ścieżki. Reguła dla /alias-prefix obejmuje też /alias-prefix/child i dołącza końcówkę do celu. Nie obejmuje /alias-prefix-other. Jeśli chcesz pojedynczy adres, użyj zakotwiczonego RedirectMatch albo dokładnego RewriteRule.

# Prefiks: obejmuje także /alias-prefix/child.
Redirect 301 /alias-prefix https://sklep.example/nowy-prefix

# Dokładna ścieżka, z opcjonalnym końcowym ukośnikiem.
RedirectMatch 301 ^/alias-exact/?$ https://sklep.example/oferta.html

W obrębie tej samej konfiguracji mod_alias pierwsze pasujące przekierowanie ma pierwszeństwo, więc wyjątki zapisuj przed szerokimi regułami. Nie zakładaj jednak, że samo przeniesienie linii mod_alias nad mod_rewrite rozstrzygnie kolejność między modułami. Dla tej samej grupy adresów stosuj jeden mechanizm i sprawdź rzeczywistą odpowiedź. Źródło: Apache mod_alias: kolejność, Redirect i RedirectMatch.

5. Dokładna mapa w mod_rewrite i obsługa parametrów

Poniższy blok jest fragmentem reguł, nie zamiennikiem całego pliku .htaccess. Domena sklep.example jest celowo przykładowa. Wstaw własny, stały adres kanoniczny oraz zatwierdzoną mapę. Zachowaj istniejące zabezpieczenia i konfigurację hostingu. W typowym układzie z front controllerem własne przekierowania muszą zostać rozpatrzone przed wewnętrznym przepisaniem do aplikacji; ustal to w swojej konfiguracji i nie edytuj sekcji automatycznie nadpisywanej przez CMS.

# Apache 2.4, .htaccess w DocumentRoot, stała domena bez końcowego /.
# Podstaw WŁASNĄ domenę i ZATWIERDZONĄ mapę. To nie cały plik CMS-a.
RewriteEngine On

RewriteCond %{QUERY_STRING} ^p=123$
RewriteRule ^index\.php$ https://sklep.example/poradnik.html [R=301,END,QSD]

RewriteRule ^stara-oferta/?$ https://sklep.example/oferta.html [R=301,END]
RewriteRule ^stary-poradnik\.html$ https://sklep.example/poradnik.html [R=301,END]
RewriteRule ^stare-zażółć$ https://sklep.example/poradnik.html [R=301,END]

RewriteRule ^stara-kampania$ https://sklep.example/oferta.html [R=301,END,QSD]
RewriteRule ^stary-filtr$ https://sklep.example/oferta.html?kolor=czarny [R=301,END]
RewriteRule ^stary-filtr-qsa$ https://sklep.example/oferta.html?kolor=czarny [R=301,END,QSA]

# Tylko ten konkretny zasób usunięto bez odpowiednika.
RewriteRule ^wycofane-bez-zamiennika$ - [G,END]

• W .htaccess wzorzec RewriteRule nie zaczyna się od /. Apache usuwa prefiks katalogu przed dopasowaniem. Cel może być pełnym URL-em. W teście błędne ^/stara-oferta$ nie pasowało i zwracało 404.
• ^ i $ ograniczają dopasowanie. /? dopuszcza tylko opcjonalny końcowy ukośnik. Bez tych ograniczeń łatwo objąć dodatkowe adresy. Nie dodawaj [NC] bez decyzji, czy wielkość liter rzeczywiście ma być ignorowana.
• Query string nie jest częścią wzorca RewriteRule. Dokładny warunek ^p=123$ pasuje tylko do takiej postaci parametrów. Wariant p=123&utm_source=test celowo NIE pasuje — w naszym statycznym teście zwracał 404. W prawdziwym CMS-ie może obsłużyć go aplikacja; jeśli ma migrować, dopisz jawną politykę i kolejne testy zamiast zakładać zgodność.
• R=301 wskazuje kod wprost. Samo R oznacza domyślnie 302. END kończy przetwarzanie mod_rewrite dla bieżącego żądania w kontekście katalogowym; nie zapobiega kolejnemu żądaniu klienta, więc nie naprawia pętli A → B → A.
• Cel jest stały: nie korzystamy z %{HTTP_HOST}, dowolnego parametru next ani backreference tworzącego domenę. Reguły nie mogą stać się otwartym przekierowaniem na obcy serwis.

QSD usuwa także parametry mające znaczenie dla aplikacji lub analityki: nie dodawaj go globalnie. QSA może z kolei utworzyć powtarzające się klucze, których interpretacja zależy od aplikacji. Testuj osobno parametry kampanii, identyfikatory treści i filtry. Nie przenoś tokenów logowania do nowego publicznego URL-a. W przykładzie z polskimi znakami żądanie zawierało kodowanie procentowe, a wzorzec dopasował zdekodowaną ścieżkę; dowolne backreference i złożone kodowanie wymagają odrębnych testów.

Podstawy: Apache mod_rewrite: kontekst katalogowy i zmienne oraz flagi R, END, QSD i QSA.

6. Sprawdź HTTP: sam końcowy status 200 nie wystarczy

# Terminal na Twoim komputerze. Podstaw własny publiczny URL HTTPS.
redirect_url='https://sklep.example/stara-oferta?utm_source=test'

# 1. Rzeczywisty GET: status i Location pierwszej odpowiedzi, bez podążania.
curl --silent --show-error --globoff --connect-timeout 5 --max-time 15 \
  --proto '=https' --dump-header - --output /dev/null "$redirect_url"

# 2. Dopiero po sprawdzeniu domeny w Location: docelowy status i liczba skoków.
curl --silent --show-error --globoff --location --max-redirs 5 \
  --connect-timeout 5 --max-time 20 \
  --proto '=https' --proto-redir '=https' --output /dev/null \
  --write-out 'status=%{http_code}\nredirects=%{num_redirects}\nurl=%{url_effective}\n' \
  "$redirect_url"

Nie zastępuj pierwszego testu samym curl -I: to metoda HEAD, której obsługa może różnić się od GET. Nie dodajemy --fail, bo 404 i 410 są poprawnymi oczekiwanymi wynikami niektórych wierszy mapy. Dla pętli curl z ograniczeniem liczby przekierowań zakończy się błędem; w naszym teście było to wyjście 47 po trzech skokach. Nie usuwaj limitu, aby wymusić zielony wynik.

Przy większej mapie użyj check-map.py z paczki. Dla każdego źródła sprawdza oczekiwany status i dokładny Location, a potem pobiera osobno zatwierdzony cel. Jeśli cel również przekierowuje, test nie przechodzi. Skrypt nie podąża za niesprawdzonym adresem z nagłówka Location i nie wysyła danych autoryzacji. Wersja z paczki dotyczy mapy w obrębie jednego originu, nie migracji między domenami.

[
  {"source":"/stara-oferta","status":301,"target":"/oferta.html"},
  {"source":"/stara-oferta?utm_source=test","status":301,"target":"/oferta.html?utm_source=test"},
  {"source":"/oferta.html","status":200},
  {"source":"/stara-oferta-dodatkowa","status":404}
]

python3 check-map.py --origin 'https://sklep.example' --map moja-mapa.json --delay 1

Najpierw dry-run: wykryj konflikt mapy bez HTTP

python3 check-map.py --origin 'https://sklep.example' --map moja-mapa.json --dry-run

Dry-run odrzuca brak celu, powtórzone źródła (również identyczne), przekierowanie na siebie, cykl A → B → A, łańcuch do kolejnego przekierowania oraz cel, który ta sama mapa opisuje jako 404/410. Walidacja działa też przed każdym testem HTTP. Dokładne warianty query string są oddzielnymi wierszami; automat nie zgaduje równoważności parametrów, kodowania, wielkości liter lub treści. Cel niewystępujący jako źródło w mapie wymaga późniejszego GET — samo poprawne parsowanie JSON nie potwierdza jego istnienia.

7. Odtwórz nasze testy, w tym celowo błędne reguły

Rozpakuj pobrany ZIP do nowego katalogu na własnym komputerze, poza katalogiem jakiejkolwiek strony. Przejrzyj README i kod. Na macOS z natywnym /usr/sbin/httpd, dostępnymi modułami Apache, Pythonem 3 i curl uruchom poniższe polecenie jako zwykły użytkownik. Nie używaj sudo. Skrypt tworzy własny katalog tymczasowy, uruchamia odseparowany Apache na losowym wysokim porcie 127.0.0.1 i po teście zatrzymuje wyłącznie własny proces.

python3 run-lab.py

python3 test-seo-checks.py

PASS przy scenariuszu bad-* oznacza, że test poprawnie odtworzył i wykrył oczekiwany błąd. Nie oznacza dopuszczenia tej konfiguracji do publikacji. Nie uruchamiaj całej paczki na serwerze swojej strony. Laboratoryjny HTTP nie zastępuje testu certyfikatu, CDN ani wariantów produkcyjnej domeny.

Osobny test: reguła przed blokiem WordPressa

Na WordPress 7.1 z Apache 2.4.68 wykonaliśmy dodatkową próbę przez lokalną bramę Nginx. Utworzyliśmy jedną własną stronę testową i sprawdziliśmy jej treść oraz canonical. Reguła umieszczona przed istniejącym front controllerem WordPressa zwracała 301 → właściwa strona 200 dla starego URL-a, końcowego ukośnika i parametru UTM. Sąsiedni, nieobjęty wzorcem adres pozostał 404. Ta sama reguła dopisana za blokiem CMS-a nie obsłużyła starego URL-a — otrzymaliśmy 404. Po poprawieniu kolejności wróciło 301.

Wynik: 12 kontroli integracji oraz 2 kontrole wycofania. Przywrócono dokładną zawartość wcześniejszego .htaccess i usunięto wyłącznie własną stronę testową; zbiór wcześniejszych identyfikatorów stron pozostał bez zmian. To dowód jednego scenariusza kolejności z działającym CMS-em, nie gwarancja zachowania każdej wtyczki przekierowań, konfiguracji multisite lub proxy.

Aby odtworzyć opcjonalny test, najpierw przygotuj i ukończ izolowane laboratorium source/restore z poradnika kopii i odtwarzania WordPress. Następnie użyj test-wordpress.mjs z tego ZIP-a, przekazując ścieżkę do folderu z compose.yaml. Szczegóły i warunki wyłącznego dostępu opisuje README. Nie przekazuj ścieżki swojego projektu produkcyjnego.

8. Wdrożenie i rollback: przygotuj je przed zmianą

1. Zapisz aktualny .htaccess i inne zmieniane ustawienia w wersjonowanej kopii poza publicznym katalogiem strony. Jeśli pracujesz przez SFTP, pobierz plik lokalnie i sprawdź jego zawartość. Nie przechowuj kopii .htaccess.bak ani plików konfiguracyjnych do pobrania z WWW.
2. Zachowaj wyniki bazowe: źródła i cele z mapy, działanie strony głównej, formularzy oraz kluczowych ścieżek aplikacji. Dla funkcji zapisujących dane stosuj testowe środowisko i dane; nie odtwarzaj prawdziwych zamówień.
3. Przygotuj poprawkę jako mały diff istniejącego pliku. Nie usuwaj przy okazji reguł zabezpieczeń, obsługi aplikacji, cache ani konfiguracji operatora. Ustal też, czy CMS nie nadpisze Twojego bloku.
4. Odtwórz reguły i pełną mapę na stagingu odpowiadającym konfiguracji produkcyjnej. Sprawdź GET oraz log błędów. Jeżeli zmieniasz konfigurację główną serwera, sprawdź jej składnię zgodnie z procedurą operatora; test .htaccess nadal wymaga żądania HTTP.
5. Wgraj uzgodnioną zmianę w oknie z dostępnym rollbackiem. Sposób bezpiecznej podmiany pliku ustal z hostingiem. Konfiguracja .htaccess jest odczytywana przy żądaniach, więc jej edycja nie jest powodem do globalnego restartu Apache.
6. Natychmiast wykonaj własną mapę i testy stron, które miały pozostać bez zmian. Sprawdź HTTP/HTTPS, www/bez www, slash, parametry i kodowanie. Wyeliminuj łańcuchy także między CDN, serwerem i aplikacją: stary adres powinien kierować od razu do docelowej kanonicznej wersji.
7. Przy 500, pętli, obcym Location, błędnym celu lub uszkodzeniu aplikacji przywróć zatwierdzoną kopię oraz inne zmienione reguły w tej samej warstwie. Powtórz baseline i testy funkcjonalne. Nie rozwiązuj błędu przez wyłączenie zabezpieczeń ani przekierowanie całej domeny na homepage.

301 i 308 mogą być przechowywane w cache. Przywrócenie pliku na serwerze nie cofa natychmiast odpowiedzi zapisanej wcześniej w przeglądarce lub CDN. Dlatego po rollbacku porównaj świeży odczyt curl z przeglądarką i w razie potrzeby usuń właściwe wpisy cache zgodnie z instrukcją operatora. Nie twórz odwrotnego przekierowania B → A w ciemno, bo klient z zapamiętanym A → B może wejść w pętlę. Podstawa: RFC 9110: statusy i cache.

9. Po 301 sprawdź canonical, linki i Google Search Console

Nie oceniaj nowego adresu wyłącznie po HTTP 200. W pakiecie dodaliśmy check-destinations.py: odczytuje dokładnie wskazane strony, sprawdza canonical w head, meta robots/googlebot i nagłówki X-Robots-Tag, tytuł, H1 oraz zatwierdzone frazy treści. To własny profil odbioru statycznego HTML, nie implementacja algorytmu Google ani automatyczna ocena jakości. Dobierz wymagane fragmenty tak, aby odróżniały właściwą ofertę od homepage lub komunikatu błędu.

[
  {
    "path": "/oferta.html",
    "canonical": "https://sklep.example/oferta.html",
    "titleContains": "Integracja magazynu",
    "h1Contains": "Integracja magazynu",
    "requiredText": ["Synchronizacja stanów", "Obsługiwane systemy"]
  }
]

python3 check-destinations.py --origin 'https://sklep.example' --manifest cele-seo.json

Ten ścisły wariant wymaga jednego absolutnego canonicala w HTML head w tym samym originie, jednego H1 i jawnie wskazanej treści. Odrzuca noindex/none dla Googlebota oraz łańcuch. HTTP Link canonical, element base i unavailable_after kieruje do osobnego przeglądu zamiast zgadywać wynik. Czyta do 1 MiB HTML; większa odpowiedź nie otrzyma częściowego PASS. Nie renderuje JS, nie ocenia widoczności CSS i nie interpretuje robots.txt. Zgodność kilku fraz nie dowodzi równoważności całej treści — tę decyzję nadal zatwierdza właściciel mapy.

Kryteria odbioru opieramy na dokumentacji Google: canonical i meta robots oraz X-Robots-Tag. Zestaw 47 testów obejmuje również celowo zły canonical, blokadę indeksacji w nagłówku, duplikat H1, treść obecną tylko w skrypcie, limit rozmiaru odpowiedzi i brak podążania do obcej domeny.

• Nowy adres zwraca 200 i odpowiednią treść. Jeśli ma wejść do indeksu, nie jest blokowany przez przypadkowe noindex ani robots.txt. Canonical wskazuje nowy właściwy adres, a nie starą wersję.
• Linki wewnętrzne oraz hreflang, jeśli występuje, prowadzą bezpośrednio do nowych adresów. Nie zostawiaj nawigacji i kart produktów opartych na stałych 301.
• Sitemap zawiera aktualne adresy kanoniczne, a nie przekierowania i błędy. Prześlij aktualną mapę w GSC. Przy większej migracji zachowaj listę starych adresów do monitoringu poza publiczną sitemap.
• W Inspekcji URL sprawdź reprezentatywne źródła i cele. Test aktualnego URL-a mówi o pobraniu w danym momencie; raport indeksu i wybrany przez Google canonical mogą odzwierciedlać wcześniejszy crawl. Sam 301 nie potwierdza zakończenia migracji.
• Monitoruj błędy przekierowań, 404/5xx i logi po wdrożeniu; porównuj widoczność starego i nowego zestawu adresów, a nie tylko pojedyncze strony. Datę wdrożenia zaznacz w swojej dokumentacji pomiaru. Reaguj od razu na błąd techniczny, ale nie zmieniaj mapy codziennie na podstawie pojedynczego dnia ruchu.

Google zaleca utrzymywać przekierowania możliwie długo, zwykle co najmniej rok; dla użytkowników starych linków mogą być potrzebne bezterminowo. Jednocześnie warto aktualizować własne linki oraz ważne odsyłacze zewnętrzne, aby nie opierały się na dodatkowym skoku. Źródło: Google: wdrożenie i monitoring migracji URL.

Jeżeli po migracji adres końcowy działa, ale ma błędny canonical lub noindex, kolejny krok to diagnostyka HTML. Pokazujemy ją na przykładzie sklepu w poradniku technicznego SEO PrestaShop. Przy zmianie struktury całej witryny zakres mapy i odbioru możesz uzgodnić w ramach wdrożenia technicznego SEO.