Jak ręcznie edytować .htaccess

Plik .htaccess to podręczne centrum sterowania dla serwera Apache w danym katalogu. Pozwala wdrażać przekierowania, ochronę zasobów, nagłówki i optymalizacje bez dostępu do konfiguracji globalnej. Instrukcja poniżej przeprowadzi Cię krok po kroku: od bezpiecznego przygotowania, przez edycję, po diagnostykę i przykłady. Dzięki niej zrozumiesz, co robisz i jak szybko cofnąć zmiany, gdy coś pójdzie nie tak, tak aby Twoja strona pozostała dostępna i szybka.

Przygotowanie do edycji pliku

Czym jest i gdzie go znaleźć

Plik .htaccess jest interpretowany przez Apache przy każdym żądaniu dotyczącym katalogu, w którym się znajduje, oraz jego podkatalogów. To plik ukryty (kropka na początku nazwy), więc w menedżerze plików lub kliencie FTP włącz wyświetlanie ukrytych plików. Standardowo leży w katalogu głównym aplikacji (np. public_html, public, htdocs), ale może też występować głębiej, jeśli chcesz nadawać reguły tylko dla części witryny.

Najczęstsze lokalizacje:

• hosting współdzielony: /public_html/.htaccess
• frameworki: /public/.htaccess lub /web/.htaccess
• podkatalogi z inną polityką: /assets/.htaccess, /private/.htaccess

Ważne: reguły z katalogu podrzędnego mogą nadpisać reguły z katalogu nadrzędnego, jeśli dyrektywy AllowOverride na to pozwalają.

Kopia bezpieczeństwa i przywracanie

Zanim cokolwiek zmienisz, wykonaj kopia i zapisz ją obok, np. .htaccess.bak-2025-12-20. Przywrócenie polega na podmianie plików: usuń wadliwy i zamień na zapasowa. Dobrą praktyką jest trzymanie ostatnich kilku wersji oraz wpisywanie krótkiego dziennika zmian (co, kiedy, po co). Dzięki temu minimalizujesz czas niedostępności, jeśli pojawi się błąd 500 Internal Server Error.

Uprawnienia i edytor

Ustaw odpowiednie uprawnienia pliku: zwykle 644 (właściciel: zapis/odczyt; grupa i inni: odczyt). Katalogi zwykle mają 755. Edytuj zwykłym edytorem tekstu w trybie UTF‑8 bez BOM. Unikaj znaków końca linii typu CRLF na serwerach Linux (najlepiej LF). Nie kopiuj z edytorów, które wstawiają nietypowe cudzysłowy czy znaki niedrukowalne.

Zasady działania i priorytety

Apache przetwarza dyrektywy od góry do dołu. Komentarze zaczynają się znakiem #. W .htaccess możesz używać sekcji dla konkretnych plików (Files, FilesMatch), katalogów (Directory w .htaccess nie działa), typów MIME, nagłówków i mechanizmu przepisywania URL-i. Część dyrektyw zależy od modułów (np. rewrite, headers). Jeśli moduł nie jest włączony w konfiguracji serwera, dyrektywy mogą być ignorowane lub wywołać błąd 500.

Wpływ na wydajność

Każde żądanie powoduje wielokrotne sprawdzanie .htaccess w drzewie katalogów. Dlatego trzymaj plik możliwie krótki, dobrze skomentowany i zgrupuj reguły. Gdy masz dostęp do konfiguracji globalnej (httpd.conf), lepiej przenieść stałe reguły tam i wyłączyć AllowOverride dla maksymalnej wydajności.

Bezpieczna procedura edycji — krok po kroku

Środowisko testowe i plan

Najpierw zaplanuj zmiany i sprawdź je lokalnie lub na środowisku testowym. Jeżeli nie masz stagingu, zastosuj okno serwisowe o niskim ruchu. Przygotuj listę adresów do testów: strona główna, podstrona, zasób statyczny, logowanie, API, plik do pobrania.

• Włącz wyświetlanie ukrytych plików w FTP.
• Pobierz .htaccess i wykonaj lokalną kopię.
• Opracuj minimalny zestaw zmian, które wprowadzasz w jednym wdrożeniu.
• Po wdrożeniu testuj wszystkie ścieżki krytyczne aplikacji.

Dodawanie reguł — małymi krokami

Wprowadzaj jedną grupę reguł naraz, np. najpierw przekierowania, później nagłówki, na końcu zabezpieczenia. Po każdej grupie testuj. Komentuj reguły: kiedy wprowadzone, po co, kto zatwierdził. Przykład komentarza: # 2025‑12‑20: wymuszenie HTTPS dla całej domeny, J.Kowalski.

Walidacja i logi

Po wdrożeniu sprawdź:

• konsolę przeglądarki (zakładka Network: statusy, przekierowania, nagłówki),
• logi serwera: error.log i access.log,
• czy pliki statyczne (CSS/JS/obrazki) ładują się bez błędów CORS i MIME,
• czy mapy witryny i robots.txt są dostępne,
• czy generujesz jedną wersję adresów (www lub bez www),
• czy nie tworzysz pętli przekierowań.

W razie błędu 500 natychmiast przywróć kopię, a następnie metodycznie zawężaj problem (binary search: wyłącz połowę nowych reguł i sprawdź, która część powoduje błąd).

Najczęstsze zastosowania i gotowe przepisy

Przekierowania 301/302

Do prostych przekierowań katalogów i plików służy dyrektywa Redirect (mod_alias):

• Redirect 301 /stary-katalog/ https://example.com/nowy-katalog/
• Redirect 302 /promo https://example.com/wyprzedaz
• RedirectMatch 301 ^/old/(.*)$ https://example.com/new/$1

Gdy potrzebujesz większej kontroli, użyj mechanizmu mod_rewrite i reguły RewriteRule:

• RewriteEngine On
• RewriteCond %{REQUEST_FILENAME} !-f
• RewriteCond %{REQUEST_FILENAME} !-d
• RewriteRule ^produkt/(.*)$ /sklep/produkt.php?id=$1 [L,QSA]

Wyjaśnienie parametrów:

• L — Last (zatrzymuje dalsze reguły)
• QSA — Query String Append (dokleja parametry zapytania)
• R=301/302 — rodzaj przekierowania (pamiętaj, że 301 cache’uje się agresywnie po stronie przeglądarki)
• NC — NoCase (bez rozróżniania wielkości liter)

Kanoniczna wersja domeny i wymuszenie HTTPS

Konsekwentna kanonizacja zapobiega duplikacji treści i mieszanemu kontentowi. Wymuszając HTTPS, zabezpieczasz ruch i korzystasz z HTTP/2.

• RewriteEngine On
• RewriteCond %{HTTPS} !=on
• RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
• RewriteCond %{HTTP_HOST} ^www.example.com$ [NC]
• RewriteRule ^ https://example.com%{REQUEST_URI} [L,R=301]

Pamiętaj, aby testować na subdomenach i ścieżkach. Jeśli masz WordPress lub inny CMS, który sam zarządza przekierowaniami, unikaj podwójnych reguł. W przypadku reverse proxy/Load Balancera wymuś respektowanie nagłówka X-Forwarded-Proto lub użyj warunków opartych o %{ENV:HTTPS} zgodnie z konfiguracją serwera.

Strony błędów i twarde blokady

Własne strony błędów poprawiają UX i SEO:

• ErrorDocument 404 /404.html
• ErrorDocument 403 /403.html
• ErrorDocument 500 /500.html

Blokady podstawowe (IP, user-agent):

• Require all granted — domyślnie zezwól (Apache 2.4)
• <RequireAll> Require not ip 203.0.113.0/24 </RequireAll>
• BrowserMatchNoCase „badbot” bad_bot
• Order Allow,Deny — starsza składnia Apache 2.2 (unikaj w nowych instalacjach)

Zablokuj bezpośredni dostęp do plików konfiguracyjnych i wrażliwych:

• <Files .env> Require all denied </Files>
• <FilesMatch „.(ini|log|bak|sql)$”> Require all denied </FilesMatch>

Ochrona katalogów i indeksowanie

Jeśli nie chcesz listowania plików w katalogu:

• Options -Indexes

Wymuś plik indeksu:

• DirectoryIndex index.php index.html

Chroń katalog hasłem (HTTP Basic). W .htaccess:

• AuthType Basic
• AuthName Strefa prywatna
• AuthUserFile /ścieżka/.htpasswd
• Require valid-user

Plik .htpasswd generuj narzędziem htpasswd (bcrypt lub apr1). Upewnij się, że .htpasswd nie jest dostępny przez WWW.

Parametry PHP, limity i upload

Na hostingu współdzielonym często możesz nadawać dyrektywy PHP:

• php_value memory_limit 256M
• php_value upload_max_filesize 64M
• php_value post_max_size 64M
• php_flag display_errors Off

Uwaga: to działa tylko przy PHP jako moduł Apache. Dla PHP-FPM użyj pliku .user.ini lub konfiguracji serwera. W logach sprawdzisz, czy dyrektywa została zaakceptowana.

Przepisy dla SPA i API

Obsługa pojedynczego punktu wejścia (SPA):

• RewriteEngine On
• RewriteCond %{REQUEST_FILENAME} !-f
• RewriteCond %{REQUEST_FILENAME} !-d
• RewriteRule . /index.html [L]

API i wymuszenie metody:

• <LocationMatch „^/api/”> LimitExcept GET POST OPTIONS Require all denied </LocationMatch>

Optymalizacja wydajności i bezpieczeństwa nagłówkami

Kompresja treści

Włącz kompresja gzip lub brotli (wymaga mod_deflate lub mod_brotli):

• AddOutputFilterByType DEFLATE text/html text/plain text/css application/javascript application/json image/svg+xml
• # lub BrotliCompressionQuality 5; BrotliEnable on

Testuj w DevTools (content-encoding: gzip/br). Unikaj podwójnej kompresji po reverse proxy.

Cache-Control i wersjonowanie

Długie keszowanie plików statycznych przyspiesza ładowanie. Słowo cache kojarzy się z pojemnikiem pamięci — ustaw nagłówki i wersjonuj pliki (cache busting):

• <FilesMatch „.(css|js|gif|jpg|jpeg|png|svg|webp|woff2?)$”> Header set Cache-Control „public, max-age=31536000, immutable” </FilesMatch>
• ExpiresActive On
• ExpiresByType text/css „access plus 1 year”
• FileETag None

Jeśli nie wersjonujesz nazw, skróć max-age (np. 7 dni), by móc szybciej publikować poprawki.

Bezpieczne nagłówki

Ustaw istotne nagłówki bezpieczeństwa (mod_headers):

• Header always set X-Frame-Options „SAMEORIGIN”
• Header always set X-Content-Type-Options „nosniff”
• Header always set Referrer-Policy „strict-origin-when-cross-origin”
• Header always set Permissions-Policy „geolocation=(), microphone=()”
• Header always set Content-Security-Policy „default-src 'self’; img-src 'self’ data:; script-src 'self’ 'unsafe-inline’ 'unsafe-eval’; style-src 'self’ 'unsafe-inline'”
• Header always set Strict-Transport-Security „max-age=31536000; includeSubDomains; preload”

HSTS działa tylko po HTTPS; upewnij się, że wszystkie subdomeny obsługują TLS, zanim dodasz includeSubDomains i wpis do preload.

CORS i typy MIME

Udostępnianie zasobów między domenami (CORS):

• <LocationMatch „^/api/”> Header always set Access-Control-Allow-Origin „https://app.example.com” Header always set Access-Control-Allow-Methods „GET, POST, OPTIONS” Header always set Access-Control-Allow-Headers „Content-Type, Authorization” </LocationMatch>

Prawidłowe typy MIME:

• AddType text/javascript js
• AddType text/css css
• AddType image/svg+xml svg
• AddType font/woff2 woff2

Preload, preconnect i priorytety

Możesz wskazać krytyczne zasoby przeglądarce:

• Header add Link „<https://cdn.example.com/fonts.woff2>; rel=preload; as=font; type=font/woff2; crossorigin”
• Header add Link „<https://cdn.example.com>; rel=preconnect; crossorigin”

Dbaj o spójność z polityką CORS i CSP dla preloadowanych zasobów.

Diagnostyka i rozwiązywanie problemów

Najczęstsze błędy składni

Błąd 500 po edycji .htaccess to zwykle literówka: brak nawiasu, niezamknięty cudzysłów, nieznana dyrektywa, reguła w złej kolejności lub użycie opcji niedostępnej w .htaccess. Sprawdź error.log: wskaże linię i moduł. Oto kilka typowych potknięć:

• RewriteEngine Off przed RewriteRule (wyłączona przepisywarka)
• Przeładowanie pętli: przekierowanie na ten sam adres bez warunku
• Nadmierny NC — łapie zbyt szeroko
• Brak escapingu kropek lub znaków specjalnych w regexie (np. . zamiast .)

Konflikty z aplikacjami i modułami

CMS-y (np. WordPress) generują własne bloki w .htaccess. Umieszczaj swoje reguły nad lub pod blokiem zależnie od celu. Jeżeli korzystasz z frameworka, który sam odpowiada za routing (Laravel, Symfony), to reguła front controller (RewriteRule ^ index.php [L]) powinna pozostać ostatnia w grupie, a warunki wyjątków dodać nad nią.

Moduły: jeśli polegasz na headers, rewrite czy brotli, upewnij się, że hosting je udostępnia. W przeciwnym razie część reguł będzie ignorowana. W trybie proxy/Cloudflare niektóre nagłówki mogą być nadpisane; porównuj response na porcie origin i po CDN.

Narzędzia testowe

Przydadzą się:

• curl -I https://example.com — podgląd statusu i nagłówków
• curl -ILs -o /dev/null -w „%{url_effective} %{http_code}n” URL — śledzenie przekierowań
• DevTools: zakładka Network, Security, Coverage
• analityka serwerowa: GoAccess, AWStats
• skanery nagłówków: securityheaders.com
• PageSpeed Insights / Lighthouse: wpływ cache i kompresji

Checklisty przed publikacją

• Przekierowania: brak pętli, jedno hop, kody 301/302 zgodne z celem.
• Kanonizacja: dokładnie jedna wersja domeny i protokołu.
• Pliki statyczne: kompresja i długi cache ze strategią wersjonowania.
• Bezpieczeństwo: CSP, X-Frame-Options, X-Content-Type-Options, HSTS po TLS.
• Blokady: brak fałszywych pozytywów dla realnych użytkowników i botów indeksujących.
• Logi: brak nowych błędów 4xx/5xx, spadek TTFB nie nastąpił.
• Rollback: gotowa kopia i plan przywracania.

Przykładowy szablon .htaccess do adaptacji

Struktura z komentarzami

Poniżej przykład, który możesz skopiować i dostosować (zastąp example.com i dopasuj ścieżki):

• # 1) Podstawy
• Options -Indexes
• DirectoryIndex index.php index.html
• # 2) Routing
• RewriteEngine On
• RewriteCond %{REQUEST_FILENAME} !-f
• RewriteCond %{REQUEST_FILENAME} !-d
• RewriteRule ^ index.php [L]
• # 3) HTTPS i kanonizacja
• RewriteCond %{HTTPS} !=on
• RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
• RewriteCond %{HTTP_HOST} ^www.example.com$ [NC]
• RewriteRule ^ https://example.com%{REQUEST_URI} [L,R=301]
• # 4) Bezpieczeństwo plików
• <FilesMatch „.(env|ini|log|bak|sql)$”> Require all denied </FilesMatch>
• # 5) Nagłówki bezpieczeństwa
• Header always set X-Frame-Options „SAMEORIGIN”
• Header always set X-Content-Type-Options „nosniff”
• Header always set Referrer-Policy „strict-origin-when-cross-origin”
• # 6) Kompresja i cache
• AddOutputFilterByType DEFLATE text/html text/css application/javascript application/json image/svg+xml
• <FilesMatch „.(css|js|gif|jpg|jpeg|png|svg|webp|woff2?)$”> Header set Cache-Control „public, max-age=31536000, immutable” </FilesMatch>
• # 7) Strony błędów
• ErrorDocument 404 /404.html
• ErrorDocument 500 /500.html

Warianty i wskazówki

• Do testów używaj R=302 zamiast 301, aby uniknąć twardego keszowania przez przeglądarkę.
• Dla wielojęzycznych witryn filtruj ścieżki w RewriteCond, by nie łapać zasobów statycznych.
• Jeśli korzystasz z CDN, pozwól mu serwować pliki statyczne, a .htaccess skup na aplikacji i bezpieczeństwie.
• Trzymaj reguły pokrewne razem i poprzedzaj sekcje komentarzami z datą.

Praktyczne scenariusze i receptury

Przenosiny treści i czyszczenie starych linków

Masowa migracja URL-i:

• RewriteMap redirmap txt:/ścieżka/mapa.txt — wymaga dostępu do httpd.conf (na hostingu współdzielonym zwykle niedostępne)
• Alternatywa: kilkadziesiąt reguł Redirect 301 lub RewriteRule z grupami dopasowania

Twórz wzorce: ^kategoria/([0-9]{4})/([0-9]{2})/(.*)$ → /nowa/$1/$3 i uważaj na kolejność (bardziej szczegółowe nad ogólnymi).

Mikrousługi i podpięte aplikacje

Gdy część ruchu obsługuje zewnętrzne API lub inna aplikacja w subkatalogu, rozgranicz ruch:

• RewriteRule ^api/v2/(.*)$ http://localhost:8080/$1 [P,L] — wymaga mod_proxy i ProxyPassReverse w konfiguracji serwera
• RewriteRule ^app/(.*)$ /app/public/$1 [L] — prosty alias do podkatalogu

Ochrona przed hotlinkowaniem

Zablokuj osadzanie Twoich obrazków na zewnętrznych stronach, zachowując dostęp dla własnej domeny i wyszukiwarek:

• RewriteEngine On
• RewriteCond %{HTTP_REFERER} !^$
• RewriteCond %{HTTP_REFERER} !example.com [NC]
• RewriteRule .(jpe?g|png|gif|webp)$ – [F,NC,L]

SEO i porządkowanie adresów

Ujednolicenie ukośników i trailing slash:

• RewriteCond %{REQUEST_FILENAME} !-f
• RewriteCond %{REQUEST_URI} !.[a-zA-Z0-9]{2,5}$
• RewriteRule ^(.+[^/])$ https://example.com/$1/ [R=301,L]

Usunięcie index.php z adresu:

• RewriteCond %{THE_REQUEST} s/+index.php[s?]
• RewriteRule ^index.php$ / [R=301,L]
• RewriteRule ^(.*)$ index.php [L]

Poznaj ograniczenia i dobre praktyki

Co może, a czego nie może .htaccess

.htaccess nie włączy modułów — to musi zrobić administrator w konfiguracji globalnej. Część dyrektyw działa tylko tam (RewriteMap, ProxyPass, VirtualHost). W środowiskach z Nginx .htaccess jest ignorowany; tam potrzeba edycji nginx.conf. Na Apache .htaccess działa tylko, gdy AllowOverride nie jest na None.

Porządek i dokumentacja

Utrzymuj jednolity styl: sekcje z nagłówkami komentarzy, każda reguła opisana jednym krótkim zdaniem. Stosuj porządek: bezpieczeństwo → routing → przekierowania → nagłówki → wydajność. Raz w kwartale dokonuj przeglądu: usuń reguły nieużywane, zbyt ogólne lub nachodzące na siebie.

Bezpieczeństwo na pierwszym miejscu

Najpierw likwiduj wektory ataku: blokuj dostęp do wrażliwych plików, wymuszaj TLS, ograniczaj metody HTTP, waliduj pochodzenie żądań. Zasada najmniejszych uprawnień wciąż obowiązuje. Pamiętaj też o monitoringu: alerty na wzrost 4xx/5xx, nagłe spadki ruchu i zmiany w czasie odpowiedzi.

Na koniec zrób szybki przegląd słów kluczowych, które warto znać i rozumieć podczas edycji: bezpieczeństwo, uprawnienia, Redirect, RewriteRule, mod_rewrite, HTTPS, kompresja, cache, nagłówki, a także sama natura pliku .htaccess. Z tym zestawem i procedurą pracy krok po kroku edycja ręczna stanie się przewidywalna, powtarzalna i bezpieczna.