Ubuntu’da Node.js için NVM Nasıl Kurulur: Eksiksiz Teknik Rehber

NVM (Node Version Manager), kök ayrıcalıkları gerektirmeden veya sistem genelindeki yolları değiştirmeden tek bir makinede birden fazla izole Node.js çalışma zamanı ortamı yükleyen ve yöneten POSIX uyumlu bir kabuk betiğidir. Her Node.js sürümü `~/.nvm/versions/node/` altında kendi dizininde bulunur ve projeler arasında tam, çakışmasız izolasyon sağlar.

Bu kılavuz, Ubuntu (20.04, 22.04 ve 24.04) üzerinde üretim kalitesinde bir NVM kurulumunu ele almakta olup yalnızca temel komutları değil, aynı zamanda kabuk profili özel durumlarını, `.nvmrc` iş akışı otomasyonunu, global paket geçişini ve çoğu öğreticinin atladığı sunucuya özgü tuzakları da kapsamaktadır.

Sistem Paket Yöneticisi Yerine Neden NVM

Node.js’i `apt` aracılığıyla yüklemek, `/usr/bin/node` konumuna tek, sistem genelinde geçerli bir ikili dosya yerleştirir. Bunu yükseltmek, ana makinedeki her uygulamayı aynı anda etkiler. Paylaşılan bir geliştirme makinesinde veya birden fazla Node.js projesi çalıştıran bir VPS‘te bu durum, kırılgan ve yeniden oluşturulması zor ortamlar yaratır.

NVM, her Node.js sürümünü kullanıcı alanı dizinine yükleyerek ve `PATH`’ı kabuk düzeyinde değiştirerek bu sorunu çözer. Sonuç, işletim sisteminin paket durumu üzerinde sıfır etkiyle kullanıcı başına, proje başına sürüm kontrolüdür.

NVM ile Diğer Node.js Sürüm Yöneticilerinin Karşılaştırması

NVM, en geniş belgeleme ve ekosistem desteğine sahip seçenek olmaya devam etmekte olup ham başlatma hızından çok yeniden üretilebilirliğin önemli olduğu ekipler ve sunucu ortamları için en güvenli varsayılan seçenektir.

Ön Koşullar

• Ubuntu 20.04, 22.04 veya 24.04 (masaüstü veya sunucu)
• `sudo` ayrıcalıklarına sahip kök olmayan bir kullanıcı hesabı
• `curl` veya `wget` yüklü (her ikisi de çoğu Ubuntu imajında varsayılan olarak mevcuttur)
• Bash veya Zsh hakkında temel bilgi

Başlamadan önce kabuğunuzu ve Ubuntu sürümünüzü doğrulamak için:

“`bash

echo $SHELL

lsb_release -a

“`

Adım 1: Sistem Paket Dizinini Güncelleyin

Oturum sırasında çözümlenen bağımlılıkların güncel olduğundan emin olmak için APT paket listelerini yenileyin:

“`bash

sudo apt-get update && sudo apt-get upgrade -y

“`

Ayrıca `curl`’ın mevcut olduğunu doğrulayın:

“`bash

curl –version || sudo apt-get install -y curl

“`

Adım 2: NVM Kurulum Betiğini İndirin ve Çalıştırın

Resmi NVM yükleyicisi GitHub’da barındırılmaktadır. NVM deposunu `~/.nvm` konumuna klonlar ve gerekli kabuk başlatma bloğunu profil dosyanıza ekler.

Seçenek A — curl kullanarak (önerilen):

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Seçenek B — wget kullanarak:

“`bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Çalıştırmadan önce her zaman NVM GitHub sürümler sayfasındaki en son sürüm etiketini doğrulayın. Daha yeni bir sürüm yayınlanmışsa `v0.40.1`’ı mevcut kararlı etiketle değiştirin.

Yükleyicinin gerçekte yaptıkları:

1. NVM deposunu `~/.nvm` konumuna klonlar
2. Etkin kabuğunuzu (`bash`, `zsh`, `ksh` veya `fish`) algılar
3. Aşağıdaki başlatma bloğunu uygun profil dosyasına (`~/.bashrc`, `~/.zshrc`, `~/.profile` veya `~/.bash_profile`) ekler

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

“`

Güvenlik notu: Uzak bir betiği doğrudan `bash`’a aktarmak yaygın bir kalıptır ancak doğası gereği risk taşır. Üretim sunucuları veya dedicated server ortamları için önce betiği indirin, inceleyin, ardından çalıştırın:

“`bash

curl -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh

cat install_nvm.sh # review before running

bash install_nvm.sh

“`

Adım 3: Mevcut Kabuk Oturumunda NVM’yi Etkinleştirin

Yükleyici profilinizi değiştirir, ancak bu değişiklikler yalnızca yeni kabuk oturumlarında geçerli olur. Yeni bir terminal açmadan NVM’yi hemen etkinleştirmek için:

Bash için:

“`bash

source ~/.bashrc

“`

Zsh için:

“`bash

source ~/.zshrc

“`

Manuel kaynak yükleme (herhangi bir kabukta çalışır):

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

“`

Yaygın Tuzak: Etkileşimli Olmayan Kabuklarda Profil Dosyasının Kaynak Yüklenmemesi

Ubuntu’da `~/.bashrc` yalnızca etkileşimli oturum açmayan kabuklar için kaynak yüklenir. SSH üzerinden bağlanıyorsanız (bir oturum açma kabuğu), Bash bunun yerine `~/.bash_profile` veya `~/.profile`’ı okur. SSH girişinden sonra NVM bulunamazsa, kaynak yükleme bloğunu `~/.bash_profile`’a ekleyin:

“`bash

echo 'source ~/.bashrc' >> ~/.bash_profile

source ~/.bash_profile

“`

Bu, uzak sunucularda NVM yapılandırılırken en sık karşılaşılan sorunlardan biridir.

Adım 4: NVM Kurulumunu Doğrulayın

“`bash

nvm –version

“`

Beklenen çıktı (sürüm numarası değişebilir):

“`

0.40.1

“`

Komut `nvm: command not found` döndürürse, kabuk profili doğru şekilde kaynak yüklenmemiştir. Adım 3’teki kaynak yükleme komutunu yeniden çalıştırın ve başlatma bloğunun profil dosyanızda mevcut olduğunu doğrulayın:

“`bash

grep -n 'NVM_DIR' ~/.bashrc

“`

Adım 5: NVM Kullanarak Node.js Yükleyin

En Son LTS Sürümünü Yükleyin (Üretim için Önerilen)

“`bash

nvm install –lts

“`

`–lts` bayrağı, 30 ay boyunca güvenlik yamaları alan en son Uzun Vadeli Destek sürümünü yükler. cPanel’li VPS veya herhangi bir sunucu ortamındaki üretim iş yükleri için LTS, mevcut sürüme kıyasla kesinlikle tercih edilir.

En Son Sürümü Yükleyin

“`bash

nvm install node

“`

Belirli Bir Sürümü Yükleyin

“`bash

nvm install 20.14.0

“`

Mevcut Tüm Uzak Sürümleri Listeleyin

“`bash

nvm ls-remote

“`

Yalnızca LTS sürümlerini filtrelemek için:

“`bash

nvm ls-remote –lts

“`

Adım 6: Etkin Node.js ve npm Sürümlerini Doğrulayın

“`bash

node -v

npm -v

“`

Sistem genelinde bir Node.js kurulumu kullanmadığınızdan emin olmak için ikili dosya yolunu da doğrulayın:

“`bash

which node

Expected: /home/<username>/.nvm/versions/node/v20.14.0/bin/node

“`

Adım 7: Birden Fazla Node.js Sürümünü Yönetin

Yerel Olarak Yüklü Tüm Sürümleri Listeleyin

“`bash

nvm ls

“`

Örnek çıktı:

“`

-> v20.14.0

v18.20.3

v16.20.2

default -> lts/* (-> v20.14.0)

node -> stable (-> v20.14.0) (default)

lts/* -> lts/iron (-> v20.14.0)

“`

Sürümler Arasında Geçiş Yapın

“`bash

nvm use 18.20.3

“`

Bu değişiklik yalnızca mevcut terminal oturumu için geçerlidir. Yeni bir terminal açmak varsayılan takma ada geri döner.

Şu Anda Hangi Sürümün Etkin Olduğunu Kontrol Edin

“`bash

nvm current

“`

Adım 8: Kalıcı Varsayılan Node.js Sürümünü Ayarlayın

Belirli bir sürümü tüm yeni kabuk oturumları için varsayılan yapmak için:

“`bash

nvm alias default 20.14.0

“`

Belirli bir yama sürümü yerine bir sürüm satırına da takma ad verebilirsiniz; bu, o satır içindeki güncellemeleri otomatik olarak takip eder:

“`bash

nvm alias default lts/*

“`

Adım 9: `.nvmrc` ile Sürüm Geçişini Otomatikleştirin

Bu, NVM’nin en güçlü ve az kullanılan özelliklerinden biridir. Proje kök dizininize gerekli Node.js sürümünü içeren bir `.nvmrc` dosyası yerleştirin:

“`bash

echo "20.14.0" > /path/to/your/project/.nvmrc

“`

Ardından, o dizine `cd` ile girdiğinizde:

“`bash

nvm use

Found '/path/to/your/project/.nvmrc' with version <20.14.0>

Now using node v20.14.0

“`

Dizin Değişikliğinde Otomatik Sürüm Geçişi

`.nvmrc` dosyası içeren bir dizine girdiğinizde `nvm use`’ı otomatik olarak tetiklemek için `~/.bashrc` (veya `~/.zshrc`) dosyanıza aşağıdakini ekleyin:

Bash için:

“`bash

cdnvm() {

command cd "$@" || return $?

nvm_path="$(nvm_find_up .nvmrc | command tr -d 'n')"

if [[ ! $nvm_path = *[^[:space:]]* ]]; then

declare default_version

default_version="$(nvm version default)"

if [[ $default_version == "N/A" ]]; then

nvm use default

elif [[ $(nvm current) != "$default_version" ]]; then

nvm use default

fi

elif [[ -r "$nvm_path/.nvmrc" && -r "$nvm_path" ]]; then

declare nvm_version

nvm_version=$(<"$nvm_path/.nvmrc")

declare locally_resolved_nvm_version

locally_resolved_nvm_version="$(nvm ls –no-colors "$nvm_version" | command tail -1 | command tr -d '->*' | command tr -d '[:space:]')"

if [[ "$locally_resolved_nvm_version" == "N/A" ]]; then

nvm install "$nvm_version"

elif [[ $(nvm current) != "$locally_resolved_nvm_version" ]]; then

nvm use "$nvm_version"

fi

fi

}

alias cd='cdnvm'

“`

Bu kalıp, özellikle farklı çalışma zamanı gereksinimleri olan projeler üzerinde çalışan birden fazla geliştiricinin bulunduğu CI/CD hatlarında ve ekip ortamlarında son derece değerlidir.

Adım 10: Sürümler Arasında Global npm Paketlerini Yönetin

NVM tarafından yüklenen her Node.js sürümünün, global olarak yüklenen paketler için kendi izole `node_modules` dizini vardır. Bu, `v18` altında global olarak yüklenen `pm2`, `yarn` veya `typescript` gibi araçların `v20` altında kullanılamayacağı anlamına gelir.

Etkin Sürüm için Global Paket Yükleyin

“`bash

npm install -g yarn

npm install -g pm2

npm install -g typescript

“`

Yeni Sürüm Yüklerken Global Paketleri Taşıyın

NVM, tüm global paketleri bir sürümden yeni bir kuruluma kopyalamak için yerleşik bir bayrak sağlar:

“`bash

nvm install 20.14.0 –reinstall-packages-from=18.20.3

“`

Bu, PM2 veya benzeri araçlar tarafından yönetilen kalıcı süreçler çalıştıran bir sunucuda Node.js sürümlerini yükseltirken kritik öneme sahiptir.

Mevcut Sürüm için Global Olarak Yüklü Paketleri Listeleyin

“`bash

npm list -g –depth=0

“`

Adım 11: Bir Node.js Sürümünü Kaldırın

Kaldırmadan önce, kaldırmak istediğiniz sürümden çıkış yapın:

“`bash

nvm use 20.14.0

nvm uninstall 16.20.2

“`

Şu anda etkin olan sürümü kaldıramazsınız. Bunu yapmaya çalışmak bir hata döndürür.

Gelişmiş: Etkileşimli Olmayan Ortamlarda NVM Kullanımı (CI/CD, Cron, Systemd)

NVM, etkileşimli olmayan kabuklarda kaynak yüklenmeyen kabuk başlatma dosyalarına dayanır. Bu durum, cron işlerinde, systemd birim dosyalarında ve bazı CI ortamlarında `node: command not found` hatalarına neden olur.

Çözüm 1: Tam ikili dosya yolunu kullanın

“`bash

/home/username/.nvm/versions/node/v20.14.0/bin/node /path/to/app.js

“`

Çözüm 2: Betiklerde NVM’yi açıkça kaynak yükleyin

“`bash

#!/bin/bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm use 20.14.0

node /path/to/app.js

“`

Çözüm 3: Sistem genelinde erişim için sembolik bağlantı oluşturun (dikkatli kullanın)

“`bash

sudo ln -s /home/username/.nvm/versions/node/v20.14.0/bin/node /usr/local/bin/node

“`

Bu yaklaşım kullanıcı başına izolasyonu feda eder, ancak bazen özel bir hizmet kullanıcısı olarak çalışan systemd hizmetleri için gereklidir.

Paylaşımlı Hosting, VPS ve Dedicated Sunucularda NVM

Node.js uygulamalarını diğer hizmetlerle birlikte çalıştıran ekipler için bir VPS, fiziksel donanım yönetimi yükü olmadan NVM’nin gerektirdiği kabuk düzeyinde kontrolü sağlar.

Pratik Temel Kontrol Listesi

Bunu bir dağıtım ve yapılandırma referansı olarak kullanın:

• Kabuk türünü doğrulayın (`echo $SHELL`) kurulumdan önce — Zsh ve Bash farklı profil dosyaları gerektirir
• Üretim Node.js kurulumları için her zaman `–lts` kullanın; `node`’ı (en son) deneysel çalışmalar için saklayın
• `.nvmrc`’ı sürüm kontrolüne ekleyin, böylece her ekip üyesi ve CI çalıştırıcısı aynı çalışma zamanı sürümünü kullanır
• `–reinstall-packages-from` kullanın, Node.js sürümlerini yükseltirken global araçları manuel olarak yeniden yüklemekten kaçınmak için
• NVM’yi açıkça kaynak yükleyin herhangi bir etkileşimli olmayan betikte (cron, systemd, CI hatları) — kabuk profilinin yüklendiğini asla varsaymayın
• Sürüm başına global paketleri denetleyin `npm list -g –depth=0` ile sürüm değiştirdikten sonra eksik bağımlılıkları erken tespit etmek için
• `.nvmrc`’da tam sürümleri sabitleyin (örn. `20.14.0`), takma adlar yerine (örn. `lts`) üretimde maksimum yeniden üretilebilirlik için
• `which node`’ı kontrol edin sürüm değiştirdikten sonra sistem tarafından yüklenen bir ikili dosyayı yanlışlıkla kullanmadığınızı doğrulamak için

Sıkça Sorulan Sorular

NVM, Node.js yüklemek için sudo veya kök erişimi gerektiriyor mu?

Hayır. NVM her şeyi mevcut kullanıcının ana dizinindeki `~/.nvm` altına yükler. Node.js sürümlerini yüklemek veya değiştirmek için kök ayrıcalıklarına gerek yoktur. Bu, sistem düzeyindeki paket yöneticilerine kıyasla birincil avantajlarından biridir.

Kurulumdan sonra neden `nvm: command not found` görünüyor?

NVM başlatma bloğu kabuk profilinize eklendi, ancak profil mevcut oturumda yeniden kaynak yüklenmedi. `source ~/.bashrc` (Bash) veya `source ~/.zshrc` (Zsh) komutunu çalıştırın. Yeni bir terminal açtıktan sonra hata devam ederse, başlatma bloğunun `grep NVM_DIR ~/.bashrc` kullanılarak doğru dosyaya yazılıp yazılmadığını kontrol edin.

Aynı sunucudaki birden fazla kullanıcı NVM aracılığıyla farklı Node.js sürümlerine sahip olabilir mi?

Evet. NVM her kullanıcının ana dizinine (`~/.nvm`) yüklediğinden, her kullanıcı tamamen bağımsız bir Node.js sürümleri ve global paketler kümesini korur. Bu, çok kiracılı sunucular için doğru mimaridir.

NVM ile Node.js sürümlerini değiştirdiğimde global olarak yüklenen npm paketlerine ne olur?

Her Node.js sürümünün kendi izole global paket dizini vardır. Bir sürüm altında global olarak yüklenen paketler diğerine görünmez. Bunları otomatik olarak taşımak için `nvm install <new-version> –reinstall-packages-from=<old-version>` kullanın.

NVM, bir sunucuda üretimde Node.js uygulamaları çalıştırmak için uygun mu?

NVM, hangi Node.js sürümünün kullanıldığını yönetmek için çok uygundur, ancak üretimde süreç yönetimi için PM2 gibi bir süreç yöneticisiyle eşleştirmeli veya systemd birim dosyaları kullanmalısınız. Bu etkileşimli olmayan ortamların, yukarıdaki CI/CD bölümünde açıklandığı gibi NVM’yi açıkça kaynak yüklediğinden veya tam ikili dosya yoluna başvurduğundan emin olun.