For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /tr/docs/web/troubleshooting.md (or send Accept: text/markdown).
Sorun giderme
Kurulum sorunlarını gerçekten başarısız olan sınırda teşhis edin.
Kurulum ve yapılandırma
Herhangi bir adımdan önce, Başlamadan önce ve Terminal temelleri bölümlerini okuyun. Bu talimatlar, supastack monorepo'nun tamamını VS Kodunda açtığınızı varsayar; kök package.json dosyası depo kökünü işaretler. pnpm komutlarında çalışma alanı paketi bir uygulama veya paylaşılan kod klasörüdür; Üründe çalışma alanı, ekibin veri taşıyıcısı ve güvenlik sınırıdır. corepack pnpm --filter ... komutlar kökünden çalıştırılırken monorepodan bir paket seçer. Yalnızca senkronize edilmiş bir mobil veya masaüstü klasörü açtıysanız, Web arka ucunu, Docker kurulumunu veya kök komut dosyalarını içermez: arka ucu bu monorepodan veya erişilebilir bir barındırılan sunucudan çalıştırın ve platform klasörünün kendi komut dosyalarını kullanın. Ortam değişkeni, yerel bir .env dosyasında veya barındırma kontrol panelinizde depolanan adlandırılmış bir ayardır; İlgili uygulamayı değiştirdikten sonra yeniden başlatın ve sunucu sırlarını NEXT_PUBLIC_ ve EXPO_PUBLIC_ değerlerinin dışında tutun.
1. İlk faydalı hata satırını ve onu oluşturan komutu kopyalayın; gizli değerleri yapıştırmayın.
2. Deponun kökünden corepack pnpm --filter @supastack/web typecheck'i Web türü hataları için çalıştırın veya otomatik paket için corepack pnpm testini çalıştırın.
3. Tarayıcı sorunu için Web'i corepack pnpm --filter @supastack/web dev ile başlatın ve http://localhost:3000. konumunda yeniden oluşturun. Beklenen: ayarları değiştirmeden önce hatanın kurulumda mı, kodda mı, veritabanında mı, sağlayıcıda mı yoksa tarayıcıda mı olduğunu anlayabilirsiniz.
Yapılandırmayı değiştirmeden önce başarısız komutu ve ilk ilgili hatayı okuyun. Hatanın bağımlılık kurulumu, derleme, ortam doğrulaması, veritabanı erişimi, sağlayıcı gönderimi ya da tarayıcı davranışı olup olmadığını belirleyin.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm testKopyalanacak komutlar
Bir komutun hangi klasörde çalıştığını görmek için yorumları takip edin. İki terminal etiketlenmişse, iki terminal penceresi açın ve ikincisini kullanırken ilk komutu çalışır durumda tutun.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm testİlk çalıştırma hataları, çözümlenmiş
İlk çalıştırma az sayıda şekilde başarısız olur. İlk kırmızı hata satırını bir satırla eşleştirin — sonraki hatalar genellikle ilkinin sonucudur, bu yüzden diğer her şeyden önce en üsttekini düzeltin.
| Belirti | Olası neden | İlk düzeltme |
|---|---|---|
| node, corepack veya pnpm tanınmıyor / komut bulunamadı | Araç kurulu değil ya da terminal kurulum bitmeden önce açılmıştı | Kurun (veya terminali yeniden açın), ardından node --version komutunu yeniden deneyin |
| package.json bulunamadı / ENOENT package.json | Terminal yanlış klasörde | Depo köküne — package.json içeren klasöre — cd ile geçin ve yeniden deneyin |
| EADDRINUSE / 3000 numaralı bağlantı noktası zaten kullanımda | Başka bir geliştirme sunucusu bağlantı noktasını hâlâ tutuyor | O sunucunun terminalini bulun ve Ctrl + C'ye basın, ardından yeniden başlatın |
| localhost:5432'ye ECONNREFUSED veya bir veritabanı bağlantı hatası | Postgres çalışmıyor | docker compose up -d postgres komutunu çalıştırın, sağlıklı olana kadar bekleyin ve yeniden deneyin |
| Eksik bir anahtarı adlandıran ortam doğrulama hatası | apps/web/.env.local eksik veya zorunlu bir değeri boş | Adı geçen anahtarı .env.example'dan kopyalayın, bir değer verin, kaydedin ve sunucuyu yeniden başlatın |
| corepack enable sonrası corepack veya pnpm eksik | PATH üzerinde pnpm shim'i yok | corepack pnpm ... komutunu doğrudan kullanın — hiçbir zaman shim gerektirmez; Windows'ta corepack.cmd kullanın |
| PowerShell bir .ps1 betiğinin çalışamayacağını / engellendiğini söylüyor | PowerShell'in betik ilkesi shim'i engelliyor | .cmd biçimini kullanın — corepack.cmd pnpm install — ilke değişikliği gerekmez |
Uygulama iş akışı
Eksik API erişimi için sunucunun çalıştığını ve yapılandırılmış kaynağın istemciyle eşleştiğini doğrulayın. Kullanılamayan YZ seçenekleri için AI_MODEL_POLICY'yi ve etkin katalog satırlarını inceleyin. Belirsiz kuyruğa alınmış görev için başka gönderim başlatmak yerine kaydedilmiş kurtarma akışını kullanın.
Tarayıcı yerleşim sorunları için hesaplanmış stilleri inceleyin ve tam görünüm alanını yeniden üretin. Ürün chrome token'ları app-theme.css'te (catalog.ts'den paketler) yaşar; pazarlama marka kilidi theme.css'te yaşar. Bileşen geçersiz kılmaları özgüllükle yine kazanabilir. Yalnızca token bildirimini değil, işlenen yarıçapı kontrol edin.
Doğrulama ve sorun giderme
Sayfa :3001'deyse Web uygulaması için :3000'i açın; :3001 ayrı apps/docs sunucusuna aittir. Bir test veritabanı erişimi isterse yalıtılmış bir geliştirme veritabanı kullanın ve her iki .env konumunu da kontrol edin. Aynı hata devam ederse, yardım isterken komutu ekleyin ve ilk hata satırını temizleyin; asla erişim kontrollerini devre dışı bırakmayın veya günlüklere sırları yazdırmayın.
Başarısız kontrolü yetkilendirmeyi devre dışı bırakarak, sırları günlükleyerek ya da atlanmış altyapı kontrollerini geçmiş sayarak çözmeyin. Küçük bir yeniden üretim ve ilgili gizli olmayan yapılandırmayı yakalayın. Düzeltmeden sonra başarısız kontrolü, ardından etkilenen regresyon testlerini yeniden çalıştırın.