Web Sitenizi veya Uygulamanızı Yayınladıktan Sonra 404 Hataları Nasıl Düzeltilir

Uygulamanız yerelde çalışıyor ama yayından sonra sayfalar 404 dönüyorsa, en yaygın neden tek sayfalık uygulama (SPA) yönlendirmesinin eksik olmasıdır: sunucu, var olmayan /dashboard adlı bir dosya arar, çünkü bu rota yalnızca JavaScript içinde vardır. Düzeltme, uygulama rotaları için index.html sunan bir yedek kuraldır. Diğer nedenler arasında derleme çıktısında eksik dosyalar, büyük-küçük harfe duyarlı yollar, sondaki eğik çizgi farkları, yanlış bir temel yol ve hiç yayınlanmamış API rotaları yer alır.

Önce tam olarak hangi URL’nin 404 verdiğini ve oraya nasıl ulaştığınızı not edin. Örüntü, nedene doğrudan işaret eder.

Adım 1: Örüntüyü bulun

Gerçek durum kodunu görmek için geliştirici araçlarını açın (sağ tık → İncele), Ağ sekmesine gidin, sayfayı yeniden yükleyin ve ilk isteğin durumuna bakın.

Adım 2: SPA yedeğini ekleyin

Bu klasik sorundur. React, Vue ya da Svelte tek sayfalık bir uygulamada sunucuda yalnızca birkaç gerçek dosya bulunur: index.html ve birkaç JavaScript ile CSS dosyası. /dashboard ya da /projects/42 gibi rotaları tarayıcıdaki bir yönlendirici yönetir.

• Bir bağlantıya tıklamak çalışır: yönlendirici URL’yi değiştirir ve yeni sayfayı sunucuya sormadan çizer.
• Yenilemek ya da bağlantıyı doğrudan açmak başarısız olur: tarayıcı sunucudan /dashboard ister, sunucuda böyle bir dosya yoktur ve 404 döner.

Düzeltme, şu kuraldır: istek gerçek bir dosyayla eşleşmiyorsa, index.html’i 200 durum koduyla sun ve yönlendiricinin devralmasını sağla. Bunu nasıl ekleyeceğiniz sunucuya bağlıdır (ayrıntılar değiştiği için sunucunuzun güncel dokümanlarını kontrol edin):

Kuralın gerçek dosyaları yutmadığından emin olun: /assets/app.js istekleri hâlâ JavaScript dosyasını döndürmelidir. Bunun yerine index.html dönüyorsa, “Failed to load module script” hatasıyla boş bir sayfa görürsünüz. Bkz. boş beyaz sayfa nasıl düzeltilir.

Ayrıca yönlendiriciye bir yakalayıcı (catch-all) rota verin; böylece hiçbir sayfayla eşleşmeyen URL’ler boş bir ekran yerine “Sayfa bulunamadı” mesajı göstersin.

Sunucu ayarlarını değiştiremiyorsanız, hash yönlendirme (/#/dashboard gibi URL’ler) sorunu önler, çünkü # sonrasındaki kısım hiçbir zaman sunucuya gönderilmez. Bu ilk tercih değil, geçici bir çözümdür: URL’ler daha çirkindir ve arama motorlarına daha az dostçadır.

Sunucuda sayfa oluşturan ya da derleme zamanında üreten çatılar (Next.js, Astro ve benzerleri) genellikle her sayfa için gerçek dosyalara ya da sunucu rotalarına sahiptir, bu yüzden bu sorun orada daha az yaygındır. Bunların karşılığı, derleme zamanında hiç üretilmemiş bir sayfadır.

Adım 3: Gerçekte neyin yayınlandığını kontrol edin

Her şey 404 veriyorsa, sunucu muhtemelen derlenmiş uygulamanızı sunmuyordur.

• Doğru klasör. Sunucu, proje kökünü değil derleme çıktısını (Vite için genellikle dist, Create React App için build, statik bir Next.js dışa aktarımı için out) yayınlamalıdır.
• Derleme çalıştı. Dağıtım günlüğünü okuyun. Derleme başarısız olduysa, sunucu hiçbir şey dağıtmamış ya da eski bir sürümü dağıtmış olabilir.
• index.html en üst düzeyde yayınlanan klasörün içinde, bir alt klasörde değil.
• Temel yol eşleşiyor. Uygulama example.com/app/ adresinde sunuluyorsa, o temel yolla derlenmelidir (Vite’ın base, React Router’ın basename), yoksa her rota ve varlık kaçırılır.

Adım 4: Eksik dosyaları ve yanlış yolları düzeltin

Sayfalar yükleniyor ama varlıklar 404 veriyorsa:

• Büyük-küçük harf duyarlılığı. macOS ve Windows genellikle Logo.png ile logo.png’yi aynı dosya sayar. Çoğu Linux sunucusu bunu yapmaz. Her referansı gerçek dosya adıyla birebir eşleştirin.
• Derlemenin dışındaki dosyalar. Vite’ta public/ içindeki dosyalar olduğu gibi kopyalanır ve kökten (/logo.png) referans verilir. Kodda içe aktarılan dosyalar paketlenir. Projede başka bir yerdeki bir dosya hiç yayınlanmamış olabilir.
• Göreceli yollar. images/photo.jpg geçerli URL’ye göre çözülür, bu yüzden /blog/post-1 üzerinde bozulur. /images/photo.jpg kullanın.
• Yerel diske kaydedilen yüklemeler. Kullanıcı yüklemeleri sunucunun kendi klasörüne yazıldıysa, yeni bir sürüm yayınlandığında kaybolurlar. Uygun bir dosya depolama kullanın.

Adım 5: Sondaki eğik çizgileri tutarlı yönetin

/about ile /about/ farklı URL’lerdir. Sunucular eğik çizgiyi ekleyip eklemediğinde ya da kaldırıp kaldırmadığında farklılık gösterir ve bağlantılarınız ya da yönlendiriciniz ile uyuşmazlık 404 hatalarına ya da yönlendirme döngülerine yol açabilir. Tek bir biçim seçin, bağlantılarınızı buna göre yapın ve sunucuyu diğer biçimi buna yönlendirecek şekilde ayarlayın. Tutarlılık arama motorlarına da yardımcı olur; aksi halde her sayfanın iki kopyasını görebilirler.

Adım 6: 404 veren API rotalarını düzeltin

Sayfa yükleniyor ama Ağ sekmesinde /api/... isteklerinin 404 döndüğünü görüyorsanız:

• Arka uç yayınlanmamış. Statik bir sunucu yalnızca dosyaları sunar; bir arka ucun bir yerde çalışması gerekir.
• Yol, üretimde farklı yönlendiriliyor. Geliştirmede bir proxy /api isteklerini ayrı bir sunucuya iletmiş olabilir. Üretimde sunucunun eşdeğer bir rewrite’a ihtiyacı vardır ya da ön yüzün API’nin gerçek adresine istek atması gerekir.
• SPA yedeği isteği yakaladı. Bir API isteği 200 durum koduyla index.html döndürüyorsa, yedek kural çok geniştir. /api/* yollarını bu kuralın dışında tutun.

Yayınlanan uygulamanın /api/orders isteklerine 404 dönüyor, ama önizlemede çalışıyorlar. Önizlemede ve yayınlanmış uygulamada /api’nin nasıl yönlendirildiğini kontrol edin ve yayınlanmış ön yüzün arka uca aynı şekilde ulaşmasını sağlayın.

Adım 7: Eski URL’leri yönlendirin

Başka bir siteden taşındıysanız ya da yapıyı değiştirdiyseniz, insanların ve arama motorlarının hâlâ kullandığı eski URL’ler 404 verecektir. Her eski URL’den yeni adresine bir 301 (kalıcı) yönlendirme ekleyin. Bir liste tutun ve lansmandan sonra bir örneği test edin. WordPress sitesi taşıma rehberimiz bu listenin nasıl oluşturulacağını anlatır.

Adım 8: Alan adını kontrol edin

Uygulama sunucunun adresinde çalışıyor ama özel alan adınızda 404 veriyorsa, alan adı yanlış projeye işaret ediyor olabilir ya da sunucu alan adını henüz sitenize eklememiştir. DNS kayıtlarını ve sunucunun alan adı ayarlarını kontrol edin. Bkz. özel alan adı nasıl bağlanır.

Gerçek 404 sayfanızı yararlı hale getirin

Bazı 404’ler doğrudur: biri bir URL’yi yanlış yazmıştır. Bu sayfayı yardımcı olacak şekilde yapın:

• Kısa bir mesaj ve ana sayfaya ile önemli bölümlere bağlantılar
• Sitenizde arama varsa bir arama kutusu
• Sitenin geri kalanıyla aynı üst bilgi ve gezinme

Kurulumunuz izin veriyorsa, var olmayan sayfalar için gerçek bir 404 durum kodu döndürün. 200 durum koduyla dönen bir “bulunamadı” mesajı, arama motorlarının yumuşak 404 dediği şeydir ve tarama sürelerini boşa harcayıp dizinlemeyi karıştırabilir.

Sık yapılan hatalar

• Yalnızca tıklayarak test etmek. Her zaman derin URL’leri yeni bir sekmeye yapıştırıp yenileyerek test edin.
• Her şeyi yakalayan bir yedek. Varlıklar ve API rotaları index.html döndürür, bu da boş sayfalara ve kafa karıştıran API hatalarına yol açar.
• Yalnızca sunucuda bozulan uyumsuz büyük-küçük harf.
• Derleme çıktısı yerine kaynak klasörü yayınlamak.
• Yönlendirme olmadan URL’leri yeniden yapılandırmak. Her eski bağlantı bir 404’e dönüşür.

Mythex’te 404’ler

Mythex’te çalışma alanından yayınlarsınız ve statik ön yüzler statik siteler olarak dağıtılır. Yayınlanmış bir sayfa 404 veriyorsa, ajana tam URL’yi, yenilemede mi yoksa tıklamada mı olduğunu ve Ağ sekmesinin ne gösterdiğini verin ve yönlendirmeyi kontrol etmesini isteyin. Düzeltmeden sonra yeniden yayınlayın, çünkü canlı uygulama siz yeniden yayınlayana kadar bir anlık görüntüdür. Projeyi yakın zamanda değiştirdiyseniz ve canlı site eski görünüyorsa, yeniden yayınlayıp sert yenileme yapın. Derleme başarısız olursa yayın penceresindeki Fix with AI seçeneğini kullanın. Dokümanlarda Nasıl yayınlanır ve Yayın sorun giderme bölümlerine, ayrıca yapay zekayla yapılmış bir uygulamada hata ayıklama rehberimize bakın.

404 kontrol listesi

• Tam olarak hangi URL’lerin 404 verdiği ve tıklamada, yenilemede ya da ikisinde birden olduğu not edildi
• SPA yedeği uygulama rotaları için 200 durum koduyla index.html sunuyor
• Yedek, gerçek dosyaları ve /api/* yollarını dışarıda bırakıyor
• Yönlendiricide bir yakalayıcı “bulunamadı” rotası var
• Yayınlanan klasör derleme çıktısı ve derleme başarılı
• Temel yol, uygulamanın sunulduğu yerle eşleşiyor
• Dosya adı büyük-küçük harfi her referansla eşleşiyor
• Varlık yolları / ile başlıyor
• Sondaki eğik çizgi biçimi tutarlı
• API rotaları üretimde dağıtılmış ve yönlendirilmiş
• Eski URL’ler için 301 yönlendirmeler var
• Derin bağlantılar yeni bir sekmeye yapıştırılarak test edildi

Sorular