Web Uygulamanızda Boş Beyaz Sayfa Nasıl Düzeltilir

Boş beyaz bir sayfa neredeyse her zaman iki şeyden birini anlatır: uygulamanın JavaScript’i hiçbir şey çizmeden önce çökmüştür ya da JavaScript hiç yüklenmemiştir. Tarayıcı konsolunu açın (sağ tık → İncele → Konsol) ve ilk kırmızı hatayı okuyun, sonra yüklenemeyen dosyalar için Ağ sekmesine bakın. Çoğu neden eksik bir ortam değişkeni, yanlış bir temel yol, bitmemiş bir derleme ya da tek bir bileşendeki bir çökmedir.

Bu rehber, React, Vue ya da benzeri çatılarla yapılmış tek sayfalık uygulamaları kapsar (yapay zeka oluşturucularının yaptıklarını da dahil), boş sayfaların en sık görüldüğü yer burasıdır.

Sayfa neden beyaz

Modern bir tek sayfalık uygulama (SPA) tarayıcıya neredeyse boş bir HTML dosyası gönderir, kabaca şöyle:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Sonra JavaScript, tüm sayfayı o boş div’in içinde oluşturur. Betik yüklenemezse ya da render edilmeden önce bir hata verirse, div boş kalır ve beyaz görürsünüz. Sayfa görünür bir şekilde “bozuk” değildir; sadece hiç çizilmemiştir.

Bu yüzden düzeltme her zaman sayfanın kendisinde değil, geliştirici araçlarında başlar.

Adım 1: Konsolu okuyun

Geliştirici araçlarını açın: sayfaya sağ tıklayıp İncele seçin ya da F12’ye basın (Mac’te Cmd+Option+I). Konsol sekmesine gidin ve sayfayı yeniden yükleyin.

İlk kırmızı hataya bakın; sonrakiler çoğu zaman yan etkidir. Ne dediği nedene işaret eder:

Dosya adı ve satır numarası dahil tam hata metnini kopyalayın. Bir yapay zeka oluşturucu kullanıyorsanız, doğrudan sohbete yapıştırın.

Adım 2: Dosyaların yüklendiğini kontrol edin

Ağ sekmesini açın, Önbelleği devre dışı bırak kutusunu işaretleyin ve yeniden yükleyin. .js ve .css dosyalarına yapılan isteklere bakın.

• Bir JavaScript dosyasında 404 durumu: sayfa sunucuda olmayan bir dosya istiyor.
• 200 durumu ama tür text/html: sunucu betik yerine bir sayfa döndürmüş (çoğu zaman SPA yedeği yüzünden index.html kendisi). Kök neden aynı: dosya, sayfanın beklediği yerde değil.

Sık nedenler:

Yanlış temel yol. Uygulama example.com/app/ gibi bir alt klasörden sunuluyorsa, ama /assets/... konumundan dosya yükleyecek şekilde derlendiyse, her betik isteği ıska geçer. Vite’ta bu, vite.config içindeki base seçeneğidir; Create React App’te homepage alanıdır; Next.js’te basePath’tir. Uygulamanın gerçekte sunulduğu yerle eşleşmelidir.

Eski index.html. Derleme araçları dosyalara içerik özetine dayalı adlar verir, örneğin index-a1b2c3.js. Yeni bir dağıtımdan sonra eski dosya ortadan kalkar. Bir tarayıcı ya da CDN hâlâ eski index.html’i önbelleğinde tutuyorsa, eski dosyayı ister ve hiçbir şey alamaz. Sert yenileme (Cmd+Shift+R ya da Ctrl+Shift+R) bunu doğrular. Kalıcı çözüm, karma adlı dosyalar uzun süre önbelleğe alınırken index.html’i kısa ya da önbelleksiz bir başlıkla sunmaktır.

Derleme bitmedi ya da dağıtılmadı. Derleme başarısız olduysa, sunucu eski ya da boş bir çıktı klasörünü sunuyor olabilir. Derleme günlüğünde hataları kontrol edin.

Yanlış klasör yayınlanmış. Sunucu, projenin kaynak klasörünü değil derleme çıktısını (genellikle dist ya da build) sunmalıdır. Kaynağı sunmak, /src/main.tsx adresine işaret eden bir index.html verir ve tarayıcılar bunu çalıştıramaz.

Adım 3: Ortam değişkenlerini kontrol edin

Ön yüz uygulamaları genellikle bir API URL’si ya da herkese açık bir anahtar gibi ayarları derleme zamanında okur. Canlı derlemede bir değişken eksikse, createClient(undefined, undefined) gibi bir kod hemen hata verir ve sayfa beyaza döner.

Bilmeniz gerekenler:

• Vite’ta tarayıcı kodunda yalnızca VITE_ ön ekli değişkenler kullanılabilir ve import.meta.env.VITE_NAME olarak okunur. Create React App’te bu REACT_APP_, Next.js’te NEXT_PUBLIC_’tir.
• Bu değerler uygulama derlendiğinde içine gömülür. Derlemeden sonra eklenen bir değişken, yeniden derleyip yeniden dağıtana kadar hiçbir şey yapmaz.
• Önizlemenin ya da yerel makinenizin, üretim derlemesinde olmayan bir .env dosyası olabilir. Aynı değişkenleri sunucuda da ayarlayın.
• Bu önekleri taşıyan her şey herkese açık JavaScript’e girer. Oraya yalnızca herkese açık değerler koyun, asla gizli anahtarları değil.

Hızlı bir test: konsol hatasında bir ayar adının yanında undefined arayın ya da şunu isteyin:

Yayınlanmış uygulama boş bir sayfa gösteriyor. Ön yüzün okuduğu her ortam değişkenini listele, canlı derlemede hangilerinin eksik ya da boş olduğunu kontrol et ve biri eksikse boş sayfa yerine uygulamanın açık bir hata mesajı göstermesini sağla.

Adım 4: Çökmeyi düzeltin

Konsolda normal bir JavaScript hatası görünüyorsa, kod render sırasında çökmüştür. Yapay zeka ile yapılmış uygulamalarda tipik nedenler:

• Veri henüz yüklenmedi. Bir bileşen, user gelmeden önce user.name okur. Düzeltme bir yükleme durumu ya da isteğe bağlı zincirleme (user?.name) eklemektir.
• Boş veri. Yeni bir hesabın kaydı yoktur, ama kod listede en az bir öğe olduğunu varsayar.
• Beklenmeyen veri yapısı. Bir API, kodun beklediği listeyi değil bir hata nesnesi döndürmüştür.
• Eksik bir import, bir dosya yeniden adlandırıldıktan ya da taşındıktan sonra.
• Sunucu tarafı render sırasında yalnızca tarayıcıda bulunan bir API kullanmak, örneğin bir Next.js sunucu bileşeninde window ya da localStorage.

Yapay zekaya tam hatayı, sayfayı ve hangi hesapla giriş yaptığınızı verin:

Dashboard sayfası yeni kullanıcılar için boş. Konsol: ProjectList.tsx:18 konumunda TypeError: Cannot read properties of undefined (reading 'map'). Projeleri olan hesabımda çalışıyor. Boş bir hesapta “Henüz proje yok” gösterecek şekilde düzelt ve önizlemede yeni bir hesabı kontrol et.

Adım 5: Bir hata sınırı ekleyin

React’te tek bir çöken bileşen tüm uygulamayı kaldırabilir; bu yüzden küçük bir hata tamamen boş bir sayfa üretir. Bir hata sınırı, altındaki render hatalarını yakalayan ve bunun yerine yedek bir ekran gösteren bir bileşendir.

Ana rotaların etrafına, “Bir şeyler ters gitti” mesajını ve bir Yeniden Yükle düğmesini gösteren, hatayı konsola da yazan bir hata sınırı ekle. Üst bilgi ve gezinme dışarıda kalsın ki yine görünsün.

Bu hatayı düzeltmez, ama ziyaretçiler boş ekran yerine bir mesaj görür ve sizin de nerede kırıldığını görmenizi sağlar.

Adım 6: Hata yok, ama hâlâ boş

Konsol temizse ve betikler yükleniyorsa:

• Elements sekmesine bakın. <div id="root"> içinde içerik var mı? Varsa render ediliyor ama görünmüyordur: beyaz üzerine beyaz metin, opacity: 0, display: none ya da onu kaplayan tam ekran bir öğe.
• Yönlendiriciyi kontrol edin. Geçerli URL’ye uyan bir rota yoksa ve “bulunamadı” rotası yoksa, bazı yönlendiriciler hiçbir şey render etmez. 404 sayfası gösteren bir yakalayıcı rota ekleyin.
• Bağlama noktasını kontrol edin. Kod, var olan bir öğeye bağlanmalıdır. index.html id="app" içeriyor ama kod root arıyorsa, hiçbir şey görünmez (ve React genellikle bir hata kaydeder).
• Bir tarayıcı eklentisini kontrol edin. Gizli bir pencere deneyin. Reklam engelleyiciler, analytics ya da ads gibi adları olan betikleri bazen engeller.

Yalnızca bir sayfayı yeniledikten sonra mı boş?

Ana sayfa çalışıyor ama /dashboard sayfasını yenilemek boş bir sayfa ya da 404 gösteriyorsa, sunucu uygulama rotaları için index.html göndermeyi bilmiyor demektir. Bu bir yönlendirme yedeği sorunudur ve yayından sonra 404 hatalarını düzeltme rehberinde ele alınır.

Sık yapılan hatalar

• İlk hatayı değil son hatayı okumak. İlk kırmızı satır genellikle nedendir.
• Derlemeden ortam değişkenlerini ayarlamak. Ön yüz değişkenleri derleme zamanında sabitlenir.
• Yalnızca kendi hesabınızla test etmek. Boş hesap çökmeleri, boş sayfaların en yaygın nedenlerinden biridir.
• Dağıtımın çalıştığını varsaymak. Kodu hata ayıklamadan önce derleme günlüğünü kontrol edin.
• Her şeyi tarayıcı önbelleğine yüklemek. Sert yenileme bunu saniyeler içinde eler; sayfa hâlâ boşsa sorun başkadır.

Mythex’te boş sayfalar

Önizleme boşsa, önce uygulamanın çalıştığını kontrol edin (Kod → terminal’i açın), sonra Mythex’ten doğru sunucuyu başlatmasını isteyin, önizleme araç çubuğunda Yenile’ye tıklayın ya da /fix kullanın. Yayınlanmış bir URL boşsa, dokümanlar bir dakika beklemeyi ve sert yenilemeyi, yayınlamadan önce ortam değişkenlerinin ve veritabanının kurulduğunu doğrulamayı ve barındırma kotanızı kontrol etmeyi önerir. Yayınlanmış uygulamanın bir anlık görüntü olduğunu unutmayın: bir şeyi düzelttikten sonra yeniden yayınlayın. Bir değişiklik soruna yol açtıysa, son iyi yanıttaki Bu noktaya geri dön seçeneği projeyi geri alır. Dokümanlardaki Sorun giderme ve Yayın sorun giderme bölümlerine, ayrıca yapay zekayla yapılmış bir uygulamada hata ayıklama genel rehberimize bakın.

Boş sayfa kontrol listesi

• Konsoldaki ilk kırmızı hatayı okudum
• Ağ sekmesinde 404 veren ya da HTML döndüren .js/.css dosyalarını kontrol ettim
• Temel yol, uygulamanın sunulduğu yerle eşleşiyor
• Derleme bitti ve yayınlanan klasör derleme çıktısı
• Tüm ön yüz ortam değişkenleri canlı derlemede ayarlandı, sonra yeniden derlendi
• Boş ve yeni hesaplar dahil çökme düzeltildi
• Gelecekteki çökmelerin bir mesaj göstermesi için hata sınırı var
• Bilinmeyen URL’ler için yakalayıcı rota var
• Sert yenileme ve gizli pencere sonrası test edildi

Sorular