npm ci ile tekrarlanabilir kurulum: kilit dosyası tek başına güvenlik değildir

Bir Node.js uygulamasının geliştirici bilgisayarında çalışması, yeni cihazda aynı bağımlılıklarla kurulacağını garanti etmez. package.json sürüm aralıklarıyla kilit dosyasının çözdüğü kesin bağımlılık ağacı farklı amaçlara hizmet eder. Bu rehber genel sunucu kurulumundan farklı olarak npm tabanlı bir projenin temiz ve incelenebilir teslimine odaklanır. MagicMirror gibi modüllü projelere uygulanabilecek bir yöntemdir; özel depo veya gerçek paket yapılandırması burada yayımlanmıyor.

Sürüm bilgisini yalnız uygulamada tutmayın

Kabul kaydına Node.js, npm, işletim sistemi ve mimari bilgilerini ekleyin. Yerel eklentiler veya platforma bağlı paketler bulunduğunda aynı kilit dosyası farklı cihazda farklı çalışma koşullarıyla karşılaşabilir. Desteklenen çalışma zamanı sürümü projenin kendi belgeleriyle doğrulanmalıdır. En yeni sürümü otomatik olarak uygun sürüm saymayın. Bağımlılık kurulumunu düzeltmek için çalışma zamanı sürümünü kontrolsüz değiştirmek yeni uyumsuzluklar oluşturabilir.

npm belgeleri package-lock.json dosyasını çözümlenmiş bağımlılık ağacını tanımlayan bir kayıt olarak açıklar. Bu dosya kaynak kontrolünde incelenebilir olmalıdır. Yalnız uygulama dosyalarının değişmesi beklenirken çok sayıda alt bağımlılık değişmişse nedenini araştırın. Registry adreslerini ve kaynak değişimlerini de değerlendirin. Özel erişim bilgilerini kilit dosyasına veya paylaşılacak günlük çıktısına taşımayın; erişim ayarları ayrı yönetilmelidir.

1. Çalışma zamanını kaydet
2. Kilit dosyasını incele
3. Yalıtılmış temiz kurulum yap
4. Davranış testini yürüt
5. Sürüm paketini kabul et

Temiz kurulum canlı dizinde yapılacak deneme değildir

npm ci var olan kilit dosyasını kullanır ve manifest ile uyuşmazlıkta onu sessizce güncellemek yerine hata verir. Mevcut node_modules dizinini kaldırabildiği için çalışan uygulamanın canlı dizininde rastgele denenmemelidir. Ayrı ve gözden çıkarılabilir bir çalışma kopyası hazırlayın. Kurulumun çıktısı, kullanılan seçenekler ve hata kodu kayıt altına alınsın. Bir bilgisayardaki eski node_modules içeriğinin başarıyı tesadüfen sağlamasına izin vermeyin.

Kilit dosyası belirli bağımlılık ağacı seçenekleriyle üretilmişse aynı seçeneklerin temiz kurulumda da gerekebileceğini npm belgesinden kontrol edin. Kullanıcıya veya makineye özel gizli ayarlar üzerine kurulan süreç tekrarlanabilir değildir. Paylaşılabilir proje ayarlarını sürümleyin; kimlik bilgilerini dışarıda tutun. Dosyanın değişmediğini görmek yararlı bir kontroldür; kurulumun bütün yan etkilerinin güvenli olduğunu göstermez.

Kurulum betiklerini bağımsız inceleyin

Bağımlılıkların yaşam döngüsü betikleri kurulum sırasında kod çalıştırabilir. Yalnız paket adı ve sürümüne bakmak bu davranışı açıklamaz. npm sürümünün betik yönetimi seçeneklerini ve projenin gerçekten hangi betiklere ihtiyaç duyduğunu inceleyin. Betikleri kapatmak bazı paketlerin kurulumunu tamamlamamasına yol açabilir; bunu sessizce başarı saymayın. Kontrolsüz betik çalıştırmak da yalnız kurulum hatasını ortadan kaldırdığı için kabul edilmemelidir.

Temiz test ortamına üretim sırlarını vermeyin. Dış hizmet çağrılarını sentetik hedeflere veya sahte uygulamalara yönlendirin. Testler başlamadan kurulumun kendisinin erişim ihtiyacını belirleyin. Güvenlik denetimi çıktısı yardımcı bir girdidir; bilinen açık bulunmaması paketin zararsız veya tedarik zincirinin sağlam olduğunu kanıtlamaz. Yeni alt bağımlılıkları ve beklenmedik kaynak değişikliklerini insan incelemesiyle değerlendirin.

Davranış kabulü ve geri dönüş

Sözdizimi denetimi, anlamlı birim testleri ve uygulamanın kritik iş akışı ayrı sonuçlar üretsin. Bir modülün yüklenmesi ağ, kamera veya ses işlevinin çalıştığını göstermeyebilir. Desteklenen hedef ortamda gerekli işlevleri zararsız örneklerle kontrol edin. Bu yazı kapsamında paket kurulumu veya performans testi yürütülmedi; tarif edilen adımlar uygulanacak kabul planıdır. Sonuç raporuna çalıştırılmamış kontrolü geçmiş gibi eklemeyin.

Geri dönüş için önceki kaynak sürümü, kilit dosyası ve uyumlu çalışma zamanı birlikte korunmalıdır. Yalnız package.json dosyasını geri almak eski bağımlılık ağacını yeniden oluşturmayabilir. Veritabanı şeması veya kalıcı veri değişmişse uygulama geri dönüşü ayrıca planlanır. Yeni paket doğrulanmadan mevcut sağlam paketin üzerine yazmayın. Teslimin değeri komutun sıfır koduyla bitmesinden çok, incelenmiş bağımlılık ağacıyla doğrulanan iş davranışıdır.

Nasıl yapılır: ayrıntılı uygulama

Ortam ve ön koşullar: Node.js / npm kurulum kabulü — Doğru depo commit’i, desteklenen Node/npm ve incelenmiş lock dosyası gerekir.

1. Node, npm ve temiz çalışma ağacını kaydedin
2. Lock ve config uyumunu okuyun
3. Tekrarlanabilir kurulumu yapın
4. Uygulama ve güvenlik incelemesini ayırın
5. Lock takımını ve paketi birlikte geri alın

1. Node, npm ve temiz çalışma ağacını kaydedin

Uygulama kökünde desteklenen Node/npm sürümünü projenin engines/lock dosyasıyla eşleştirin. Paket kurulum script’leri kod çalıştırabilir; yalnız güvenilir incelemeden geçmiş projede ilerleyin.

node --version
npm --version
git status --short
node -p "require('./package.json').engines"

2. Lock ve config uyumunu okuyun

package.json ile package-lock.json aynı commit’ten gelmeli; registry/proxy ve install seçenekleri tutarlı olmalı. npm config list çıktısı sır içerebilir, toplu config dökmeyin.

git diff -- package.json package-lock.json
npm config get registry
npm config get legacy-peer-deps

3. Tekrarlanabilir kurulumu yapın

npm ci mevcut node_modules’u kaldırır ve lock’a sadık kurar; lock yok/uyumsuzsa hata vermesi beklenir. Güvenlik incelemesi için –ignore-scripts seçilirse projenin gerekli native/build adımlarının eksik kalacağı açık değerlendirilir.

npm ci
npm ls --depth=0

4. Uygulama ve güvenlik incelemesini ayırın

package.json içindeki gerçek scripts listesini okuyun; yalnız projede tanımlı test/build komutlarını çalıştırın. Audit bulgusu için otomatik –force fix üretim güncellemesi değildir.

npm run
npm audit --omit=dev

5. Lock takımını ve paketi birlikte geri alın

Önceki package.json/lock ve desteklenen Node/npm sürümüne dönüp npm ci ile tekrar kurun. Lock dosyası bütün bağımlılık kodunun güvenilir olduğunu veya uygulamanın test edildiğini kanıtlamaz.

Beklenen sonuç: Manifest/lock uyumu korunur ve bağımlılıklar tekrarlanabilir biçimde kurulur.

Sonuç farklıysa: npm ci hatasında lock dosyasını rastgele yenilemeyin; manifest farkını inceleyin.

Geri dönüş: Önceki onaylı commit ve lock dosyasına dönüp temiz kurulum yapın.