npm ERR! ERESOLVE unable to resolve dependency tree hatası nasıl çözülür?

npm ERESOLVE hatasının kaynağını bulun; peer dependency sürümlerini eşleştirin, legacy-peer-deps ile force farkını öğrenin ve kurulumu doğrulayın.

npm install sırasında görülen ERESOLVE unable to resolve dependency tree hatası, paketlerin talep ettiği sürüm aralıklarının aynı bağımlılık ağacında uyuşmadığını gösterir. Örneğin projeniz React 18 kullanırken bir bileşen yalnızca React 17 ile çalıştığını bildiriyorsa npm bu ilişkiyi çözemeyebilir.

Kalıcı çözüm, hata raporunda adı geçen paketleri uyumlu sürümlerde buluşturmaktır. --legacy-peer-deps kurulumu geçirebilir; ancak paketlerin birlikte doğru çalışacağını garanti etmez. Önce hangi ilişkinin bozulduğunu bulalım.

1. Hata raporundaki iki sürüm aralığını bulun

Aşağıdaki çıktı öğretici bir örnektir; example-widget gerçek bir paket önerisi değildir:

Found: react@18.2.0
Could not resolve dependency:
peer react@"^17.0.0" from example-widget@1.0.0

Found kurulu sürümü, peer ise diğer paketin beklediği sürüm aralığını gösterir. Peer dependency, paketin çevresindeki uygulamadan beklediği bağımlılıktır. npm 7 ve sonrasında bu ilişkiler kurulumda daha etkin biçimde çözülür. Hatanın adını görmek tek başına yeterli değildir; çakışan paket ve aralığı da kaydedin.

node --version
npm --version
npm ls react
npm explain react

Örneğiniz React ile ilgili değilse son iki komutta hata raporundaki bağımlılık adını kullanın. npm ls geçersiz ilişki bulduğunda sıfırdan farklı çıkış kodu verebilir; bu, teşhis sırasında beklenebilen bir sonuçtur.

2. Uyumlu paket sürümünü seçin

Çakışan paketin güncel sürümünü ve bildirdiği peer dependency aralığını kontrol edin. Aşağıdaki komutta yer tutucuyu hata raporundaki gerçek paket adıyla değiştirin:

npm view <paket-adi>@latest peerDependencies
npm view <paket-adi> versions --json

En yeni sürüm uygulamanızın kullandığı framework ile uyumluysa paketi yükseltin. Uyumlu değilse desteklenen başka bir sürümü veya bakımı devam eden bir alternatifi değerlendirin. Ana framework sürümünü düşürmek bazen mümkündür; fakat uygulamanın diğer bağımlılıklarını ve kullandığı özellikleri de etkiler.

Seçtiğiniz gerçek sürümü npm install <paket-adi>@<uyumlu-surum> ile yükleyin. Bütün paketleri aynı anda latest sürümüne geçirmek, küçük bir çakışmayı kapsamlı bir geçiş çalışmasına çevirebilir. Önce rapordaki ilişkiyi düzeltmek değişikliğin etkisini takip etmeyi kolaylaştırır.

3. legacy-peer-deps ve force ne yapar?

npm install --legacy-peer-deps, bağımlılık ağacı oluşturulurken peer dependency ilişkilerini dikkate almayan eski davranışı kullanır. Yalnızca sürüm bildirimindeki eksikliğin farkında olduğunuz ve uygulamayı test edebildiğiniz geçici durumlarda değerlendirin.

npm install --force daha geniş korumaları gevşetir. İki seçenek aynı değildir; hiçbiri uyumsuz bir API'yi uyumlu hale getirmez. Kurulumun başarılı olması, uygulamanın çalışmasıyla aynı sonuç değildir.

Geçici olarak legacy ayarıyla oluşturulan lock dosyası CI ortamında aynı ayarı gerektirebilir. Bu kararı proje yapılandırmasında açıkça belgeleyin; geliştiricinin bilgisayarına gizli bir genel npm ayarı eklemek ekipte farklı kurulumlar oluşturabilir.

4. Lock dosyasını rastgele silmeyin

package-lock.json, çözülmüş sürümleri kayıt altında tutar. Silinmesi bütün izin verilen sürümlerin yeniden seçilmesine yol açabilir. Önce paket aralıklarını düzeltin, normal kurulumla lock dosyasını güncelleyin ve Git farkını inceleyin. Önbellek temizlemek de sürüm aralığı çakışmasını düzeltmez.

Temiz kurulum kontrolünü ayrı bir checkout veya CI ortamında yapın. npm ci mevcut node_modules dizinini yeniden kurar ve package.json ile lock dosyasının uyuşmasını bekler:

npm ci
npm ls
npm run build

Çözümün işe yaradığını nasıl anlarsınız?

Kurulum hatasız tamamlanmalı, npm ls ilgili ilişkiyi invalid göstermemeli ve değişen paketi kullanan ekran veya işlem çalışmalıdır. Projenizin testlerini de çalıştırın. Yerel ve CI Node/npm sürümlerini eşleştirerek aynı çözümün iki ortamda tekrarlandığını doğrulayın.