NODE_OPTIONS ve Node.js Komut Satırı Bayrakları

Komut satırının yapısı ve bayrak sırası

Belgelerdeki genel biçim şöyledir: node [seçenekler] [V8 seçenekleri] [betik | -e "kod" | -] [--] [argümanlar]. Buradaki kural basittir ama sık atlanır: Node.js'e ait bayraklar betik adından önce yazılmalıdır. Betik adından sonra gelen her şey, bayrağa benzese bile, betiğinize argüman olarak gider ve process.argv içinde görünür.

// sira.mjs
console.log('execArgv:', process.execArgv);
console.log('argv (ilk ikisi hariç):', process.argv.slice(2));
console.log('stackTraceLimit:', Error.stackTraceLimit);

// $ node --stack-trace-limit=50 sira.mjs
// çıktı: execArgv: [ '--stack-trace-limit=50' ]
// çıktı: argv (ilk ikisi hariç): []
// çıktı: stackTraceLimit: 50

// $ node sira.mjs --stack-trace-limit=50
// çıktı: execArgv: []
// çıktı: argv (ilk ikisi hariç): [ '--stack-trace-limit=50' ]
// çıktı: stackTraceLimit: 10

process.execArgv, Node.js'e verilen bayrakları tutar ve belgeye göre alt süreçleri aynı çalışma ortamıyla başlatmak için kullanışlıdır. process.argv ve argüman ayrıştırma ayrıntıları process.argv ve çıkış kodları yazısında. İki küçük kural daha var: bayraklarda kelimeler tire veya alt çizgiyle ayrılabilir (--stack_trace_limit ile --stack-trace-limit aynıdır) ve tek değer alan bir bayrak birden fazla kez verilirse son değer geçerli olur. Denememizde --stack_trace_limit=40 --stack-trace-limit=60 sonucunda Error.stackTraceLimit 60 oldu.

Tanınmayan bir bayrak verdiğinizde Node.js betiği hiç çalıştırmaz ve 9 koduyla çıkar. Bu yazıdaki hata çıktılarında node.exe dosyasının tam yolunu kısaca node olarak yazdık. Belgedeki çıkış kodları listesinde 9, bilinmeyen bir seçenek ya da değer bekleyen bir seçeneğin değersiz verilmesi anlamına gelir.

$ node --olmayan-bayrak app.js
node: bad option: --olmayan-bayrak
$ echo $?
9

NODE_OPTIONS nasıl çalışır?

NODE_OPTIONS içindeki bayraklar, komut satırındakilerden önce yorumlanır. Bunun pratik anlamı şudur: aynı tek değerli bayrak iki yerde de varsa komut satırındaki kazanır; --require gibi birden çok kez verilebilen bayraklarda ise önce NODE_OPTIONS içindekiler, sonra komut satırındakiler uygulanır. Aşağıdaki betik, bayrakların nereden geldiğini ve etkisini gösteriyor.

// bilgi.mjs
import v8 from 'node:v8';

const mib = (n) => Math.round(n / 1024 / 1024);
console.log('execArgv:', process.execArgv);
console.log('NODE_OPTIONS:', process.env.NODE_OPTIONS ?? '(yok)');
console.log('stackTraceLimit:', Error.stackTraceLimit);
console.log('heap limiti (MiB):', mib(v8.getHeapStatistics().heap_size_limit));

$ NODE_OPTIONS="--max-old-space-size=512 --stack-trace-limit=5" node bilgi.mjs
execArgv: []
NODE_OPTIONS: --max-old-space-size=512 --stack-trace-limit=5
stackTraceLimit: 5
heap limiti (MiB): 608

$ NODE_OPTIONS="--stack-trace-limit=5" node --stack-trace-limit=30 bilgi.mjs
execArgv: [ '--stack-trace-limit=30' ]
NODE_OPTIONS: --stack-trace-limit=5
stackTraceLimit: 30
heap limiti (MiB): 4192

İlk çalıştırmada bayraklar yalnızca ortam değişkeninden geldiği için process.execArgv boş kaldı; yani bir sürecin hangi bayraklarla çalıştığını anlamak için iki kaynağa da bakmanız gerekir. İkinci çalıştırmada komut satırındaki 30 değeri ortam değişkenindeki 5 değerini geçersiz kıldı. Varsayılan yığın sınırı (son satırdaki 4192) makinenin belleğine göre değişir; sizin sisteminizde farklı bir sayı görebilirsiniz.

Bir değerin içinde boşluk varsa belge çift tırnakla kaçışlamayı gösteriyor: NODE_OPTIONS='--require "./my path/file.js"'. Kabuğunuzun tırnak kurallarına dikkat edin; dış tırnak kabuk için, iç tırnak Node.js içindir.

NODE_OPTIONS içinde izin verilmeyen bayraklar

Belge, NODE_OPTIONS içinde kullanılabilecek bayrakların tam listesini verir. -p, betik dosyası ya da --test bu listede yoktur. İzin verilmeyen bir bayrak kullanıldığında Node.js hiçbir kodu çalıştırmadan 9 koduyla çıkar.

$ NODE_OPTIONS="-p" node bilgi.mjs
node: -p is not allowed in NODE_OPTIONS
$ echo $?
9

Bir bayrağın izinli olup olmadığını kod içinden process.allowedNodeEnvironmentFlags ile sorabilirsiniz. Bu özel Set, has() çağrısında baştaki tirelerin atlanmasına ve eşittir işaretinden sonrasının yok sayılmasına izin verir.

// izinli.mjs
const f = process.allowedNodeEnvironmentFlags;
console.log(f.has('--max-old-space-size'));
console.log(f.has('--stack-trace-limit'));
console.log(f.has('--enable-source-maps'));
console.log(f.has('--test'));
console.log(f.has('-p'));
// çıktı: true
// çıktı: true
// çıktı: true
// çıktı: false
// çıktı: false

NODE_OPTIONS genellikle Docker imajlarında, systemd servis dosyalarında ve CI ayarlarında kullanılır; çünkü başlatma komutunu değiştirmeden bayrak eklemeyi sağlar. Bu ortamların genel kurulumu için Dockerfile yazma rehberi ve systemd servis dosyası rehberi yazılarına bakabilirsiniz.

Bellek sınırı: --max-old-space-size

--max-old-space-size=SIZE, V8'in eski nesil (old space) bellek bölümünün en fazla kaç MiB olabileceğini belirler. Kullanım bu sınıra yaklaştıkça V8 çöp toplamaya daha fazla zaman ayırır. Belge, 2 GiB belleği olan bir makinede diğer işlere ve takas alanına yer bırakmak için 1536 değerini örnek veriyor. Bu bayrak V8'e aittir ama NODE_OPTIONS içinde kullanılmasına izin verilen V8 seçenekleri arasındadır.

$ node --max-old-space-size=1536 bilgi.mjs
execArgv: [ '--max-old-space-size=1536' ]
NODE_OPTIONS: (yok)
stackTraceLimit: 10
heap limiti (MiB): 1632

heap_size_limit değerinin 1536 yerine 1632 çıkması bir hata değildir: bayrak yalnızca eski nesil bölümünü sınırlar, v8.getHeapStatistics() ise V8'in toplam yığın sınırını raporlar. Bunun yanında iki ilgili bayrak var. --max-old-space-size-percentage sınırı sistem belleğinin yüzdesi olarak verir ve ikisi birlikte kullanılırsa öncelik onundur. --max-semi-space-size ise genç nesil çöp toplayıcısının yarı alan boyutunu ayarlar; belge, en iyi değeri kendi uygulamanızla ölçerek bulmanızı öneriyor.

Yığın izi uzunluğu: --stack-trace-limit

Bir hata nesnesinin yığın izi varsayılan olarak 10 çerçeve tutar. Derin çağrı zincirlerinde, özellikle çok katmanlı kütüphanelerde, asıl sorunlu satır bu 10 çerçevenin dışında kalabilir. --stack-trace-limit bu sayıyı değiştirir; 0 verirseniz yığın izi hiç toplanmaz. Aynı değeri kod içinden Error.stackTraceLimit ile de okuyup değiştirebilirsiniz; değişiklik yalnızca sonradan oluşturulan hataları etkiler.

$ node --stack-trace-limit=12 -p "Error.stackTraceLimit"
12

Daha uzun yığın izi daha fazla iş demektir; üretimde bu değeri gereğinden fazla yükseltmeyin. Hata ayıklarken geçici olarak yükseltip, sorunu bulduktan sonra eski değere dönmek iyi bir alışkanlıktır.

Kaynak haritaları: --enable-source-maps

Kodunuzu bir derleyiciden ya da paketleyiciden geçirip çalıştırıyorsanız yığın izleri, yazdığınız kaynak dosyayı değil üretilen çıktıyı gösterir. --enable-source-maps bayrağı kaynak haritalarını önbelleğe alır ve yığın izlerini mümkün olduğunca özgün dosya ve satıra göre raporlar. Bayrağın etkin olup olmadığını process.sourceMapsEnabled ile kontrol edebilirsiniz.

$ node --enable-source-maps -p "process.sourceMapsEnabled"
true

Belge önemli bir uyarı içeriyor: Error.prepareStackTrace fonksiyonunu kendiniz değiştirirseniz bu bayrak yığın izini düzenleyemeyebilir. Bu durumda kendi fonksiyonunuzda orijinal Error.prepareStackTrace sonucunu çağırıp döndürmeniz gerekir. TypeScript dosyalarını tip ayıklamayla doğrudan çalıştırıyorsanız konum bilgisi zaten korunur; ayrıntılar TypeScript'i Node.js ile kullanma yazısında.

Ayar dosyası: --config-file ve node.config.json

v26.12.0 ile --experimental-config-file bayrağının adı --config-file oldu ve bayrak kararlı hâle geldi; eski ad ve --experimental-default-config-file takma ad olarak çalışmaya devam ediyor. Bayrak yol olmadan verilirse Node.js çalışma dizinindeki node.config.json dosyasını okur; başka bir dosya için --config-file=yol biçimini kullanırsınız. Dosyadaki her anahtar bir komut satırı bayrağına karşılık gelir.

{
  "$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
  "nodeOptions": {
    "enable-source-maps": true,
    "disable-warning": ["DEP0044"],
    "unhandled-rejections": "strict"
  }
}

// ayar.mjs
import util from 'node:util';

console.log('sourceMapsEnabled:', process.sourceMapsEnabled);
console.log('execArgv:', process.execArgv);
console.log(util.isArray([]));

// $ node --config-file ayar.mjs
// çıktı: sourceMapsEnabled: true
// çıktı: execArgv: [ '--config-file=node.config.json' ]
// çıktı: true

Ayar dosyası olmadan aynı betiği çalıştırdığımızda sourceMapsEnabled değeri false oldu ve DEP0044 uyarısı stderr'e yazıldı; dosya ile çalıştırdığımızda uyarı susturuldu. $schema satırı editörünüzün dosyayı doğrulayabilmesi içindir; belgeye göre vX.Y.Z yerine kullandığınız sürümü ya da latest-v26.x gibi bir hat adını yazarsınız.

Dosyanın yapısı ad alanlarına bölünür. nodeOptions alanı yalnızca NODE_OPTIONS içinde izin verilen bayrakları kabul eder. test, watch ve permission gibi ad alanları ilgili alt sistemin ayarlarını tutar ve dosyada bulunmaları o alt sistemi otomatik olarak açar; örneğin "test": {"test-isolation": "process"} yazmak, node --test --test-isolation=process çalıştırmakla eşdeğerdir. Tek dosyada birden fazla ana sürüm için ayar tutmak isterseniz configs dizisi ve her öğede bir nodeVersion kullanabilirsiniz; Node.js ana sürümüyle eşleşen ilk öğeyi uygular.

Öncelik sırası şöyledir: en üstte NODE_OPTIONS ve komut satırı, ardından --env-file ile okunan dosyadaki NODE_OPTIONS, en altta ayar dosyası. Yani ayar dosyası hiçbir zaman komut satırındaki ya da ortam değişkenindeki değeri ezmez. Bu, ayar dosyasını "varsayılanlar" için, ortam değişkenini ise ortama özel değişiklikler için kullanmanızı kolaylaştırır.

Ayar dosyasında karşılaştığımız hatalar

Belge, tüm V8 bayraklarının şu an desteklenmediğini söylüyor. Denememizde max-old-space-size anahtarını nodeOptions altına yazdığımızda Node.js dosyayı reddetti ve 9 koduyla çıktı. Bellek sınırı gibi V8 bayraklarını bu yüzden NODE_OPTIONS veya komut satırıyla verin.

$ node --config-file ayar.mjs
V8 flag --max-old-space-size is currently not supported
node: node.config.json: invalid content
$ echo $?
9

Bilinmeyen bir anahtar da aynı şekilde reddedilir; denememizde "olmayan-ayar": true için "Unknown or not allowed option olmayan-ayar for namespace nodeOptions" hatası alındı. Belgeye göre aynı anahtar aynı ya da farklı ad alanlarında iki kez yazılamaz. Son olarak boşlukla ayrılmış --config-file node.config.json biçimi desteklenmez: denememizde Node.js bu durumda JSON dosyasını ayar dosyası olarak değil, çalıştırılacak program olarak aldı ve ayar.mjs hiç çalışmadan sessizce çıktı. Yol vermek istiyorsanız mutlaka eşittir işaretli biçimi kullanın.

Sık başvurulan diğer bayraklar

Aşağıdaki bayrakların her birini serinin ilgili yazısında ayrıntılı ele aldık. Tablo, hangi işi hangi bayrağın yaptığını hatırlamak için bir başvuru listesidir.

Tablodaki bağlantılar: --env-file, --watch ve --run, --inspect ile hata ayıklama, izin modeli, --unhandled-rejections, --disable-warning.

Sık yapılan hatalar

Bayrağı betik adından sonra yazmak. node app.js --max-old-space-size=2048 komutu bellek sınırını değiştirmez; bayrak betiğinize argüman olarak gider. Node.js bayrakları her zaman betik adından önce gelmelidir.

NODE_OPTIONS içine her bayrağı koymak. -p, --test ya da bir betik adı bu değişkende kullanılamaz ve süreç 9 koduyla çıkar. Emin değilseniz process.allowedNodeEnvironmentFlags.has() ile kontrol edin.

NODE_OPTIONS değerinin her yerde geçerli olduğunu unutmak. Değişkeni kabuk profilinize yazarsanız o kabuktan başlatılan her Node.js süreci, araç komutları dahil, bu bayrakları alır. Bayrağı yalnızca ilgili servisin ortamında tanımlayın.

V8 bayraklarını node.config.json içine yazmak. Denememizde max-old-space-size ayar dosyasında desteklenmedi ve süreç başlamadı. Bellek bayraklarını ortam değişkeni veya komut satırıyla verin.

--config-file için boşluklu biçim kullanmak. --config-file dosya.json yazıldığında dosya program olarak alınır. Doğru biçim --config-file=dosya.json ya da yolsuz --config-file şeklindedir.

Sık Sorulan Sorular

NODE_OPTIONS ile komut satırı çakışırsa hangisi geçerli olur?

Tek değer alan bayraklarda komut satırı kazanır. Birden çok kez verilebilen bayraklarda (örneğin --require) ikisi de uygulanır: önce NODE_OPTIONS içindekiler, sonra komut satırındakiler.

--max-old-space-size için hangi değeri seçmeliyim?

Belgede sabit bir öneri yoktur; yalnızca 2 GiB bellekli bir makine için 1536 örneği verilir. Değeri, makinedeki toplam bellek ve aynı makinede çalışan diğer süreçlere göre seçin ve uygulamanızı bu sınırla ölçün.

node.config.json dosyası otomatik okunur mu?

Hayır, dosyanın okunması için --config-file bayrağını vermeniz gerekir. Bayrak yolsuz verilirse çalışma dizinindeki node.config.json kullanılır.

Hangi bayrakları desteklediğini nereden görürüm?

node --help seçenekleri kısaca listeler; belgeye göre bu çıktı cli.html sayfasından daha az ayrıntılıdır, bu yüzden tam açıklamalar için nodejs.org/api/cli.html sayfasına bakın. V8'e ait tüm seçenekleri node --v8-options listeler; belgeye göre V8 seçenekleri Node.js kararlılık garantilerinin kapsamında değildir.

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 komutu ile betik çalıştırma · --env-file ve process.env · Deprecation uyarıları · Node.js performans optimizasyonu