Node.js Betik Çalıştırma: node Komutu, -e, -p, --watch ve --run

Komutun genel biçimi

CLI belgesindeki özet satır şöyledir: önce Node.js seçenekleri, sonra V8 seçenekleri, ardından giriş dosyası (ya da -e "betik" veya standart girdi için -), en sonda da programa iletilecek argümanlar gelir. Giriş dosyasından sonra yazdığınız her şey programın argümanıdır; node app.js --version komutunda --version Node.js'e değil, app.js'e gider. Argümansız node komutu REPL'i açar.

node [seçenekler] [V8 seçenekleri] [giriş-dosyası | -e "betik" | -] [--] [argümanlar]

Belgeye göre tüm seçeneklerde kelimeler tire ya da alt çizgiyle ayrılabilir; --pending-deprecation ile --pending_deprecation aynıdır. Tek değer alan bir seçenek birden çok kez verilirse son değer geçerli olur ve komut satırındaki seçenekler NODE_OPTIONS ortam değişkeniyle verilenlerin önüne geçer. NODE_OPTIONS ayrıntısı NODE_OPTIONS ve CLI bayrakları yazısında.

Giriş dosyası nasıl bulunur ve nasıl yüklenir?

Giriş noktası, belgede "belirteç benzeri" bir metin olarak tanımlanır. Mutlak yol değilse geçerli çalışma klasörüne göre çözülür ve sanki o klasörden require() ile istenmiş gibi aranır. Bu yüzden node merhaba yazdığınızda Node.js merhaba.js dosyasını bulup çalıştırabilir. Dosya bulunamazsa hata fırlatılır:

node yok.js
# çıktı: node:internal/modules/cjs/loader:1607
# çıktı:   throw err;
# çıktı:   ^
# çıktı:
# çıktı: Error: Cannot find module '/home/kullanici/proje/yok.js'
# çıktı:     at Module._resolveFilename (node:internal/modules/cjs/loader:1603:15)
# çıktı:     ... (yığın kısaltıldı)
# çıktı:   code: 'MODULE_NOT_FOUND',
# çıktı:   requireStack: []
# çıktı: }
# çıktı:
# çıktı: Node.js v26.13.0

Çıktılardaki yerel yollar /home/kullanici/proje/ biçiminde kısaltıldı. Bulunan dosya varsayılan olarak require() ile istenmiş gibi, yani CommonJS olarak yüklenir. Belgede üç istisna sayılır ve bunlardan biri geçerliyse dosya import() ile istenmiş gibi ES modülü olarak yüklenir: süreç --import gibi giriş noktasını ESM yükleyicisine zorlayan bir bayrakla başlatılmışsa, dosyanın uzantısı .mjs, .mts veya .wasm ise ya da dosya .cjs uzantılı değilken en yakın üst package.json dosyasında "type": "module" yazıyorsa.

// merhaba.js (package.json yok)
console.log('Merhaba, Node.js!');
console.log(typeof require, typeof module);
// çıktı: Merhaba, Node.js!
// çıktı: function object

// merhaba.mjs
console.log('Merhaba, ESM!');
console.log(typeof require, import.meta.filename.endsWith('merhaba.mjs'));
// çıktı: Merhaba, ESM!
// çıktı: undefined true

İlk dosyada require ve module tanımlı, çünkü dosya CommonJS olarak yüklendi. İkincisinde .mjs uzantısı dosyayı ES modülü yaptı; require artık yok ama import.meta var. İki modül sisteminin farklarını CommonJS ve ESM farkı yazısında, dil düzeyindeki import ve export sözdizimini ES modülleri yazısında bulabilirsiniz.

Shebang ile doğrudan çalıştırma

Unix benzeri sistemlerde dosyanın ilk satırına bir shebang yazarak işletim sistemine hangi yorumlayıcıyı kullanacağını söyleyebilirsiniz. Learn rehberi #!/usr/bin/node gibi mutlak bir yol yerine #!/usr/bin/env node yazmayı önerir; çünkü her sistemde node aynı klasörde değildir ama env hemen her sistemde bulunur. Dosyanın ayrıca çalıştırma izni olmalıdır.

#!/usr/bin/env node
console.log('Merhaba, Node.js!');

chmod u+x merhaba.js
./merhaba.js
# çıktı: Merhaba, Node.js!

Node.js bu ilk satırı kod olarak yorumlamaz; aynı dosyayı node merhaba.js ile çalıştırdığınızda da hata almazsınız. Önceki bölümdeki merhaba.js ve merhaba.mjs dosyalarını ilk satırlarında bu shebang varken Windows üzerinde node ile çalıştırdık ve ikisi de sorunsuz çalıştı. Windows'ta shebang işletim sistemi tarafından kullanılmadığı için dosyayı yine node komutuyla başlatmanız gerekir.

-e ve -p: dosya olmadan kod çalıştırmak

-e (--eval) kendisinden sonraki metni JavaScript olarak çalıştırır; -p (--print) aynı işi yapar ve sonucu da yazdırır. Belgeye göre REPL'de önceden tanımlı olan yerleşik modüller bu betiklerde de kullanılabilir; yani os veya path yazmak için önce içe aktarmanız gerekmez.

node -p "1 + 2"
# çıktı: 3
node -e "console.log(123)"
# çıktı: 123
node -p "os.platform()"
# çıktı: win32
node -p "[1, 2].map((x) => x * 2)"
# çıktı: [ 2, 4 ]

Tırnaklar kabuğa göre değişir. Belgeye göre Windows'taki cmd.exe yalnızca çift tırnağı tanıdığı için tek tırnak düzgün çalışmaz; PowerShell ve Git Bash'te ise iki tür tırnak da kullanılabilir. Betik bir tire ile başlıyorsa değeri eşittir işaretiyle verin (node --print --eval=-42); aksi hâlde Node.js onu yeni bir seçenek sanar. Türkçe karakter içeren uzun kodları komut satırına yazmak yerine dosyaya koymak, Windows konsolundaki kodlama sorunlarından da kaçınmanızı sağlar.

-e ile verilen kodun CommonJS mi ES modülü mü olduğuna --input-type karar verir. Bu bayrak verilmezse Node.js önce kodu CommonJS olarak çalıştırmayı dener, başarısız olursa ES modülü olarak dener; TypeScript tip ayıklama adımları da bu sıraya dahildir. Bu yüzden node -e "import { sep } from 'node:path'; console.log(sep)" bayraksız da çalışır. Belge, birden çok algılama geçişinin gecikmesinden kaçınmak için türü açıkça belirtmeyi önerir. --print ise ES modülü sözdizimini desteklemez:

node --input-type=module -p "1"
# çıktı: Error [ERR_EVAL_ESM_CANNOT_PRINT]: --print cannot be used with ESM input
# çıktı:     ... (yığın kısaltıldı)
# çıktı:   code: 'ERR_EVAL_ESM_CANNOT_PRINT'

Kodu standart girdiden de verebilirsiniz. Tek başına - argümanı stdin'in takma adıdır; betik girdiden okunur ve sonraki argümanlar o betiğe geçer. Bu, başka bir komutun ürettiği kodu çalıştırırken işe yarar:

echo "console.log('stdin\'den geldi')" | node -
# çıktı: stdin'den geldi

--check ile yalnızca sözdizimi denetimi

-c (--check) dosyayı çalıştırmadan sözdizimini denetler. Sürekli entegrasyon adımlarında ya da bir dosyayı sunucuya göndermeden önce hızlı bir kontrol için kullanışlıdır. Hata varsa satır ve sütunu gösterir ve 1 koduyla çıkar; sorun yoksa hiçbir şey yazmadan 0 ile çıkar.

node --check bozuk.js
# çıktı: /home/kullanici/proje/bozuk.js:1
# çıktı: const x = ;
# çıktı:           ^
# çıktı:
# çıktı: SyntaxError: Unexpected token ';'
# çıktı:     ... (yığın kısaltıldı)
echo $?
# çıktı: 1

--check yalnızca sözdizimine bakar; tanımsız bir değişkene erişim ya da bulunamayan bir modül gibi çalışma zamanı hatalarını yakalamaz. Bunlar için test yazmanız gerekir; yerleşik test çalıştırıcısı node:test yazısında anlatılıyor.

--watch: dosya değişince otomatik yeniden başlatma

--watch izleme modunu açar: izlenen dosyalar değiştiğinde Node.js süreci yeniden başlatılır. Belgeye göre bu mod v22.0.0 ve v20.13.0 ile kararlı hâle geldi. Varsayılan olarak giriş dosyası ve onun require ya da import ettiği her modül izlenir. Aşağıdaki çıktıyı, izleme modunu bir alt süreçte başlatıp dosyayı değiştiren küçük bir sürücü betikle aldık:

node --watch --watch-preserve-output izle.js
# çıktı: sürüm 1
# çıktı: Completed running 'izle.js'. Waiting for file changes before restarting...
# çıktı: Change detected in '/home/kullanici/proje/izle.js'
# çıktı: Restarting 'izle.js'
# çıktı: sürüm 2
# çıktı: Completed running 'izle.js'. Waiting for file changes before restarting...

--watch-preserve-output yeniden başlatmada konsolun temizlenmesini kapatır; önceki çıktıyı görmek istediğinizde işe yarar. --watch-path ise izlenecek yolları kendiniz belirlemenizi sağlar ve kullanıldığında içe aktarılan modüllerin izlenmesini kapatır. Belgeye göre --watch-path yalnızca macOS ve Windows'ta desteklenir; desteklenmeyen platformda ERR_FEATURE_UNAVAILABLE_ON_PLATFORM fırlatılır. --watch-kill-signal yeniden başlatmada gönderilecek sinyali değiştirir ve 1.1 aktif geliştirme aşamasındadır.

İzleme modu --check, --eval, --interactive ve REPL ile birleştirilemez. Bir dosya yolu ister ve --run ile birlikte verilirse --run öncelik kazanır, izleme modu yok sayılır. Belge, dosya verilmezse Node.js'in 9 koduyla çıktığını söyler; bizim Windows denememizde ise node --watch boş bir girişle tamamlanıp değişiklik beklemeye geçti. Her iki durumda da izleme modunu bir dosya yoluyla kullanın.

node --run: package.json betiklerini çalıştırmak

node --run, package.json içindeki "scripts" nesnesinden bir komutu çalıştırır. Belgeye göre bu komut kök klasöre kadar yukarı çıkarak bir package.json arar, komutu o dosyanın bulunduğu klasörde çalıştırır ve her üst klasördeki ./node_modules/.bin dizinini PATH değişkeninin başına ekler. Böylece projenin bağımlılıklarıyla gelen komut satırı araçlarını tam yol yazmadan kullanabilirsiniz.

{
  "type": "module",
  "scripts": {
    "start": "node app.js",
    "bilgi": "node bilgi.js"
  }
}

// app.js
console.log('argümanlar:', process.argv.slice(2));

// bilgi.js
import { basename } from 'node:path';
console.log(process.env.NODE_RUN_SCRIPT_NAME);
console.log(basename(process.env.NODE_RUN_PACKAGE_JSON_PATH));

node --run start -- --port 8080
# çıktı: argümanlar: [ '--port', '8080' ]
node --run bilgi
# çıktı: bilgi
# çıktı: package.json
node --run
# çıktı: Available scripts are:
# çıktı:   start: node app.js
# çıktı:   bilgi: node bilgi.js
echo $?
# çıktı: 9

-- işaretinden sonra yazılan argümanlar betiğin sonuna eklenir. Learn rehberinin vurguladığı gibi bunlar Node.js bayrağı olarak yorumlanmaz; -- --watch yazmak node --watch app.js ile aynı etkiyi vermez. Betik adı verilmeden çalıştırılan node --run mevcut betikleri listeler ve sıfır olmayan bir kodla çıkar; bizim denememizde bu kod 9 oldu. Var olmayan bir betik adı verdiğimizde ise "Missing script" mesajı, betik listesi ve 1 çıkış kodu aldık. Alt klasörden node --run start çalıştırdığımızda üstteki package.json bulundu ve komut o klasörde çalıştı.

Çalışan betik iki ortam değişkeni alır: NODE_RUN_SCRIPT_NAME çalıştırılan betiğin adını, NODE_RUN_PACKAGE_JSON_PATH ise işlenen package.json dosyasının yolunu taşır. Belgeye göre --env-file ile yüklenen değişkenler --run ile çalıştırılan komuta aktarılmaz; bunu da denedik ve betik içinde değişkenleri undefined olarak gördük.

Belge, node --run'ın npm run davranışını taklit etmeyi amaçlamadığını, yaygın kullanım durumlarında en iyi performansa odaklanmak için bilerek sınırlı tutulduğunu söyler. Bir betiğiniz prebuild gibi bir ön betiğe dayanıyorsa node --run onu çalıştırmaz. npm tarafındaki ayrıntılar Node.js belgelerinin kapsamında olmadığından docs.npmjs.com adresine bakın.

Hangi yöntemi ne zaman kullanmalı?

Belgede v26.11.0 ile eklenen --process-timeout=süre seçeneği de yer alır: süreç başlangıçtan itibaren verilen süreyi aşarsa 124 koduyla sonlandırılır. Bu seçenek 1.1 aktif geliştirme aşamasındadır, NODE_OPTIONS içinde kullanılamaz ve --run ya da inspector bayraklarıyla birleştirilemez.

Sık yapılan hatalar

• Node.js bayrağını dosya adından sonra yazmak: node app.js --watch izleme modunu açmaz; --watch programın argümanı olur. Bayraklar dosya adından önce gelir.
• cmd.exe'de tek tırnak kullanmak: Windows komut isteminde -e kodunu çift tırnakla sarın.
• -p ile ESM kodu çalıştırmaya çalışmak: --print ES modülü sözdizimini desteklemez; ERR_EVAL_ESM_CANNOT_PRINT alırsınız. -e ile console.log kullanın.
• --run'ın pre betiklerini çalıştıracağını sanmak: node --run yalnızca adını verdiğiniz betiği çalıştırır.
• --env-file değişkenlerini --run betiğinde beklemek: Bu değişkenler çalıştırılan komuta aktarılmaz; betiğin kendisinde --env-file kullanın.
• Uzantıyı ve type alanını karıştırmak: .js dosyası en yakın package.json içindeki "type" değerine göre CommonJS ya da ESM olur; beklenmedik require is not defined hatalarının kaynağı çoğu zaman budur.

Sık Sorulan Sorular

Dosya uzantısını yazmadan çalıştırabilir miyim?

Giriş noktası require() çözümlemesiyle arandığı için node merhaba komutu merhaba.js dosyasını bulur. Yine de açıklık için uzantıyı yazmak daha iyidir; özellikle .mjs gibi uzantılarda neyin çalışacağı hemen anlaşılır.

--watch ile nodemon gibi bir pakete hâlâ ihtiyacım var mı?

Temel ihtiyaç olan "dosya değişince yeniden başlat" işlevi --watch ile yerleşik olarak gelir ve belgede kararlı olarak işaretlidir. Üçüncü taraf araçların ek özellikleri Node.js belgelerinin konusu değildir.

node --run npm run yerine geçer mi?

Basit betikler için evet; Learn rehberi onu performans ve sadelik odaklı, bilerek sınırlı bir görev çalıştırıcısı olarak tanıtır. Ön ve son betiklere ya da npm'in tanımladığı ortam değişkenlerine dayanan iş akışlarında npm run kullanmaya devam edin.

Programa verdiğim argümanları nasıl okurum?

Argümanlar process.argv dizisinde yer alır; seçenek ayrıştırmak için yerleşik util.parseArgs vardır. Ayrıntılar process.argv, parseArgs ve çıkış kodları yazısında.

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 kurulumu · REPL kullanımı · process.argv ve çıkış kodları · --env-file · CommonJS ve ESM · NODE_OPTIONS ve CLI bayrakları