Node.js Kurulumu, Sürüm Doğrulama ve Sürüm Yöneticileri

Resmî indirme sayfası ve sürüm türleri

Node.js belgelerinin örnek bölümü, işe başlamadan önce Node.js'i indirip kurmanızı ister ve bunun için nodejs.org/en/download sayfasını gösterir. Node-API rehberindeki araçlar sayfası da aynı adresi verir; burada iki önemli bilgi yer alır: yükleyici npm'i de içerir ve LTS (Long Term Support) sürümü en kararlı seçenek olarak önerilir. Üretimde çalışacak bir sunucu ya da uzun yaşayacak bir proje için LTS hattını seçmek bu yüzden mantıklı bir varsayılandır.

Bir sürümün LTS mi yoksa Current mı olduğunu, elinizdeki ikilinin kendisine sorarak da öğrenebilirsiniz. process.release nesnesinin lts özelliği yalnızca LTS sürümlerde bulunur ve o hattın kod adını taşır. Belgeler örnek olarak 14.x hattı için 'Fermium', 16.x için 'Gallium', 18.x için 'Hydrogen' adlarını sayar. Current sürümlerde ve diğer tüm sürüm türlerinde bu özellik undefined olur. Yazının örneklerini çalıştırdığımız v26.13.0 ikilisi 'Lithium' döndürdü, yani bir LTS sürümü.

node -p "process.release.lts ? 'LTS: ' + process.release.lts : 'Current'"
# çıktı: LTS: Lithium

Destek takviminin tarihleri API belgelerinde yer almaz. Bir hattın ne zamana kadar güvenlik güncellemesi alacağını öğrenmek için nodejs.org üzerindeki sürüm sayfasına bakın; tarih ezberlemek yerine her yükseltme kararında oradaki güncel tabloyu kontrol etmek daha güvenlidir.

Kurulumu doğrulamak: node -v ve process nesnesi

Kurulumdan sonra ilk komut node -v (uzun biçimi --version) olmalıdır; Node.js'in sürümünü yazdırır. node -h ise komut satırı seçeneklerinin kısa bir özetini verir; belgeye göre bu çıktı tam CLI belgesinden daha az ayrıntılıdır. Unix benzeri sistemlerde aynı belgeyi man node ile terminalde de okuyabilirsiniz.

node -v
# çıktı: v26.13.0
node -p process.versions.v8
# çıktı: 14.6.202.34-node.40

İkinci komut, Learn sayfasında V8 sürümünü öğrenmenin yolu olarak gösterilen yöntemdir. -p bayrağı verilen ifadeyi değerlendirip sonucu yazar. Aynı bilgileri bir betik içinden de okuyabilirsiniz. Aşağıdaki örnek, bir sunucuya bağlanıp hangi Node.js'in çalıştığını hızlıca görmek istediğinizde kullanabileceğiniz küçük bir tanılama betiğidir:

import process from 'node:process';

console.log(process.version);
console.log(process.versions.node);
console.log(process.versions.v8);
console.log(process.versions.modules, process.versions.napi);
console.log(process.release.name, process.release.lts);
console.log(process.platform, process.arch);
console.log(process.features.typescript);
// çıktı: v26.13.0
// çıktı: 26.13.0
// çıktı: 14.6.202.34-node.40
// çıktı: 147 10
// çıktı: node Lithium
// çıktı: win32 x64
// çıktı: strip

Çıktıyı Windows üzerinde aldık; Linux sunucuda process.platform 'linux' döndürür. Belgeye göre bu değer ikilinin hangi işletim sistemi için derlendiğini gösterir ve olası değerler 'aix', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos' ve 'win32''dir. process.arch de aynı mantıkla derlenen işlemci mimarisini verir ('x64', 'arm64' gibi).

Sürüm yöneticileri: hangisi, ne için?

Sürüm yöneticisi, aynı makinede birden çok Node.js sürümünü kurulu tutmanızı ve aralarında geçiş yapmanızı sağlar; güncellemeleri yönetmeyi de kolaylaştırır. Farklı projeler farklı sürümlerle çalışıyorsa bu araçlar neredeyse zorunlu hâle gelir. Learn sayfasına göre bazı yöneticiler projenin kullandığı sürümü kendiliğinden algılar, bazıları ise elle geçiş yapmanızı bekler. Belgelerde adı geçen yöneticiler şunlardır:

Seçim yaparken önce işletim sisteminize bakın. Adı benzer olsa da nvm ile nvm for windows ayrı projelerdir; birinin belgesindeki komutların diğerinde aynen çalışacağını varsaymayın. Bakımı yapılmayan bir aracı yeni bir kuruluma almak da uzun vadede risk taşır; belgenin volta için düştüğü not bu yüzden önemlidir. Bu araçların komutları Node.js belgelerinde yer almaz, her birinin kendi deposundaki kılavuzu esas alın.

Sürüm değiştirince yerel eklentiler neden bozulur?

C veya C++ ile yazılmış yerel eklentiler (native add-on) belirli bir Node.js ikilisine göre derlenir. Belgeye göre process.versions.modules değeri mevcut ABI sürümünü gösterir ve bu sayı C++ API'si her değiştiğinde artar. Node.js, farklı bir ABI sürümüne göre derlenmiş modülleri yüklemeyi reddeder. Bizim denediğimiz sürümde bu değer 147'dir.

Pratik sonucu şudur: node_modules klasörünü bir sürümde kurup başka bir ana sürüme geçtiğinizde, saf JavaScript paketleri genellikle çalışmaya devam eder ama yerel eklenti içeren paketler yüklenirken hata verebilir. Böyle bir durumda bağımlılıkları yeni sürümle yeniden kurmak gerekir; Learn sayfasındaki npm girişi, package.json bulunan bir projede npm install komutunun tüm bağımlılıkları node_modules altına kurduğunu anlatır. Sürüme bağımlı olmadan yerel kod yazmak isteyenler için Node-API (process.versions.napi) ayrı bir arayüz sunar; Node-API rehberine göre bu arayüz desteklenen tüm Node.js sürümlerinde kararlıdır.

Projenin beklediği sürümü belirtmek: engines alanı

Bir projenin hangi Node.js sürümleriyle uyumlu olduğunu package.json içindeki "engines" alanıyla belirtirsiniz. Learn rehberine göre bu alan hem insanlar hem de makineler için bir uyumluluk göstergesidir; kullanılan paket yöneticisine bağlı olarak uyumsuz sürümde kurulum bir istisnayla durabilir. Bu davranış paket yöneticisine bağlı olduğu için, uygulamanızın kendisi de başlangıçta küçük bir kontrol yapabilir:

{
  "name": "ornek-api",
  "engines": { "node": ">=24" }
}

import { readFileSync } from 'node:fs';
import process from 'node:process';

const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));
const gereken = Number(pkg.engines.node.replace('>=', ''));
const ana = Number(process.versions.node.split('.')[0]);

console.log(`Gereken: ${gereken}+, çalışan: ${ana}`);
if (ana < gereken) {
  console.error('Bu proje için Node.js sürümünüz eski.');
  process.exitCode = 1;
}
// çıktı: Gereken: 24+, çalışan: 26

Örnek bilerek basit tutuldu ve yalnızca >= biçimini anlar; gerçek sürüm aralıklarının tamamını çözmez. Burada process.exit() yerine process.exitCode kullandık, çünkü belgeler çıkış kodunu bu yolla ayarlayıp sürecin kendi kendine bitmesine izin vermeyi önerir. Ayrıntısı process.argv ve çıkış kodları yazısında. package.json alanlarının tamamı için package.json exports ve imports yazısına bakabilirsiniz.

Belgeyi sürümle birlikte okumak: kararlılık etiketleri

Node.js API belgesindeki her modül ve özellik bir kararlılık etiketi taşır. Bu etiketler, kurduğunuz sürümde bir özelliğe ne kadar güvenebileceğinizi gösterdiği için sürüm seçimiyle doğrudan ilgilidir. 0 - Deprecated uyarı üretebilen ve geriye uyumluluğu garanti edilmeyen özellikleri, 1 - Experimental anlamsal sürümleme kurallarına bağlı olmayan ve üretimde önerilmeyen özellikleri, 2 - Stable npm ekosistemiyle uyumun öncelikli olduğu özellikleri, 3 - Legacy ise kaldırılması beklenmeyen ama artık aktif olarak bakımı yapılmayan özellikleri işaret eder.

Deneysel özellikler de kendi içinde üç aşamaya ayrılır: 1.0 erken geliştirme, 1.1 aktif geliştirme (asgari kullanılabilirliğe yaklaşmış) ve 1.2 sürüm adayı (kırıcı değişiklik beklenmiyor ama hâlâ olabilir). Örneğin yukarıdaki betikte gördüğünüz process.features.typescript 1.2 sürüm adayı olarak işaretlidir. Deneysel bir özellik bir sürümde bayrak isteyip sonraki sürümde varsayılan hâle gelebilir; bu yüzden belgeyi okurken her zaman kendi sürümünüzün belgesine bakın.

V8 tarafındaki dil özellikleri için de benzer bir ayrım vardır. Learn rehberine göre V8'in kararlı saydığı (shipping) özellikler Node.js'te varsayılan olarak açıktır ve bayrak istemez. Neredeyse tamamlanmış (staged) özellikler --harmony bayrağı ister; geliştirilmekte olanlar ise ayrı harmony bayraklarıyla açılabilir ama bunlar yalnızca deneme amaçlıdır ve uyarı yapılmadan değişebilir. Üretim ortamında bu bayraklara dayanmamak en güvenli yoldur.

Geliştirme ve üretim için ayrı kurulum gerekir mi?

Hayır. Learn rehberi bunu açıkça söyler: Node.js'te geliştirme ile üretim arasında bir fark yoktur ve üretim için uygulamanız gereken özel bir Node.js ayarı bulunmaz. Ancak npm kayıt defterindeki bazı kütüphaneler NODE_ENV değişkenine bakar ve tanımlı değilse kendilerini geliştirme moduna alır. Rehber bu nedenle Node.js'i her zaman NODE_ENV=production ile çalıştırmayı önerir.

Aynı rehber, kodunuzun içinde NODE_ENV değerine göre farklı davranışlar yazmayı bir anti-desen olarak tanımlar. Staging ile üretim ortamı farklı kod yolları çalıştırırsa, testte geçen bir özelliğin üretimde bozulması mümkün olur. Ortam ayarlarının nasıl taşınacağı konusunda process.env ve --env-file yazısına bakabilirsiniz.

Sık yapılan hatalar

• İki kurulumu karıştırmak: Hem sistem paketinden hem sürüm yöneticisinden Node.js kurulduğunda terminal hangisini önce bulursa onu çalıştırır. node -p process.execPath ile gerçek yolu kontrol edin.
• Sürüm değiştirip bağımlılıkları yenilememek: Farklı ABI sürümüne göre derlenmiş yerel eklentiler yüklenmez. Ana sürüm değişikliğinden sonra bağımlılıkları yeniden kurun.
• Deneysel bir özelliğe üretimde güvenmek: Kararlılık etiketi 1 olan özellikler semver dışındadır; sürüm yükseltmesinde davranışları değişebilir.
• engines alanını yazmamak: Projenin beklediği sürüm belirtilmezse, eski sürümle çalışan bir ekip arkadaşı ya da sunucu anlaşılması zor hatalarla karşılaşır.
• Desteklenmeyen platform denetimini kapatmak: NODE_SKIP_PLATFORM_CHECK=1 başlangıçtaki platform denetimini atlar; belgeye göre bu durumda Node.js doğru çalışmayabilir ve desteklenmeyen platformlardaki sorunlar düzeltilmez.

Sık Sorulan Sorular

LTS mi Current mı kurmalıyım?

Üretimde çalışacak uygulamalar için resmî araçlar sayfası LTS hattını en kararlı seçenek olarak önerir. Yeni özellikleri denemek istiyorsanız Current sürümü ayrı bir ortamda kullanabilirsiniz. Hangi sürümün hangi tür olduğunu process.release.lts ile kontrol edebilirsiniz.

npm'i ayrıca kurmam gerekir mi?

Resmî yükleyici npm'i de içerir. npm'in kendi komutları Node.js belgelerinin kapsamında değildir; ayrıntılar için docs.npmjs.com adresine bakın. Learn sayfası Yarn ve pnpm'i de npm'e alternatif olarak anar.

Node.js'in hangi V8 sürümünü kullandığını nasıl öğrenirim?

node -p process.versions.v8 komutu yeterlidir. process.versions nesnesi V8'in yanı sıra OpenSSL, ICU, libuv gibi bağımlılıkların sürümlerini de listeler; bizim sürümümüzde nesnede 31 alan vardı.

Sürüm yöneticisi kullanmak zorunlu mu?

Değil. Tek bir proje ve tek bir sürümle çalışıyorsanız resmî yükleyici yeterlidir. Farklı projeler farklı sürümler istiyorsa veya sürüm yükseltmelerini önce denemek istiyorsanız bir sürüm yöneticisi işinizi kolaylaştırır.

Kurduktan sonra ilk ne yapmalıyım?

Sürümü doğruladıktan sonra bir betik çalıştırmayı ve REPL'i denemeyi öğrenin: node komutuyla betik çalıştırma ve Node.js REPL kullanımı yazıları bu adımları anlatır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Node.js öğrenme rehberi · Node.js nedir · Betik çalıştırma · process.argv ve çıkış kodları · package.json alanları · Node.js 26 yenilikleri · Dockerfile yazma rehberi