Windows’ta Node.js ve NPM Nasıl Kurulur ve Yapılandırılır

Node.js, JavaScript kodunu bir tarayıcı dışında çalıştıran, Chrome’un V8 motoru üzerine inşa edilmiş açık kaynaklı, çapraz platform bir JavaScript çalışma ortamıdır. NPM (Node Package Manager), Node.js ile birlikte gelen varsayılan paket yöneticisidir ve iki milyondan fazla yeniden kullanılabilir pakete erişim sağlar. Birlikte, Windows üzerinde sunucu tarafı uygulamalar, CLI araçları, REST API’ler ve tam yığın JavaScript projeleri oluşturmak için temel araç zincirini oluştururlar.

Bu kılavuz, Windows üzerinde Node.js ve NPM için eksiksiz kurulum, doğrulama, yapılandırma ve ilk uygulama iş akışını kapsamaktadır — sürüm yönetimi, PATH sorun giderme, global ve yerel paket kapsamı ile çoğu öğreticinin atladığı üretim düzeyindeki konular dahil.

Kurulumdan Önce Doğru Node.js Sürümünü Seçmek

Node.js sürüm takvimi, seçiminizi doğrudan etkileyen öngörülebilir bir ritmi takip eder:

LTS sürümleri çift ana sürüm numaraları taşır (örn. 20.x, 22.x) ve 30 ay boyunca kritik güvenlik yamaları alır. Güncel sürümler tek ana sürüm numaraları taşır ve kararlılık kriterlerini karşılamaları halinde altı ay sonra LTS statüsüne geçer.

Çoğu geliştirici ve sunucu dağıtımı için — VPS Hosting üzerinde barındırılan uygulamalar dahil — LTS doğru seçimdir. Güncel dal, yalnızca aktif LTS hattına henüz gelmemiş bir V8 özelliğine veya Node.js API’sine özellikle ihtiyaç duyduğunuzda uygundur.

Windows için NVM: Doğrudan Kuruluma Profesyonel Alternatif

MSI yükleyicisiyle devam etmeden önce, nvm-for-windows‘a (Windows için Node Version Manager) ihtiyaç duyup duymadığınızı değerlendirin. Doğrudan yükleyici sisteminizi tek bir Node.js sürümüne bağlar. NVM, birden fazla sürümü yan yana kurmanıza ve proje bazında aralarında geçiş yapmanıza olanak tanır — eski kod tabanlarını modern olanlarla birlikte yönetirken bu kritik öneme sahiptir.

nvm-for-windows’u resmi GitHub sürümler sayfasından yükleyin, ardından şunu kullanın:

“`

nvm install 20.14.0

nvm use 20.14.0

nvm list

“`

Tek bir proje yönetiyorsanız veya Node.js’i ilk kez öğreniyorsanız, MSI yükleyicisi yeterlidir. Profesyonel ortamlar için NVM kesinlikle önerilir.

Adım 1: Node.js Yükleyicisini İndirin

1. nodejs.org adresindeki resmi Node.js web sitesine gidin.
2. LTS sekmesini seçin ve mimarinize uygun Windows Yükleyicisini (`.msi`) indirin. Modern Windows makinelerinin neredeyse tamamı 64 bit’tir (`node-v20.x.x-x64.msi`). ARM64 derlemeleri, Windows on ARM cihazlar için mevcuttur.
3. Yükleyiciyi çalıştırmadan önce, indirilen dosyanın SHA-256 sağlama toplamını Node.js indirme sayfasında yayımlanan değerlerle karşılaştırarak doğrulayın. Bu adım, güvenlik bilincine sahip her ortamda zorunludur.

PowerShell’de sağlama toplamını doğrulamak için:

“`powershell

Get-FileHash .node-v20.14.0-x64.msi -Algorithm SHA256

“`

Çıktıyı yayımlanan hash ile karşılaştırın. Uyuşmazlık, bozuk veya değiştirilmiş bir indirmeye işaret eder.

Adım 2: Node.js ve NPM’yi Kurun

1. Kurulum Sihirbazını başlatmak için indirilen `.msi` dosyasına çift tıklayın.
2. Karşılama ekranında İleri‘ye tıklayın.
3. Son Kullanıcı Lisans Sözleşmesini kabul edin ve İleri‘ye tıklayın.
4. Varsayılan kurulum yolu `C:Program Filesnodejs`’dir. Bunu değiştirmek için özel bir nedeniniz yoksa (örn. disk alanı yönetimi için sistem dışı bir sürücü), olduğu gibi bırakın.
5. Özel Kurulum ekranında, npm package manager‘ın seçili olduğunu onaylayın. Varsayılan olarak etkindir.
6. Yerel Modüller için Araçlar ekranında, Chocolatey, Python ve Visual Studio Build Tools’u otomatik olarak yüklemek için bir seçenek göreceksiniz. Yerel C++ eklentileri içeren NPM paketleri yüklemeyi öngörüyorsanız bu kutuyu işaretleyin (örn. `bcrypt`, `sharp`, `node-gyp` bağımlı paketler). Bu adım birkaç gigabayt araç yükler — yalnızca saf JavaScript paketlerine ihtiyaç duyuyorsanız atlayın.
7. Yükle‘ye, ardından Son‘a tıklayın.

Yükleyici, `node.exe` ve `npm.cmd`’yi otomatik olarak `C:Program Filesnodejs` altındaki sistem `PATH` ortam değişkenine kaydeder.

Yükleyicinin Sisteminizde Gerçekte Yaptıkları

Yan etkileri anlamak, gelecekteki hata ayıklama baş ağrılarını önler:

• `C:Program Filesnodejs`’yi Sistem PATH‘ine ekler (tüm kullanıcılar için kullanılabilir).
• Varsayılan global paket öneki olarak `C:Users<username>AppDataRoamingnpm`’yi oluşturur.
• Node.js’i Windows kayıt defterine `HKLMSOFTWARENode.js` altında kaydeder.
• `npx`’yi (NPM paket çalıştırıcısı) `npm` ile birlikte yükler.

Adım 3: Kurulumu Doğrulayın

Yeni bir Komut İstemi veya PowerShell penceresi açın. “Yeni” niteleyicisi önemlidir — mevcut terminal oturumları eski PATH’i önbelleğe alır ve yükleyicinin değişikliklerini yansıtmaz.

“`

node -v

“`

Beklenen çıktı: `v20.14.0` (veya yüklü sürümünüz)

“`

npm -v

“`

Beklenen çıktı: `10.x.x`

“`

npx -v

“`

Beklenen çıktı: npm sürümüyle eşleşir veya yakındır

`node` tanınmıyorsa, PATH doğru güncellenmemiştir. Manuel olarak düzeltin:

1. Sistem Özellikleri > Gelişmiş > Ortam Değişkenleri‘ni açın.
2. Sistem değişkenleri altında `Path`’i bulun ve Düzenle‘ye tıklayın.
3. Yoksa `C:Program Filesnodejs`’yi ekleyin.
4. Tamam‘a tıklayın, tüm terminal pencerelerini kapatın ve yeniden açın.

Yaygın Kurulum Sonrası Sorunları Teşhis Etmek

Sorun: `npm` tanınıyor ancak `node` tanınmıyor (veya tam tersi).

Neden: Kısmi bir PATH girişi veya Chocolatey ya da önceki bir NVM kurulumundan kaynaklanan çakışan bir kurulum.

Çözüm: Hangi ikili dosyaların çözümlendiğini belirlemek için `where node` ve `where npm`’yi çalıştırın. Eski girişleri kaldırın.

Sorun: `npm install -g` çalıştırılırken `EACCES` izin hataları.

Neden: Global önek dizini, mevcut kullanıcı için yazma iznine sahip değil.

Çözüm: Global öneki kullanıcıya ait bir dizinle değiştirin (Adım 5’te ele alınmıştır).

Sorun: `node`, Node.js’i çalıştırmak yerine Microsoft Store’u açıyor.

Neden: Windows 10/11, `node` için Store’a yönlendiren bir Uygulama Yürütme Takma Adıyla birlikte gelir.

Çözüm: Ayarlar > Uygulamalar > Uygulama yürütme takma adları‘na gidin ve `python.exe` ile `node.exe` için takma adları devre dışı bırakın (varsa).

Adım 4: NPM’yi En Son Sürüme Güncelleyin

Bir Node.js yükleyicisiyle birlikte gelen NPM sürümü genellikle güncel sürümün bir veya iki küçük sürüm gerisindedir. Kurulumdan hemen sonra güncelleyin:

“`

npm install -g npm@latest

“`

`-g` bayrağı, paketi sistem genelinde kullanılabilir kılarak global önek dizinine yükler. Güncellemeden sonra yeniden doğrulayın:

“`

npm -v

“`

Önemli uç durum: Windows’ta NPM’yi global olarak güncellemek, zaman zaman `C:Program Filesnodejs`’de eski bir `npm.cmd` bırakabilir; bu, eski sürüme işaret ederken yeni sürüm `C:Users<username>AppDataRoamingnpm`’e yüklenir. Güncellemeden sonra `npm -v` hâlâ eski sürümü gösteriyorsa, PATH’te hangi ikili dosyanın önce geldiğini kontrol edin:

“`

where npm

“`

`AppDataRoamingnpm` altındaki yol, çıktıda `C:Program Filesnodejs`’den önce görünmelidir. Görünmüyorsa, PATH girişlerini buna göre yeniden sıralayın.

Adım 5: NPM’yi Ortamınız İçin Yapılandırın

NPM’nin yapılandırması, üç düzeyde bulunabilen bir `.npmrc` dosyasında saklanır: proje başına, kullanıcı başına (`C:Users<username>.npmrc`) ve global (`C:Program Filesnodejsnode_modulesnpmnpmrc`). Proje başına ayarlar, kullanıcı başına ayarları geçersiz kılar; kullanıcı başına ayarlar ise global ayarları geçersiz kılar.

Global Paket Önekini Değiştirin

Varsayılan global önek (`AppDataRoamingnpm`) çoğu kullanıcı için işe yarar, ancak paylaşılan sunucularda veya disk kotaları uygulandığında yeniden yönlendirmek isteyebilirsiniz:

“`

npm config set prefix "D:NodeGlobal"

“`

Öneki değiştirdikten sonra, yeni `bin` alt dizinini PATH’inize ekleyin:

“`

setx PATH "%PATH%;D:NodeGlobal"

“`

Özel veya Ayna Kayıt Defteri Yapılandırın

Kurumsal ortamlar ve hava boşluklu sunucular sıklıkla özel bir NPM kayıt defteri kullanır (Verdaccio, Nexus, Artifactory):

“`

npm config set registry "https://your-private-registry.example.com/"

“`

Özel bir kayıt defterine karşı kimlik doğrulamak için:

“`

npm login –registry=https://your-private-registry.example.com/

“`

Yalnızca kapsamlı paketler için (örn. `@mycompany/*`), genel kayıt defterini olduğu gibi bırakırken yalnızca o kapsamı özel bir kayıt defterine yönlendirebilirsiniz:

“`

npm config set @mycompany:registry "https://your-private-registry.example.com/"

“`

HTTP Proxy Yapılandırın

Windows makineniz kurumsal bir proxy’nin arkasındaysa:

“`

npm config set proxy "http://proxy.company.com:8080"

npm config set https-proxy "http://proxy.company.com:8080"

“`

Tüm Mevcut Ayarları Denetleyin

“`

npm config list

npm config list –json

“`

`–json` bayrağı, betik yazma ve CI/CD boru hattı tanılamaları için kullanışlı olan makine tarafından okunabilir yapılandırma çıktısı üretir.

Kullanışlı NPM Yapılandırma Referansı

Adım 6: Node.js Uygulaması Oluşturun ve Çalıştırın

Projeyi Başlatın

“`

mkdir my-node-app

cd my-node-app

npm init -y

“`

`npm init -y`, dizin adından ve NPM kullanıcı yapılandırmanızdan türetilen varsayılanlarla bir `package.json` oluşturur. `package.json` dosyası, uygulamanızın manifestosudur — giriş noktasını, betikleri, bağımlılıkları ve meta verileri tanımlar.

Temel Bir HTTP Sunucusu Oluşturun

Proje dizininde `app.js` oluşturun:

“`javascript

// app.js

const http = require('http');

const hostname = '127.0.0.1';

const port = 3000;

const server = http.createServer((req, res) => {

res.statusCode = 200;

res.setHeader('Content-Type', 'text/plain');

res.end('Hello, World!n');

});

server.listen(port, hostname, () => {

console.log(`Server running at http://${hostname}:${port}/`);

});

“`

Çalıştırın:

“`

node app.js

“`

Tarayıcınızda `http://127.0.0.1:3000/`’e gidin. `Hello, World!` görmelisiniz.

Teknik not: Node.js, I/O işlemleri için libuv tarafından desteklenen tek iş parçacıklı bir olay döngüsü kullanır. `http.createServer` geri çağrısı, döngüyü engellemeden her gelen istekte tetiklenir. Bu mimari, Node.js’i I/O’ya bağlı iş yükleri için son derece verimli kılar, ancak işçi iş parçacıkları veya alt süreçler olmadan CPU yoğun görevler için uygun değildir.

Express Çerçevesini Ekleyin

Express, Node.js için fiili standart HTTP çerçevesidir; yönlendirme, ara yazılım desteği ve temiz bir istek/yanıt soyutlaması sağlar:

“`

npm install express

“`

Bu, Express’i yerel olarak (`node_modules/`’e) yükler ve `package.json`’de bir bağımlılık olarak kaydeder. `app.js`’yi güncelleyin:

“`javascript

const express = require('express');

const app = express();

const port = 3000;

app.get('/', (req, res) => {

res.send('Hello from Express!');

});

app.listen(port, () => {

console.log(`Server running at http://localhost:${port}`);

});

“`

“`

node app.js

“`

Yanıtı onaylamak için `http://localhost:3000/`’i ziyaret edin.

`node_modules` ve `.gitignore`’yi Anlamak

`node_modules` dizini yüzlerce megabayt dosya içerebilir. Asla sürüm kontrolüne eklemeyin. Bir `.gitignore` dosyası oluşturun:

“`

node_modules/

.env

“`

İş arkadaşları ve dağıtım boru hatları, tam bağımlılık ağacını yeniden oluşturmak için `package.json` ve `package-lock.json`’yi okuyan `npm install`’yi çalıştırarak bağımlılıkları geri yükler.

Adım 7: Paketleri Yönetmek — Yerel ve Global

Yerel ve global paket kurulumu arasındaki farkı anlamak, Node.js yeni başlayanları için en yaygın karışıklık kaynaklarından biridir.

Temel kural: Bir paket her yerde kullanılabilir olmasını istediğiniz bir komut satırı aracı sağlıyorsa (örn. `nodemon`, `eslint`, `typescript`), global olarak yükleyin. Uygulamanızın `require()` veya `import` ile içe aktardığı bir kütüphaneyse, yerel olarak yükleyin.

PM2 ile Uygulamaları Üretimde Çalıştırmak

Bir sunucuya dağıtılan herhangi bir Node.js uygulaması için — ister bir VPS Hosting örneğinde ister bir Dedicated Server‘da olsun — `node app.js`’yi doğrudan çalıştırmak yetersizdir. Terminal kapanırsa veya işlenmemiş bir istisna oluşursa süreç sonlanır.

PM2, Node.js için üretimdeki standart süreç yöneticisidir:

“`

npm install -g pm2

pm2 start app.js –name "my-app"

pm2 startup

pm2 save

“`

`pm2 startup`, sistem yeniden başlatıldığında uygulamanızı otomatik olarak yeniden başlatmak için PM2’yi yapılandıracak bir komut oluşturur. `pm2 save` ise mevcut süreç listesini kalıcı hale getirir.

Adım 8: Güvenlik Sertleştirme ve Denetim

Bağımlılık Denetimi Çalıştırın

“`

npm audit

“`

NPM, yüklü paketlerinizi GitHub Danışma Veritabanı ile çapraz referanslar. Bilinen güvenlik açıkları, önem düzeyleriyle (düşük, orta, yüksek, kritik) ve düzeltme yollarıyla birlikte raporlanır.

“`

npm audit fix

“`

Bu, savunmasız paketleri en yakın kırılmayan yamalı sürüme otomatik olarak yükseltir. Kırıcı değişiklikler için çıktıyı inceleyin ve manuel olarak yükseltin.

Bağımlılık Sürümlerini Sabitleyin

`package.json`’de NPM, varsayılan olarak anlamsal sürümleme aralıkları kullanır (`^1.2.3` küçük ve yama güncellemelerine izin verir). Üretimde, tedarik zinciri sürprizlerini önlemek için tam sürümleri sabitleyin:

“`

npm config set save-exact true

“`

Ya da `package.json`’deki `^` öneklerini manuel olarak tam sürüm dizeleriyle değiştirin ve `package-lock.json` dosyasını işleyin.

NPM’yi Yönetici Olarak Çalıştırmaktan Kaçının

`npm install -g`’yi yükseltilmiş ayrıcalıklarla çalıştırmak, Yönetici hesabına ait dosyalar yazar; bu durum, sonraki yükseltilmemiş işlemler için izin hatalarına neden olabilir. Yükseltilmiş ayrıcalıklara olan ihtiyacı tamamen ortadan kaldırmak için kullanıcıya ait bir global önek yapılandırın (bkz. Adım 5).

Node.js Uygulamalarını Sunucuya Dağıtmak

Yerel geliştirme yalnızca ilk aşamadır. Üretim dağıtımı ek gereksinimler getirir: süreç yönetimi, ters proxy, TLS sonlandırma ve ortam değişkeni yönetimi.

Linux VPS Hosting örneğindeki tipik bir üretim yığını, Node.js’i ters proxy olarak Nginx ile eşleştirir. Nginx, TLS sonlandırmasını (SSL Sertifikaları gibi bir sağlayıcıdan alınan sertifikaları kullanarak) üstlenir ve istekleri yerel bir portta dinleyen Node.js sürecine iletir.

Yönetilen bir kontrol paneli ortamını tercih eden ekipler için, cPanel ile VPS, doğrudan SSH yapılandırması gerektirmeden dağıtımı basitleştirerek cPanel arayüzü üzerinden Node.js uygulama yönetimi sağlar.

Ortama özgü yapılandırma (veritabanı kimlik bilgileri, API anahtarları, port numaraları) asla sabit kodlanmamalıdır. `dotenv` paketiyle bir `.env` dosyası kullanın:

“`

npm install dotenv

“`

“`javascript

require('dotenv').config();

const port = process.env.PORT || 3000;

“`

Karar Matrisi: Her Kurulum Yöntemini Ne Zaman Kullanmalı

Temel Teknik Çıkarımlar

• Üretim ve ekip ortamları için her zaman LTS sürümünü yükleyin. Güncel sürümü yalnızca belirli bir V8 veya Node.js API özelliğine ihtiyaç duyduğunuzda kullanın.
• Birden fazla Node.js sürümünün bir arada bulunması gereken her ortamda nvm-for-windows kullanın.
• Çalıştırmadan önce yükleyicinin SHA-256 sağlama toplamını doğrulayın.
• İzin hatalarını önlemek ve yükseltilmiş ayrıcalıklara olan ihtiyacı ortadan kaldırmak için global NPM önekini kullanıcıya ait bir dizinle değiştirin.
• `node_modules/`’yi asla sürüm kontrolüne eklemeyin. `package-lock.json`’yi her zaman işleyin.
• Üretim boru hatlarında her `npm install`’den sonra `npm audit`’yi çalıştırın.
• Herhangi bir sunucu dağıtımında süreç yönetimi için PM2 kullanın — üretimde asla doğrudan `node app.js` çalıştırmayın.
• Daha iyi performans ve sertifika yönetimi için TLS’yi Node.js süreci içinde değil, ters proxy katmanında (Nginx, Caddy) sonlandırın.
• Sırları kaynak kodda değil, `dotenv` aracılığıyla yüklenen ortam değişkenlerinde saklayın.

Sıkça Sorulan Sorular

Windows’ta Node.js LTS ve Güncel arasındaki fark nedir?

LTS sürümleri, 30 ay boyunca güvenlik ve kararlılık yamaları alır ve çift ana sürüm numaraları taşır (18, 20, 22). Güncel sürümler en son dil ve çalışma zamanı özelliklerini içerir, ancak LTS’ye geçmeden veya bırakılmadan önce yalnızca altı ay desteklenir. Üretim Windows dağıtımları için her zaman LTS kullanın.

Windows’ta `npm install -g` neden izin hatasıyla başarısız oluyor?

Varsayılan global önek (`C:Users<username>AppDataRoamingnpm`), UAC politikaları veya Yönetici olarak çalıştırılan önceki kurulumlar nedeniyle zaman zaman yazma iznine sahip olmayabilir. Çözüm, terminali Yönetici olarak çalıştırmak (uzun vadede önerilmez) veya `npm config set prefix "C:yourpath"` ile global öneki kullanıcı hesabınızın sahip olduğu bir dizinle yeniden yapılandırmaktır.

Windows’ta birden fazla Node.js sürümünü aynı anda çalıştırabilir miyim?

Evet, nvm-for-windows kullanarak. Yükleyin, ardından aktif çalışma ortamını değiştirmek için `nvm install <version>` ve `nvm use <version>`’yi kullanın. Her sürüm kendi global paket dizinini korur, bu da sürümler arası çakışmaları önler.

`package-lock.json` nedir ve işlemeli miyim?

`package-lock.json`, `npm install` sırasında çözümlenen tüm bağımlılık ağacının tam ve deterministik bir kaydıdır. Her geliştiricinin ve her CI/CD çalışmasının özdeş paket sürümleri yüklemesini sağlar. Her zaman sürüm kontrolüne işleyin ve asla manuel olarak düzenlemeyin.

Sunucu olmadan bir Node.js uygulamasını Windows başlangıcında otomatik olarak nasıl çalıştırabilirim?

Geliştirme makineleri için `pm2 startup` ve `pm2 save` ile PM2 kullanın. Windows Hizmeti entegrasyonu için `node-windows` gibi araçlar, bir Node.js sürecini yerel bir Windows Hizmeti olarak sarar; bu sayede Hizmetler MMC ek bileşeni aracılığıyla yönetim ve hata ya da yeniden başlatmada otomatik yeniden başlatma sağlanır.