Node.js ERR_OSSL_EVP_UNSUPPORTED hatası: kalıcı çözüm ve geçici seçenek

Node.js OpenSSL hatasında eski derleme bağımlılığını tespit edin; Webpack güncellemesini, hash ayarını ve legacy provider seçeneğini doğru yerde kullanın.

Node.js ile bir projeyi başlatırken veya derlerken ERR_OSSL_EVP_UNSUPPORTED ya da error:0308010C:digital envelope routines::unsupported görüyorsanız, kullanılan bir kriptografik işlem mevcut OpenSSL yapılandırmasında desteklenmiyor olabilir. Eski Webpack tabanlı projelerde bunun sık rastlanan nedeni eski hash algoritması seçimidir.

Kalıcı çözüm, hatayı üreten derleme aracını veya bağımlılığı güncellemektir. Legacy provider seçeneği ise geçici bir uyumluluk yolu olarak ele alınmalıdır. Hatayı kapatmadan önce stack trace üzerinden hangi paketin işlemi başlattığını bulun.

1. Node ve OpenSSL sürümünü kontrol edin

node --version
node -p "process.versions.openssl"
npm ls webpack react-scripts

Node.js 17, OpenSSL 3 geçişini duyuran sürümlerden biridir. Bu geçişle varsayılan algoritma kısıtları değişti. Ancak bugün çözüm olarak Node 17 kurmak veya destek süresi bitmiş Node 16'ya kalıcı olarak dönmek uygun değildir. Projenin araçlarıyla uyumlu, desteklenen bir Node sürümü seçin.

Hata izinde webpack/lib/util/createHash görünmesi hash üretimine işaret eder. Başka bir paket veya uygulamanın kendi crypto çağrısı görünüyorsa çözümü o bileşende arayın. Her OpenSSL hatasını Webpack hatası kabul etmeyin; sertifika ve TLS sorunları farklı inceleme gerektirir.

2. Derleme aracını yöneten paketi güncelleyin

Webpack'i doğrudan yönettiğiniz projede uyumlu sürüm yükseltmesini ve gerekiyorsa loader/plugin güncellemelerini birlikte planlayın. Webpack'i react-scripts, bir framework veya başka bir CLI getiriyorsa önce o üst paketin desteklediği geçiş yolunu izleyin. Alt bağımlılığa rastgele override eklemek, aracın beklediği API'yi bozabilir.

npm explain webpack
npm outdated

Burada amaç yalnızca sürüm numarasını büyütmek değil, eski algoritmayı isteyen bileşeni kaldırmaktır. Seçilen sürümleri package.json ve lock dosyasında birlikte kaydedin. Ardından aynı Node sürümüyle geliştirme sunucusunu, üretim derlemesini ve projenin testlerini çalıştırın.

3. Doğrudan Webpack yapılandırmasında hash seçimi

Kendi Webpack yapılandırmasını kullanan ve xxhash64 desteği bulunan bir Webpack 5 sürümündeki proje için aşağıdaki ayar değerlendirilebilir. Webpack belgelerinde bu seçenek 5.54.0 ve sonrası için belirtilir:

// webpack.config.js - mevcut output ayarlarina ekleyin
module.exports = {
  output: {
    hashFunction: "xxhash64"
  }
};

Bu parça bütün config dosyanızı değiştirmek için değildir. Mevcut output alanına ekleyin. Bazı eski loader'lar kendi hash işlemini yapar; output ayarı onları değiştirmeyebilir. Framework'ün gizlediği yapılandırmaya da yalnızca desteklediği yöntemle müdahale edin.

4. Geçici legacy provider seçeneği

Acil olarak eski bir projeyi incelemek gerekiyorsa ve kullandığınız Node sürümü seçeneği destekliyorsa, yalnızca ilgili terminal oturumunda deneyebilirsiniz. PowerShell örneği, var olan NODE_OPTIONS değerini korur ve işlem sonunda geri yükler:

$previousNodeOptions = $env:NODE_OPTIONS
try {
  $env:NODE_OPTIONS = "$previousNodeOptions --openssl-legacy-provider".Trim()
  npm run build
} finally {
  $env:NODE_OPTIONS = $previousNodeOptions
}

Linux veya macOS terminalinde tek komut için:

NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--openssl-legacy-provider" npm run build

Bu seçenek eski kriptografik algoritmalara erişimi açar; bağımlılığı güncellemez. Sistem genelinde kalıcı ayar yapmayın. Node seçeneği reddederse sürüm ve derleme özelliklerini kontrol edin; farklı makinelerde aynı bayrağın aynı biçimde çalışacağını varsaymayın.

CI'da çalışmıyorsa neyi kontrol etmelisiniz?

Yerelde ve CI'da process.versions çıktısını karşılaştırın. Docker image'ı, CI runtime ayarı ve sürüm yöneticisi farklı Node sürümleri kullanabilir. Lock dosyasının commit edildiğini ve temiz kurulum yapıldığını doğrulayın. Geçici bayrak yalnızca yerelde varsa CI sonucu farklı olacaktır.

Kalıcı düzeltmeden sonra legacy bayrağını kaldırarak yeniden derleyin. Bayrak olmadan tamamlanan temiz üretim derlemesi, eski hash yolunun artık kullanılmadığını anlamak için daha değerli bir kontroldür.