.htaccess dosyası tek bir metin dosyasından ibarettir. Ama o tek dosyayı oluşturmak, içerik yazmaya başlamadan önce birkaç kez takılmanıza yol açabilir — çoğunlukla Apache'nin değil, işletim sisteminin ya da editörün yarattığı nedenlerle.
Sorun genellikle şu ikisinden birinde gizlenir: dosya doğru adla kaydedilmemiştir ya da yanlış encoding ile yazılmıştır. Her ikisi de sessiz hatalardır; Apache size neyin yanlış gittiğini söylemez, dosyayı yok sayar ya da genel bir 500 hatası döner.
Windows'ta nokta ile başlayan dosya sorunu
.htaccess dosyasının adı, nokta ile başlar ve görünür bir uzantısı yoktur. Windows ise bu dosya adı formatını neredeyse hiç sevmez.
Not Defteri ile kaydetmeye çalıştığınızda, "Dosya türü" alanında "Metin Dosyaları (*.txt)" seçili kalıyorsa Windows dosyayı .htaccess.txt olarak kaydeder. Üstelik uzantı görünümü kapalıysa Dosya Gezgini'nde ad yalnızca .htaccess gibi görünür — hatayı fark edemezsiniz. Apache ise .htaccess.txt dosyasına hiç bakmaz.
Doğru kaydetme adımları:
- Not Defteri ya da tercih ettiğiniz bir editörü açın
- Farklı Kaydet penceresinde "Dosya türü" olarak Tüm Dosyalar (*.*) seçin
- Dosya adı alanına tam olarak
.htaccessyazın — nokta dahil, uzantı yok - Encoding olarak UTF-8 seçin
- Kaydet
Dosyayı kaydettikten sonra klasörde göremiyorsanız, Dosya Gezgini'nde "Gizli öğeler"i görünür hale getirin. Windows, nokta ile başlayan dosyaları gizli olarak sınıflandırır; Görünüm sekmesinden ya da Seçenekler menüsünden bu ayarı açabilirsiniz.
macOS ve Linux'ta bu sorun yaşanmaz.
Encoding seçimi neden önemli
BOM (Byte Order Mark), bazı editörlerin UTF-8 dosyaların başına eklediği görünmez bir karakterdir. Dosya içerik olarak tamamen doğru olsa bile Apache bunu sözdizimi hatası olarak yorumlayabilir. Sonuç: 500 Internal Server Error.
Eski Windows Not Defteri, UTF-8 ile kaydetme seçtiğinizde otomatik olarak BOM ekler. Yeni sürümlerde bu davranış değişti; ama emin olmak için başka bir editör kullanmak tercih edilir.
Encoding sorununu önleyen güvenilir seçenekler:
- VS Code: Dosyayı açtıktan sonra sağ alt köşede "UTF-8" yazıyorsa güvendesiniz. "UTF-8 with BOM" görüyorsanız, Command Palette'ten "Change File Encoding" → "Save with Encoding" → "UTF-8" seçin.
- Notepad++: Üst menüden Format → "UTF-8 (BOM'suz)" seçeneğini seçin. Sonraki kaydetmelerde bu ayar korunur.
- Nano, Vim, Emacs: Terminal editörleri BOM eklemez. Linux ve macOS ortamlarında bu araçlardan biri en güvenli seçimdir.
Editörü bir kez doğru yapılandırdıktan sonra aynı editörü kullanmaya devam edin. Her kaydetmede encoding kontrolü yapmanıza gerek kalmaz.
Dosyaya ne yazılır
Boş bir .htaccess dosyası teknik olarak geçerlidir — Apache onu görür, okur, hiçbir şey yapmaz. Ama bir başlangıç içeriği koymak iyidir; hem dosyanın gerçekten işlenip işlenmediğini test edebilirsiniz hem de ilk gerçek ihtiyacınız için hazır olur.
Aşağıdaki iki direktif, neredeyse her web sitesi için uygun bir başlangıç noktasıdır:
# Dizin listelemeyi kapat
Options -Indexes
# Varsayılan karakter kodlaması
AddDefaultCharset UTF-8
Options -Indexes, ziyaretçilerin bir klasörü doğrudan tarayıcıya yazdığında içindeki dosya listesini görmesini engeller. Bu özellik Apache'de varsayılan olarak açık gelir; kapatmak hem bilgi sızıntısını önler hem de beklenmedik dizin görünümlerinin önüne geçer. Yönlendirme, önbellek ve güvenlik direktiflerini tek adımda hazırlamak istiyorsanız kapsamlı htaccess yapılandırması oluşturmak için araç sayfasından yararlanabilirsiniz.
# ile başlayan satırlar yorum satırıdır; Apache bunları işlemez. Kuralları gruplamak ya da her direktifin ne yaptığını not düşmek için kullanabilirsiniz. Boş satırlar da dosya yapısını bozmaz.
Dikkat: Bir direktif tek satırda tamamlanmalıdır. Uzun parametreler için bazı editörler otomatik satır sonu ekler — bu durum direktifi bozabilir. Kaydetmeden önce satır uzunluğunu kontrol edin.
Dosyayı nereye koyacaksınız
.htaccess, yerleştirildiği dizini ve tüm alt dizinleri etkiler. Kök dizine koyduğunuzda kurallar sitenin tamamına uygulanır; bir alt dizine bıraktığınızda yalnızca o klasör ve içindeki klasörler için geçerli olur.
Yaygın kök dizin yolları ortama göre değişir:
| Ortam | Kök dizin yolu |
|---|---|
| cPanel hosting | /public_html/ |
| Ubuntu / Debian | /var/www/html/ |
| CyberPanel / LiteSpeed | /home/[domain]/public_html/ |
| Yerel Apache (Windows) | C:\Apache24\htdocs\ |
Alt dizin kuralları ile kök dizin kuralları çakıştığında, alt dizindeki .htaccess öncelik alır — ama yalnızca kendi kapsamındaki direktifler için. Kök dizinden devralınan kurallar hâlâ geçerlidir; alt dizin yalnızca üzerine yazan direktifleri geçersiz kılar.
FTP ile yüklerken dosya listede görünmeyebilir. Nokta ile başladığı için gizli olarak işaretlenmiştir. FileZilla'da Sunucu menüsü → "Gizli dosyaları zorla göster" seçeneğini açın; diğer FTP istemcilerinde benzer bir ayar bulunur. Aynı yükleme sırasında tarayıcı botlarını yönetmek için robots.txt dosyasını da kök dizine bırakın — .htaccess erişim kontrolü yaparken robots.txt tarama yönlendirmesi sağlar.
Çalışıp çalışmadığını nasıl anlarsınız
Apache .htaccess dosyasını her gelen istek sırasında okur. Sunucuyu yeniden başlatmanıza gerek yoktur. Dosyayı yükledikten sonra tarayıcıyı açıp siteyi ziyaret etmeniz yeterlidir.
İki farklı sorun türü farklı şeylere işaret eder:
500 Internal Server Error alıyorsanız: .htaccess bulundu ve işlendi, ama içinde sözdizimi hatası var. Olası nedenler; yanlış direktif adı, eksik parametre ya da BOM encoding sorunudur. Apache error log'larını incelemeniz gerekebilir. Log yolu genellikle /var/log/apache2/error.log ya da /var/log/httpd/error_log altındadır; hosting panelinizde de erişilebilir olabilir.
Kural hiç çalışmıyor ama hata da almıyorsanız: Sözdizimi doğru olabilir, ama Apache .htaccess dosyalarını işlemiyor. AllowOverride None ayarı aktifse Apache tüm .htaccess kurallarını sessizce görmezden gelir. Bu ayar, sunucunun ana yapılandırma dosyasında (httpd.conf ya da apache2.conf) bulunur ve AllowOverride All ya da ilgili direktif türlerine izin veren bir değere çekilmesi gerekir. Paylaşımlı hosting kullanıyorsanız bu ayarı kendiniz değiştiremezsiniz; hosting sağlayıcınızla iletişime geçmeniz gerekebilir.
Yerel kurulumda sözdizimini test etmek için terminalden şu komutu çalıştırın:
apachectl configtest
Syntax OK çıktısı alıyorsanız .htaccess dahil tüm yapılandırma dosyaları geçerlidir. Windows'ta bu komut Apache kurulum dizininden çalıştırılır; WAMP, XAMPP gibi yerel sunucularda ise genellikle kontrol paneli içinden erişilebilir bir test seçeneği bulunur.
.htaccess dosyasını oluşturduktan sonra asıl kararlar başlar: hangi kurallar gerçekten gerekli, hangisi sunucu yapılandırmasına taşınmalı, hangisi her istekte yeniden değerlendirilmesi için .htaccess'te kalabilir. Redirect ve cache başlıkları gibi değişmeyen yapılandırmalar httpd.conf içinde sabit tanımlamak daha verimlidir; .htaccess'te kalan her direktif Apache'nin gelen her isteği işlemeden önce dosyayı yeniden okumasını gerektirir. Küçük bir site için fark fark edilmez; yüksek trafikli bir sunucuda bu I/O ağırlığı birikiyor. Hangi direktifin .htaccess'te kalması gerektiğini, hangisinin httpd.conf'a taşınabileceğini ayrı bir yazıda karşılaştırıyoruz.