npm SSL Error UNABLE_TO_VERIFY

npm install sırasında UNABLE_TO_VERIFY_LEAF_SIGNATURE, SELF_SIGNED_CERT_IN_CHAIN veya unable to get local issuer certificate hataları görüyorsanız Node.js, registry sunucusunun sertifika zincirini güvendiği bir kök CA'ya bağlayamıyor demektir.

En sık nedenler

• Kurumsal ağda SSL denetimi (TLS inspection) yapan proxy, kendi CA'sıyla sertifika yeniden imzalıyor.
• Özel (private) npm registry sertifikasının ara sertifikası eksik sunuluyor.
• Sistem saati yanlış olduğu için sertifika "henüz geçerli değil" görünüyor.
• Eski bir Node.js sürümü güncel kök sertifikaları içermiyor.

Doğru çözüm: CA'yı tanıtmak

Kurumsal CA'nızı PEM formatında alın ve npm'e tanıtın:

npm config set cafile /etc/ssl/kurum-ca.pem
npm config get cafile

# Alternatif: Node.js seviyesinde ek CA
export NODE_EXTRA_CA_CERTS=/etc/ssl/kurum-ca.pem

Windows'ta PowerShell için $env:NODE_EXTRA_CA_CERTS="C:\sertifikalar\kurum-ca.pem" kullanılabilir. Ardından npm install komutunu yeniden çalıştırın.

Sunucu tarafını kontrol etme

Özel registry'yi siz yönetiyorsanız sunulan zinciri doğrulayın:

openssl s_client -connect registry.ornek.com:443 -servername registry.ornek.com -showcerts

Çıktıda yalnızca yaprak sertifika varsa ara sertifikayı sunucu yapılandırmasına ekleyin; sorun istemci yerine sunucuda çözülür ve tüm geliştiricileri tek seferde kurtarır.

Kaçınılması gereken kısayol

npm config set strict-ssl false hatayı susturur ama paket indirmelerini ortadaki saldırgana açık bırakır. Yalnızca kısa süreli yerel denemede başvurun ve sonra geri alın:

npm config delete strict-ssl

Kalıcı çözüm her zaman doğru CA'yı tanıtmak ve sunucuda tam zinciri yayınlamaktır. Kendi kurumsal servisleriniz için SSL sertifikaları ve zincir kontrolü için SSL Checker işinize yarar; sorun devam ederse SSL sorun giderici adım adım yol gösterir.