Node.js v26.0.0 Dokumentation

Prozess#

Das process-Objekt bietet Informationen über und Steuerungsmöglichkeiten für den aktuellen Node.js-Prozess.

import process from 'node:process';
const process = require('node:process');
copy

Prozessereignisse#

Das process-Objekt ist eine Instanz von EventEmitter.

Ereignis: 'beforeExit'#

Das 'beforeExit'-Ereignis wird ausgelöst, wenn Node.js seine Event-Loop leert und keine weiteren Arbeiten mehr einzuplanen sind. Normalerweise wird der Node.js-Prozess beendet, wenn keine Arbeit mehr ansteht, aber ein beim 'beforeExit'-Ereignis registrierter Listener kann asynchrone Aufrufe tätigen und somit den Node.js-Prozess dazu veranlassen, fortzufahren.

Die Listener-Callback-Funktion wird mit dem Wert von process.exitCode als einzigem Argument aufgerufen.

Das 'beforeExit'-Ereignis wird nicht bei Bedingungen ausgelöst, die eine explizite Beendigung verursachen, wie etwa der Aufruf von process.exit() oder nicht abgefangene Exceptions.

'beforeExit' sollte nicht als Alternative zum 'exit'-Ereignis verwendet werden, es sei denn, es ist beabsichtigt, weitere Arbeiten einzuplanen.

import process from 'node:process';

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0
const process = require('node:process');

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0
copy

Ereignis: 'disconnect'#

Wenn der Node.js-Prozess mit einem IPC-Kanal gestartet wurde (siehe die Dokumentation zu Child Process und Cluster), wird das 'disconnect'-Ereignis ausgelöst, wenn der IPC-Kanal geschlossen wird.

Ereignis: 'exit'#

• code <integer>

Das 'exit'-Ereignis wird ausgelöst, wenn der Node.js-Prozess kurz vor der Beendigung steht, als Ergebnis von:

• Der expliziten Methode process.exit();
• Der Node.js Event-Loop, die keine weiteren Aufgaben zu erledigen hat.

Es gibt keine Möglichkeit, das Beenden der Event-Loop an diesem Punkt zu verhindern, und sobald alle 'exit'-Listener ausgeführt wurden, wird der Node.js-Prozess beendet.

Die Listener-Callback-Funktion wird mit dem Exit-Code aufgerufen, der entweder durch die Eigenschaft process.exitCode oder durch das an die Methode process.exit() übergebene exitCode-Argument festgelegt wurde.

import process from 'node:process';

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});
const process = require('node:process');

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});
copy

Listener-Funktionen müssen ausschließlich synchrone Operationen durchführen. Der Node.js-Prozess wird sofort nach dem Aufruf der 'exit'-Event-Listener beendet, wodurch alle weiteren in der Event-Loop wartenden Arbeiten verworfen werden. Im folgenden Beispiel wird beispielsweise der Timeout niemals eintreten:

import process from 'node:process';

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});
const process = require('node:process');

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});
copy

Ereignis: 'message'#

• message <Object> | <boolean> | <number> | <string> | <null> ein geparstes JSON-Objekt oder ein serialisierbarer primitiver Wert.
• sendHandle <net.Server> | <net.Socket> ein net.Server- oder net.Socket-Objekt oder undefined.

Wenn der Node.js-Prozess mit einem IPC-Kanal gestartet wurde, wird das 'message'-Ereignis jedes Mal ausgelöst, wenn eine Nachricht, die von einem Elternprozess mittels childprocess.send() gesendet wurde, vom Kindprozess empfangen wird.

Die Nachricht durchläuft Serialisierung und Parsing. Die resultierende Nachricht ist möglicherweise nicht identisch mit der ursprünglich gesendeten.

Wenn beim Starten des Prozesses die Option serialization auf advanced gesetzt wurde, kann das message-Argument Daten enthalten, die JSON nicht darstellen kann. Siehe Erweiterte Serialisierung für child_process für weitere Details.

Ereignis: 'rejectionHandled'#

• promise <Promise> Die verspätet behandelte Promise.

Das 'rejectionHandled'-Ereignis wird ausgelöst, wenn eine Promise abgelehnt wurde und ein Fehler-Handler an sie angehängt wurde (z. B. mittels promise.catch()), später als einen Durchlauf der Node.js Event-Loop.

Das Promise-Objekt wäre zuvor in einem 'unhandledRejection'-Ereignis ausgegeben worden, erhielt jedoch während der Verarbeitung einen Ablehnungs-Handler.

Es gibt kein Konzept einer "obersten Ebene" für eine Promise-Kette, bei der Ablehnungen immer behandelt werden können. Da eine Promise-Ablehnung inhärent asynchron ist, kann sie zu einem späteren Zeitpunkt behandelt werden, möglicherweise viel später als der Event-Loop-Durchlauf, in dem das 'unhandledRejection'-Ereignis ausgelöst wurde.

Anders ausgedrückt: Im Gegensatz zu synchronem Code, bei dem es eine ständig wachsende Liste nicht abgefangener Ausnahmen gibt, kann es bei Promises eine Liste von nicht behandelten Ablehnungen geben, die wächst und schrumpft.

In synchronem Code wird das 'uncaughtException'-Ereignis ausgelöst, wenn die Liste der nicht abgefangenen Ausnahmen wächst.

In asynchronem Code wird das 'unhandledRejection'-Ereignis ausgelöst, wenn die Liste der nicht behandelten Ablehnungen wächst, und 'rejectionHandled', wenn diese Liste schrumpft.

import process from 'node:process';

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});
const process = require('node:process');

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});
copy

In diesem Beispiel wächst und schrumpft die unhandledRejections-Map im Laufe der Zeit und spiegelt Ablehnungen wider, die zuerst unbehandelt bleiben und dann behandelt werden. Es ist möglich, solche Fehler in einem Fehlerprotokoll zu speichern, entweder periodisch (was für langlebige Anwendungen wahrscheinlich am besten ist) oder beim Prozessende (was für Skripte wahrscheinlich am bequemsten ist).

Ereignis: 'workerMessage'#

• value <any> Ein Wert, der mittels postMessageToThread() übertragen wurde.
• source <number> Die ID des übertragenden Worker-Threads oder 0 für den Hauptthread.

Das 'workerMessage'-Ereignis wird für jede eingehende Nachricht ausgelöst, die von der anderen Partei mittels postMessageToThread() gesendet wurde.

Ereignis: 'uncaughtException'#

• err <Error> Die nicht abgefangene Ausnahme.
• origin <string> Gibt an, ob die Ausnahme von einer unbehandelten Ablehnung (Rejection) oder einem synchronen Fehler stammt. Kann entweder 'uncaughtException' oder 'unhandledRejection' sein. Letzteres wird verwendet, wenn eine Ausnahme in einem Promise-basierten asynchronen Kontext auftritt (oder eine Promise abgelehnt wird) und das Flag --unhandled-rejections auf strict oder throw (Standardwert) gesetzt ist und die Ablehnung nicht behandelt wird, oder wenn eine Ablehnung während der statischen Ladephase von ES-Modulen am Kommandozeilen-Einstiegspunkt erfolgt.

Das 'uncaughtException'-Ereignis wird ausgelöst, wenn eine nicht abgefangene JavaScript-Ausnahme bis zur Event-Loop zurückkehrt. Standardmäßig behandelt Node.js solche Ausnahmen, indem es den Stack-Trace an stderr ausgibt und mit Code 1 beendet, wodurch ein zuvor gesetztes process.exitCode überschrieben wird. Das Hinzufügen eines Handlers für das 'uncaughtException'-Ereignis überschreibt dieses Standardverhalten. Alternativ kann das process.exitCode im 'uncaughtException'-Handler geändert werden, was dazu führt, dass der Prozess mit dem angegebenen Exit-Code beendet wird. Andernfalls wird der Prozess bei Vorhandensein eines solchen Handlers mit 0 beendet.

import process from 'node:process';
import fs from 'node:fs';

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}\n`,
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');
const process = require('node:process');
const fs = require('node:fs');

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}\n`,
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');
copy

Es ist möglich, 'uncaughtException'-Ereignisse zu überwachen, ohne das Standardverhalten des Prozessabbruchs zu überschreiben, indem ein 'uncaughtExceptionMonitor'-Listener installiert wird.

Warnung: Korrekte Verwendung von 'uncaughtException'#

'uncaughtException' ist ein grober Mechanismus zur Ausnahmebehandlung, der nur als letztes Mittel verwendet werden sollte. Das Ereignis sollte nicht als Äquivalent zu On Error Resume Next verwendet werden. Nicht abgefangene Ausnahmen bedeuten inhärent, dass sich eine Anwendung in einem undefinierten Zustand befindet. Der Versuch, Anwendungscode fortzusetzen, ohne sich ordnungsgemäß von der Ausnahme zu erholen, kann zu weiteren unvorhergesehenen und unvorhersehbaren Problemen führen.

Ausnahmen, die innerhalb des Event-Handlers geworfen werden, werden nicht abgefangen. Stattdessen wird der Prozess mit einem Exit-Code ungleich Null beendet und der Stack-Trace ausgegeben. Dies dient dazu, unendliche Rekursionen zu vermeiden.

Der Versuch, nach einer nicht abgefangenen Ausnahme normal fortzufahren, kann mit dem Ziehen des Netzsteckers beim Upgrade eines Computers verglichen werden. Neun von zehn Malen passiert nichts. Aber beim zehnten Mal ist das System beschädigt.

Die korrekte Verwendung von 'uncaughtException' besteht darin, vor dem Herunterfahren des Prozesses eine synchrone Bereinigung zugewiesener Ressourcen (z. B. Datei-Deskriptoren, Handles usw.) durchzuführen. Es ist nicht sicher, den normalen Betrieb nach einer 'uncaughtException' fortzusetzen.

Um eine abgestürzte Anwendung zuverlässiger neu zu starten, unabhängig davon, ob 'uncaughtException' ausgelöst wird oder nicht, sollte ein externer Monitor in einem separaten Prozess eingesetzt werden, um Anwendungsfehler zu erkennen und bei Bedarf wiederherzustellen oder neu zu starten.

Ereignis: 'uncaughtExceptionMonitor'#

• err <Error> Die nicht abgefangene Ausnahme.
• origin <string> Gibt an, ob die Ausnahme von einer unbehandelten Ablehnung oder synchronen Fehlern stammt. Kann entweder 'uncaughtException' oder 'unhandledRejection' sein.

Das 'uncaughtExceptionMonitor'-Ereignis wird ausgelöst, bevor ein 'uncaughtException'-Ereignis ausgelöst wird oder ein über process.setUncaughtExceptionCaptureCallback() installierter Hook aufgerufen wird.

Das Installieren eines 'uncaughtExceptionMonitor'-Listeners ändert nicht das Verhalten, sobald ein 'uncaughtException'-Ereignis ausgelöst wird. Der Prozess wird weiterhin abstürzen, wenn kein 'uncaughtException'-Listener installiert ist.

import process from 'node:process';

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.js
const process = require('node:process');

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.js
copy

Ereignis: 'unhandledRejection'#

• reason <Error> | <any> Das Objekt, mit dem die Promise abgelehnt wurde (typischerweise ein Error-Objekt).
• promise <Promise> Die abgelehnte Promise.

Das 'unhandledRejection'-Ereignis wird ausgelöst, wenn eine Promise abgelehnt wird und kein Fehler-Handler innerhalb eines Durchlaufs der Event-Loop an die Promise angehängt wird. Beim Programmieren mit Promises werden Ausnahmen als "abgelehnte Promises" gekapselt. Ablehnungen können mittels promise.catch() abgefangen und behandelt werden und werden durch eine Promise-Kette weitergegeben. Das 'unhandledRejection'-Ereignis ist nützlich, um abgelehnte Promises zu erkennen und nachzuverfolgen, deren Ablehnungen noch nicht behandelt wurden.

import process from 'node:process';

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`
const process = require('node:process');

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`
copy

Das Folgende löst ebenfalls das 'unhandledRejection'-Ereignis aus:

import process from 'node:process';

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turn
const process = require('node:process');

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turn
copy

In diesem Beispielfall ist es möglich, die Ablehnung als Entwicklerfehler zu verfolgen, wie dies typischerweise bei anderen 'unhandledRejection'-Ereignissen der Fall wäre. Um solche Fehler zu beheben, kann ein nicht-funktionaler .catch(() => { })-Handler an resource.loaded angehängt werden, was verhindern würde, dass das 'unhandledRejection'-Ereignis ausgelöst wird.

Wenn ein 'unhandledRejection'-Ereignis ausgelöst, aber nicht behandelt wird, wird es als eine nicht abgefangene Ausnahme gemeldet. Dies kann neben anderen Verhaltensweisen von 'unhandledRejection'-Ereignissen über das Flag --unhandled-rejections geändert werden.

Ereignis: 'warning'#

• warning <Error> Wichtige Eigenschaften der Warnung sind
  • name <string> Der Name der Warnung. Standard: 'Warning'.
  • message <string> Eine vom System bereitgestellte Beschreibung der Warnung.
  • stack <string> Ein Stack-Trace zum Ort im Code, an dem die Warnung ausgegeben wurde.

Das 'warning'-Ereignis wird ausgelöst, wenn Node.js eine Prozesswarnung ausgibt.

Eine Prozesswarnung ähnelt einem Fehler, da sie außergewöhnliche Bedingungen beschreibt, auf die der Benutzer aufmerksam gemacht werden soll. Warnungen sind jedoch nicht Teil des normalen Fehlerbehandlungsflusses von Node.js und JavaScript. Node.js kann Warnungen ausgeben, wenn es schlechte Codierungspraktiken erkennt, die zu suboptimaler Anwendungsleistung, Bugs oder Sicherheitslücken führen könnten.

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});
const process = require('node:process');

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});
copy

Standardmäßig gibt Node.js Prozesswarnungen an stderr aus. Die Kommandozeilenoption --no-warnings kann verwendet werden, um die Standardkonsolenausgabe zu unterdrücken, aber das 'warning'-Ereignis wird weiterhin vom process-Objekt ausgelöst. Derzeit ist es nicht möglich, andere Warnungstypen außer Deprecation-Warnungen zu unterdrücken. Um Deprecation-Warnungen zu unterdrücken, schauen Sie sich das Flag --no-deprecation an.

Das folgende Beispiel illustriert die Warnung, die an stderr ausgegeben wird, wenn zu viele Listener für ein Ereignis hinzugefügt wurden:

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leak
detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit
copy

Im Gegensatz dazu schaltet das folgende Beispiel die Standard-Warnungsausgabe aus und fügt einen benutzerdefinierten Handler zum 'warning'-Ereignis hinzu:

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Do not do that!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Do not do that!
copy

Die Kommandozeilenoption --trace-warnings kann verwendet werden, damit die Standardkonsolenausgabe für Warnungen den vollständigen Stack-Trace der Warnung enthält.

Das Starten von Node.js mit dem Kommandozeilenflag --throw-deprecation führt dazu, dass benutzerdefinierte Deprecation-Warnungen als Ausnahmen geworfen werden.

Die Verwendung des Kommandozeilenflags --trace-deprecation bewirkt, dass die benutzerdefinierte Deprecation zusammen mit dem Stack-Trace an stderr ausgegeben wird.

Die Verwendung des Kommandozeilenflags --no-deprecation unterdrückt jegliche Berichterstattung über die benutzerdefinierte Deprecation.

Die *-deprecation-Kommandozeilenflags betreffen nur Warnungen, die den Namen 'DeprecationWarning' verwenden.

Auslösen benutzerdefinierter Warnungen#

Siehe die Methode process.emitWarning() zum Ausgeben von benutzerdefinierten oder anwendungsspezifischen Warnungen.

Node.js Warnungsnamen#

Es gibt keine strengen Richtlinien für Warnungstypen (identifiziert durch die name-Eigenschaft), die von Node.js ausgegeben werden. Neue Warnungstypen können jederzeit hinzugefügt werden. Einige der häufigsten Warnungstypen sind:

• 'DeprecationWarning' - Zeigt die Verwendung einer veralteten (deprecated) Node.js-API oder eines Features an. Solche Warnungen müssen eine 'code'-Eigenschaft enthalten, die den Deprecation-Code identifiziert.
• 'ExperimentalWarning' - Zeigt die Verwendung einer experimentellen Node.js-API oder eines Features an. Solche Features sollten mit Vorsicht verwendet werden, da sie sich jederzeit ändern können und nicht denselben strengen Richtlinien zur semantischen Versionierung und langfristigen Unterstützung (LTS) wie unterstützte Features unterliegen.
• 'MaxListenersExceededWarning' - Zeigt an, dass zu viele Listener für ein gegebenes Ereignis bei einem EventEmitter oder EventTarget registriert wurden. Dies ist oft ein Hinweis auf ein Speicherleck.
• 'TimeoutOverflowWarning' - Zeigt an, dass ein numerischer Wert, der nicht in einen vorzeichenbehafteten 32-Bit-Integer passt, an die Funktionen setTimeout() oder setInterval() übergeben wurde.
• 'TimeoutNegativeWarning' - Zeigt an, dass eine negative Zahl an setTimeout() oder setInterval() übergeben wurde.
• 'TimeoutNaNWarning' - Zeigt an, dass ein Wert, der keine Zahl ist, an setTimeout() oder setInterval() übergeben wurde.
• 'UnsupportedWarning' - Zeigt die Verwendung einer nicht unterstützten Option oder eines Features an, die/das ignoriert wird, anstatt als Fehler behandelt zu werden. Ein Beispiel ist die Verwendung der HTTP-Antwortstatusmeldung bei Nutzung der HTTP/2-Kompatibilitäts-API.

Ereignis: 'worker'#

• worker <Worker> Der <Worker>, der erstellt wurde.

Das 'worker'-Ereignis wird ausgelöst, nachdem ein neuer <Worker>-Thread erstellt wurde.

Signalereignisse#

Signalereignisse werden ausgelöst, wenn der Node.js-Prozess ein Signal empfängt. Bitte beachten Sie signal(7) für eine Auflistung von Standard-POSIX-Signalnamen wie 'SIGINT', 'SIGHUP' usw.

Signale sind in Worker-Threads nicht verfügbar.

Der Signal-Handler empfängt den Namen des Signals ('SIGINT', 'SIGTERM' usw.) als erstes Argument.

Der Name jedes Ereignisses ist der allgemeine Name des Signals in Großbuchstaben (z. B. 'SIGINT' für SIGINT-Signale).

import process from 'node:process';

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);
const process = require('node:process');

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);
copy

• 'SIGUSR1' ist für Node.js reserviert, um den Debugger zu starten. Es ist möglich, einen Listener zu installieren, aber dies könnte den Debugger stören.
• 'SIGTERM' und 'SIGINT' haben auf Nicht-Windows-Plattformen Standard-Handler, die den Terminalmodus zurücksetzen, bevor sie mit dem Code 128 + Signalnummer beendet werden. Wenn für eines dieser Signale ein Listener installiert ist, wird dessen Standardverhalten entfernt (Node.js wird nicht mehr automatisch beendet).
• 'SIGPIPE' wird standardmäßig ignoriert. Es kann ein Listener installiert werden.
• 'SIGHUP' wird unter Windows generiert, wenn das Konsolenfenster geschlossen wird, und auf anderen Plattformen unter verschiedenen ähnlichen Bedingungen. Siehe signal(7). Es kann ein Listener installiert werden, jedoch wird Node.js unter Windows etwa 10 Sekunden später bedingungslos beendet. Auf Nicht-Windows-Plattformen besteht das Standardverhalten von SIGHUP darin, Node.js zu beenden, aber sobald ein Listener installiert wurde, wird dieses Standardverhalten entfernt.
• 'SIGTERM' wird unter Windows nicht unterstützt, es kann jedoch darauf gewartet werden.
• 'SIGINT' vom Terminal wird auf allen Plattformen unterstützt und kann normalerweise mit Strg+C generiert werden (obwohl dies konfigurierbar sein kann). Es wird nicht generiert, wenn der Terminal-Rohmodus aktiviert ist und Strg+C verwendet wird.
• 'SIGBREAK' wird unter Windows geliefert, wenn Strg+Pause gedrückt wird. Auf Nicht-Windows-Plattformen kann darauf gewartet werden, aber es gibt keine Möglichkeit, es zu senden oder zu generieren.
• 'SIGWINCH' wird geliefert, wenn die Größe der Konsole geändert wurde. Unter Windows passiert dies nur beim Schreiben in die Konsole, wenn der Cursor bewegt wird oder wenn ein lesbares TTY im Rohmodus verwendet wird.
• 'SIGKILL' kann keinen Listener installiert bekommen; es beendet Node.js auf allen Plattformen bedingungslos.
• 'SIGSTOP' kann keinen Listener installiert bekommen.
• 'SIGBUS', 'SIGFPE', 'SIGSEGV' und 'SIGILL' lassen, wenn sie nicht künstlich mittels kill(2) ausgelöst wurden, den Prozess inhärent in einem Zustand zurück, aus dem es nicht sicher ist, JS-Listener aufzurufen. Dies könnte dazu führen, dass der Prozess nicht mehr reagiert.
• 0 kann gesendet werden, um die Existenz eines Prozesses zu testen; es hat keine Auswirkungen, wenn der Prozess existiert, wirft aber einen Fehler, wenn der Prozess nicht existiert.

Windows unterstützt keine Signale und hat daher kein Äquivalent zur Beendigung durch Signal, aber Node.js bietet einige Emulationen mit process.kill() und subprocess.kill().

• Das Senden von SIGINT, SIGTERM und SIGKILL führt zur bedingungslosen Beendigung des Zielprozesses, und danach wird der Subprozess melden, dass der Prozess durch ein Signal beendet wurde.
• Das Senden des Signals 0 kann als plattformunabhängige Methode zum Testen auf die Existenz eines Prozesses verwendet werden.

process.abort()#

Die process.abort()-Methode veranlasst den Node.js-Prozess, sofort zu beenden und eine Core-Datei zu generieren.

Dieses Feature ist in Worker-Threads nicht verfügbar.

process.addUncaughtExceptionCaptureCallback(fn)#

• fn <Function>

Die process.addUncaughtExceptionCaptureCallback()-Funktion fügt einen Callback hinzu, der aufgerufen wird, wenn eine nicht abgefangene Ausnahme auftritt, wobei der Ausnahme-Wert als erstes Argument empfangen wird.

Im Gegensatz zu process.setUncaughtExceptionCaptureCallback() ermöglicht diese Funktion das Registrieren mehrerer Callbacks und steht nicht im Konflikt mit dem domain-Modul. Callbacks werden in umgekehrter Reihenfolge der Registrierung aufgerufen (zuletzt registrierte zuerst). Wenn ein Callback true zurückgibt, werden nachfolgende Callbacks und die Standard-Behandlung nicht abgefangener Ausnahmen übersprungen.

import process from 'node:process';

process.addUncaughtExceptionCaptureCallback((err) => {
  console.error('Caught exception:', err.message);
  return true; // Indicates exception was handled
});
const process = require('node:process');

process.addUncaughtExceptionCaptureCallback((err) => {
  console.error('Caught exception:', err.message);
  return true; // Indicates exception was handled
});
copy

process.allowedNodeEnvironmentFlags#

• Typ: <Set>

Die process.allowedNodeEnvironmentFlags-Eigenschaft ist ein spezielles, schreibgeschütztes Set von Flags, die innerhalb der Umgebungsvariable NODE_OPTIONS zulässig sind.

process.allowedNodeEnvironmentFlags erweitert Set, überschreibt jedoch Set.prototype.has, um verschiedene mögliche Flag-Repräsentationen zu erkennen. process.allowedNodeEnvironmentFlags.has() gibt true in den folgenden Fällen zurück:

• Flags können führende einfache (-) oder doppelte (--) Bindestriche auslassen; z. B. inspect-brk für --inspect-brk oder r für -r.
• Flags, die an V8 weitergegeben werden (wie in --v8-options aufgelistet), können einen oder mehrere nicht-führende Bindestriche durch einen Unterstrich ersetzen oder umgekehrt; z. B. --perf_basic_prof, --perf-basic-prof, --perf_basic-prof usw.
• Flags können ein oder mehrere Gleichheitszeichen (=) enthalten; alle Zeichen nach und einschließlich des ersten Gleichheitszeichens werden ignoriert; z. B. --stack-trace-limit=100.
• Flags müssen innerhalb von NODE_OPTIONS zulässig sein.

Beim Iterieren über process.allowedNodeEnvironmentFlags erscheinen Flags nur einmal; jedes beginnt mit einem oder mehreren Bindestrichen. An V8 weitergegebene Flags enthalten Unterstriche anstelle von nicht-führenden Bindestrichen.

import { allowedNodeEnvironmentFlags } from 'node:process';

allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});
const { allowedNodeEnvironmentFlags } = require('node:process');

allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});
copy

Die Methoden add(), clear() und delete() von process.allowedNodeEnvironmentFlags bewirken nichts und schlagen stillschweigend fehl.

Wenn Node.js ohne NODE_OPTIONS-Unterstützung kompiliert wurde (angezeigt in process.config), enthält process.allowedNodeEnvironmentFlags das, was zulässig gewesen wäre.

process.arch#

• Typ: <string>

Die CPU-Architektur des Betriebssystems, für die das Node.js-Binärprogramm kompiliert wurde. Mögliche Werte sind: 'arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc64', 'riscv64', 's390', 's390x' und 'x64'.

import { arch } from 'node:process';

console.log(`This processor architecture is ${arch}`);
const { arch } = require('node:process');

console.log(`This processor architecture is ${arch}`);
copy

process.argv#

• Typ: <string[]>

Die process.argv-Eigenschaft gibt ein Array mit den Kommandozeilenargumenten zurück, die beim Start des Node.js-Prozesses übergeben wurden. Das erste Element ist process.execPath. Siehe process.argv0, wenn der Zugriff auf den ursprünglichen Wert von argv[0] benötigt wird. Wenn ein Programm-Einstiegspunkt bereitgestellt wurde, ist das zweite Element der absolute Pfad dazu. Die verbleibenden Elemente sind zusätzliche Kommandozeilenargumente.

Zum Beispiel, unter der Annahme des folgenden Skripts für process-args.js:

import { argv } from 'node:process';

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});
const { argv } = require('node:process');

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});
copy

Der Aufruf des Node.js-Prozesses als:

node process-args.js one two=three four
copy

Würde die Ausgabe erzeugen:

0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four
copy

process.argv0#

• Typ: <string>

Die process.argv0-Eigenschaft speichert eine schreibgeschützte Kopie des ursprünglichen Werts von argv[0], der beim Start von Node.js übergeben wurde.

$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0'
copy

process.availableMemory()#

• Gibt zurück: <number>

Ermittelt die Menge an freiem Speicher, die dem Prozess noch zur Verfügung steht (in Bytes).

Siehe uv_get_available_memory für weitere Informationen.

process.channel#

• Typ: <Object>

Wenn der Node.js-Prozess mit einem IPC-Kanal gestartet wurde (siehe die Dokumentation zu Child Process), ist die process.channel-Eigenschaft eine Referenz auf den IPC-Kanal. Wenn kein IPC-Kanal existiert, ist diese Eigenschaft undefined.

process.channel.ref()#

Diese Methode veranlasst den IPC-Kanal dazu, die Event-Loop des Prozesses am Laufen zu halten, falls zuvor .unref() aufgerufen wurde.

Dies wird typischerweise über die Anzahl der 'disconnect'- und 'message'-Listener am process-Objekt verwaltet. Diese Methode kann jedoch verwendet werden, um explizit ein bestimmtes Verhalten anzufordern.

process.channel.unref()#

Diese Methode bewirkt, dass der IPC-Kanal die Event-Loop des Prozesses nicht am Laufen hält und ermöglicht es ihr, auch bei offenem Kanal zu beenden.

Dies wird typischerweise über die Anzahl der 'disconnect'- und 'message'-Listener am process-Objekt verwaltet. Diese Methode kann jedoch verwendet werden, um explizit ein bestimmtes Verhalten anzufordern.

process.chdir(directory)#

• directory <string>

Die process.chdir()-Methode ändert das aktuelle Arbeitsverzeichnis des Node.js-Prozesses oder wirft eine Ausnahme, falls dies fehlschlägt (z. B. wenn das angegebene directory nicht existiert).

import { chdir, cwd } from 'node:process';

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}
const { chdir, cwd } = require('node:process');

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}
copy

Dieses Feature ist in Worker-Threads nicht verfügbar.

process.config#

• Typ: <Object>

Die process.config-Eigenschaft gibt ein eingefrorenes Object zurück, das die JavaScript-Repräsentation der Konfigurationsoptionen enthält, die zum Kompilieren der aktuellen Node.js-Ausführungsdatei verwendet wurden. Dies entspricht der Datei config.gypi, die beim Ausführen des ./configure-Skripts erstellt wurde.

Ein Beispiel für die mögliche Ausgabe sieht so aus:

{
  target_defaults:
   { cflags: [],
     default_configuration: 'Release',
     defines: [],
     include_dirs: [],
     libraries: [] },
  variables:
   {
     host_arch: 'x64',
     napi_build_version: 5,
     node_install_npm: 'true',
     node_prefix: '',
     node_shared_cares: 'false',
     node_shared_http_parser: 'false',
     node_shared_libuv: 'false',
     node_shared_zlib: 'false',
     node_use_openssl: 'true',
     node_shared_openssl: 'false',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
}
copy

process.connected#

• Typ: <boolean>

Wenn der Node.js-Prozess mit einem IPC-Kanal gestartet wurde (siehe die Dokumentation zu Child Process und Cluster), gibt die process.connected-Eigenschaft true zurück, solange der IPC-Kanal verbunden ist, und false, nachdem process.disconnect() aufgerufen wurde.

Sobald process.connected false ist, ist es nicht mehr möglich, Nachrichten über den IPC-Kanal mittels process.send() zu senden.

process.constrainedMemory()#

• Gibt zurück: <number>

Ermittelt die dem Prozess zur Verfügung stehende Speichermenge (in Bytes) basierend auf den vom Betriebssystem auferlegten Beschränkungen. Wenn keine solche Beschränkung existiert oder die Beschränkung unbekannt ist, wird 0 zurückgegeben.

Siehe uv_get_constrained_memory für weitere Informationen.

process.cpuUsage([previousValue])#

• previousValue <Object> Ein früherer Rückgabewert eines Aufrufs von process.cpuUsage().
• Rückgabewert: <Object>
  • user <integer>
  • system <integer>

Die process.cpuUsage()-Methode gibt die Benutzer- und System-CPU-Zeitnutzung des aktuellen Prozesses zurück, in einem Objekt mit den Eigenschaften user und system, deren Werte Mikrosekunden sind (Millionstel Sekunde). Diese Werte messen die Zeit, die jeweils im Benutzer- und Systemcode verbracht wurde, und können letztendlich größer sein als die tatsächlich verstrichene Zeit, wenn mehrere CPU-Kerne für diesen Prozess arbeiten.

Das Ergebnis eines vorherigen Aufrufs von process.cpuUsage() kann als Argument an die Funktion übergeben werden, um eine Differenzmessung zu erhalten.

import { cpuUsage } from 'node:process';

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }
const { cpuUsage } = require('node:process');

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }
copy

process.cwd()#

• Rückgabe: <string>

Die process.cwd()-Methode gibt das aktuelle Arbeitsverzeichnis des Node.js-Prozesses zurück.

import { cwd } from 'node:process';

console.log(`Current directory: ${cwd()}`);
const { cwd } = require('node:process');

console.log(`Current directory: ${cwd()}`);
copy

process.debugPort#

• Typ: <number>

Der Port, der vom Node.js-Debugger verwendet wird, wenn dieser aktiviert ist.

import process from 'node:process';

process.debugPort = 5858;
const process = require('node:process');

process.debugPort = 5858;
copy

process.disconnect()#

Wenn der Node.js-Prozess mit einem IPC-Kanal gestartet wurde, schließt die process.disconnect()-Methode den IPC-Kanal zum Elternprozess, wodurch der Kindprozess ordnungsgemäß beendet werden kann, sobald keine anderen Verbindungen mehr bestehen, die ihn am Leben erhalten.

Die Wirkung des Aufrufs von process.disconnect() ist die gleiche wie der Aufruf von ChildProcess.disconnect() vom Elternprozess aus.

Wenn der Node.js-Prozess nicht mit einem IPC-Kanal gestartet wurde, wird process.disconnect() undefined sein.

process.dlopen(module, filename[, flags])#

• module <Object>
• filename <string>
• flags <os.constants.dlopen> Standard: os.constants.dlopen.RTLD_LAZY

Die process.dlopen()-Methode ermöglicht das dynamische Laden von Shared Objects. Sie wird primär von require() zum Laden von C++-Addons verwendet und sollte außer in speziellen Fällen nicht direkt verwendet werden. Mit anderen Worten, require() sollte gegenüber process.dlopen() bevorzugt werden, es sei denn, es gibt spezifische Gründe, wie benutzerdefinierte dlopen-Flags oder das Laden aus ES-Modulen.

Das flags-Argument ist ein Integer, der die Spezifikation des dlopen-Verhaltens ermöglicht. Siehe die Dokumentation zu os.constants.dlopen für Details.

Eine wichtige Voraussetzung beim Aufruf von process.dlopen() ist, dass die module-Instanz übergeben werden muss. Funktionen, die vom C++-Addon exportiert werden, sind dann über module.exports zugänglich.

Das untenstehende Beispiel zeigt, wie ein C++-Addon namens local.node geladen wird, das eine foo-Funktion exportiert. Alle Symbole werden geladen, bevor der Aufruf zurückkehrt, indem die Konstante RTLD_NOW übergeben wird. In diesem Beispiel wird davon ausgegangen, dass die Konstante verfügbar ist.

import { dlopen } from 'node:process';
import { constants } from 'node:os';
import { fileURLToPath } from 'node:url';

const module = { exports: {} };
dlopen(module, fileURLToPath(new URL('local.node', import.meta.url)),
       constants.dlopen.RTLD_NOW);
module.exports.foo();
const { dlopen } = require('node:process');
const { constants } = require('node:os');
const { join } = require('node:path');

const module = { exports: {} };
dlopen(module, join(__dirname, 'local.node'), constants.dlopen.RTLD_NOW);
module.exports.foo();
copy

process.emitWarning(warning[, options])#

• warning <string> | <Error> Die Warnung, die ausgegeben werden soll.
• options <Object>
  • type <string> Wenn warning ein String ist, ist type der Name, der für die Art der ausgegebenen Warnung verwendet wird. Standard: 'Warning'.
  • code <string> Ein eindeutiger Identifikator für die ausgegebene Warnungsinstanz.
  • ctor <Function> Wenn warning ein String ist, ist ctor eine optionale Funktion, die verwendet wird, um den generierten Stack-Trace zu begrenzen. Standard: process.emitWarning.
  • detail <string> Zusätzlicher Text, der in den Fehler aufgenommen werden soll.

Die process.emitWarning()-Methode kann verwendet werden, um benutzerdefinierte oder anwendungsspezifische Prozesswarnungen auszugeben. Diese können abgehört werden, indem ein Handler zum 'warning'-Ereignis hinzugefügt wird.

import { emitWarning } from 'node:process';

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information
const { emitWarning } = require('node:process');

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information
copy

In diesem Beispiel wird intern von process.emitWarning() ein Error-Objekt generiert und an den 'warning'-Handler weitergereicht.

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});
const process = require('node:process');

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});
copy

Wenn warning als Error-Objekt übergeben wird, wird das options-Argument ignoriert.

process.emitWarning(warning[, type[, code]][, ctor])#

• warning <string> | <Error> Die Warnung, die ausgegeben werden soll.
• type <string> Wenn warning ein String ist, ist type der Name, der für die Art der ausgegebenen Warnung verwendet wird. Standard: 'Warning'.
• code <string> Ein eindeutiger Identifikator für die ausgegebene Warnungsinstanz.
• ctor <Function> Wenn warning ein String ist, ist ctor eine optionale Funktion, die verwendet wird, um den generierten Stack-Trace zu begrenzen. Standard: process.emitWarning.

Die process.emitWarning()-Methode kann verwendet werden, um benutzerdefinierte oder anwendungsspezifische Prozesswarnungen auszugeben. Diese können abgehört werden, indem ein Handler zum 'warning'-Ereignis hinzugefügt wird.

import { emitWarning } from 'node:process';

// Emit a warning using a string.
emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!
const { emitWarning } = require('node:process');

// Emit a warning using a string.
emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!
copy

import { emitWarning } from 'node:process';

// Emit a warning using a string and a type.
emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!
const { emitWarning } = require('node:process');

// Emit a warning using a string and a type.
emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!
copy

import { emitWarning } from 'node:process';

emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
const { emitWarning } = require('node:process');

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
copy

In jedem der vorherigen Beispiele wird intern von process.emitWarning() ein Error-Objekt generiert und an den 'warning'-Handler weitergereicht.

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});
const process = require('node:process');

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});
copy

Wenn warning als Error-Objekt übergeben wird, wird es unverändert an den 'warning'-Event-Handler weitergereicht (und die optionalen Argumente type, code und ctor werden ignoriert).

import { emitWarning } from 'node:process';

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
const { emitWarning } = require('node:process');

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!
copy

Ein TypeError wird geworfen, wenn warning etwas anderes als ein String oder ein Error-Objekt ist.

Obwohl Prozesswarnungen Error-Objekte verwenden, ist der Prozesswarnungsmechanismus kein Ersatz für normale Fehlerbehandlungsmechanismen.

Die folgende zusätzliche Behandlung wird implementiert, wenn der Warnungstyp 'DeprecationWarning' ist:

• Wenn das Kommandozeilenflag --throw-deprecation verwendet wird, wird die Deprecation-Warnung als Ausnahme geworfen, anstatt als Ereignis ausgegeben zu werden.
• Wenn das Kommandozeilenflag --no-deprecation verwendet wird, wird die Deprecation-Warnung unterdrückt.
• Wenn das Kommandozeilenflag --trace-deprecation verwendet wird, wird die Deprecation-Warnung zusammen mit dem vollständigen Stack-Trace an stderr ausgegeben.

Vermeidung doppelter Warnungen#

Als bewährte Methode sollten Warnungen nur einmal pro Prozess ausgegeben werden. Platzieren Sie dazu den emitWarning()-Aufruf hinter einer Booleschen Variable.

import { emitWarning } from 'node:process';

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothing
const { emitWarning } = require('node:process');

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothing
copy

process.env#

• Typ: <Object>

Die process.env-Eigenschaft gibt ein Objekt zurück, das die Benutzerumgebung enthält. Siehe environ(7).

Ein Beispiel für dieses Objekt sieht so aus:

{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
}
copy

Es ist möglich, dieses Objekt zu ändern, aber solche Änderungen werden außerhalb des Node.js-Prozesses nicht reflektiert, oder (sofern nicht explizit angefordert) nicht an andere Worker-Threads. Mit anderen Worten, das folgende Beispiel würde nicht funktionieren:

node -e 'process.env.foo = "bar"' && echo $foo
copy

Während das Folgende funktionieren würde:

import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);
const { env } = require('node:process');

env.foo = 'bar';
console.log(env.foo);
copy

Das Zuweisen einer Eigenschaft an process.env konvertiert den Wert implizit in einen String. Dieses Verhalten ist veraltet. Zukünftige Versionen von Node.js könnten einen Fehler werfen, wenn der Wert kein String, keine Zahl oder kein Boolescher Wert ist.

import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
const { env } = require('node:process');

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
copy

Verwenden Sie delete, um eine Eigenschaft aus process.env zu löschen.

import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
const { env } = require('node:process');

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
copy

Auf Windows-Betriebssystemen sind Umgebungsvariablen groß-/kleinschreibungsunabhängig.

import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1
const { env } = require('node:process');

env.TEST = 1;
console.log(env.test);
// => 1
copy

Sofern beim Erstellen einer Worker-Instanz nicht explizit angegeben, hat jeder Worker-Thread seine eigene Kopie von process.env, basierend auf dem process.env seines übergeordneten Threads oder was auch immer als env-Option an den Worker-Konstruktor übergeben wurde. Änderungen an process.env sind nicht über Worker-Threads hinweg sichtbar, und nur der Hauptthread kann Änderungen vornehmen, die für das Betriebssystem oder für native Add-ons sichtbar sind. Unter Windows arbeitet eine Kopie von process.env in einer Worker-Instanz im Gegensatz zum Hauptthread auf eine Art, die Groß-/Kleinschreibung beachtet.

process.execArgv#

• Typ: <string[]>

Die process.execArgv-Eigenschaft gibt die Menge der Node.js-spezifischen Kommandozeilenoptionen zurück, die beim Start des Node.js-Prozesses übergeben wurden. Diese Optionen erscheinen nicht im Array, das von der process.argv-Eigenschaft zurückgegeben wird, und beinhalten nicht die Node.js-Ausführungsdatei, den Namen des Skripts oder Optionen, die auf den Skriptnamen folgen. Diese Optionen sind nützlich, um Kindprozesse mit derselben Ausführungsumgebung wie der Elternprozess zu starten.

node --icu-data-dir=./foo --require ./bar.js script.js --version
copy

Führt in process.execArgv zu:

["--icu-data-dir=./foo", "--require", "./bar.js"]
copy

Und process.argv:

['/usr/local/bin/node', 'script.js', '--version']
copy

Siehe Worker-Konstruktor für das detaillierte Verhalten von Worker-Threads mit dieser Eigenschaft.

process.execPath#

• Typ: <string>

Die process.execPath-Eigenschaft gibt den absoluten Pfadnamen der ausführbaren Datei zurück, die den Node.js-Prozess gestartet hat. Symbolische Links werden, falls vorhanden, aufgelöst.

'/usr/local/bin/node'
copy

process.execve(file[, args[, env]])#

• file <string> Der Name oder Pfad der auszuführenden Datei.
• args <string[]> Liste von String-Argumenten. Kein Argument darf ein Null-Byte (\u0000) enthalten.
• env <Object> Umgebung Schlüssel-Wert-Paare. Kein Schlüssel oder Wert darf ein Null-Byte (\u0000) enthalten. Standard: process.env.

Ersetzt den aktuellen Prozess durch einen neuen Prozess.

Dies wird durch die Verwendung der POSIX-Funktion execve erreicht, weshalb kein Speicher oder andere Ressourcen des aktuellen Prozesses erhalten bleiben, mit Ausnahme der Standard-Eingabe-, Standard-Ausgabe- und Standard-Fehler-Dateideskriptoren.

Alle anderen Ressourcen werden vom System verworfen, wenn die Prozesse ausgetauscht werden, ohne dass Exit- oder Close-Ereignisse ausgelöst werden und ohne dass Bereinigungs-Handler ausgeführt werden.

Diese Funktion kehrt niemals zurück, es sei denn, ein Fehler ist aufgetreten.

Diese Funktion ist unter Windows oder IBM i nicht verfügbar.

process.exit([code])#

• code <integer> | <string> | <null> | <undefined> Der Exit-Code. Bei String-Typ sind nur Integer-Strings (z. B. '1') erlaubt. Standard: 0.

Die process.exit()-Methode weist Node.js an, den Prozess synchron mit einem Exit-Status von code zu beenden. Wenn code weggelassen wird, verwendet exit entweder den 'Erfolgs'-Code 0 oder den Wert von process.exitCode, falls dieser gesetzt wurde. Node.js wird nicht beendet, bis alle 'exit'-Event-Listener aufgerufen wurden.

Um mit einem 'Fehler'-Code zu beenden:

import { exit } from 'node:process';

exit(1);
const { exit } = require('node:process');

exit(1);
copy

Die Shell, die Node.js ausgeführt hat, sollte den Exit-Code als 1 sehen.

Der Aufruf von process.exit() zwingt den Prozess dazu, so schnell wie möglich zu beenden, selbst wenn noch asynchrone Operationen ausstehen, die noch nicht vollständig abgeschlossen sind, einschließlich E/A-Operationen an process.stdout und process.stderr.

In den meisten Situationen ist es nicht tatsächlich notwendig, process.exit() explizit aufzurufen. Der Node.js-Prozess wird von alleine beenden, wenn keine weiteren Arbeiten in der Event-Loop anstehen. Die process.exitCode-Eigenschaft kann gesetzt werden, um dem Prozess mitzuteilen, welcher Exit-Code verwendet werden soll, wenn der Prozess ordnungsgemäß beendet wird.

Beispielsweise illustriert das folgende Beispiel einen Missbrauch der process.exit()-Methode, der dazu führen könnte, dass an stdout ausgegebene Daten abgeschnitten und verloren gehen:

import { exit } from 'node:process';

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}
const { exit } = require('node:process');

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}
copy

Der Grund, warum dies problematisch ist, liegt darin, dass Schreibvorgänge an process.stdout in Node.js manchmal asynchron sind und über mehrere Ticks der Node.js Event-Loop hinweg auftreten können. Der Aufruf von process.exit() zwingt den Prozess jedoch dazu, zu beenden, bevor diese zusätzlichen Schreibvorgänge an stdout durchgeführt werden können.

Anstatt process.exit() direkt aufzurufen, sollte der Code das process.exitCode setzen und dem Prozess ermöglichen, natürlich zu beenden, indem das Einplanen weiterer Arbeiten für die Event-Loop vermieden wird:

import process from 'node:process';

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}
const process = require('node:process');

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}
copy

Wenn es notwendig ist, den Node.js-Prozess aufgrund einer Fehlerbedingung zu beenden, ist das Werfen eines nicht abgefangenen Fehlers und das Zulassen, dass der Prozess entsprechend beendet wird, sicherer als der Aufruf von process.exit().

In Worker-Threads stoppt diese Funktion den aktuellen Thread anstelle des aktuellen Prozesses.

process.exitCode#

• Typ: <integer> | <string> | <null> | <undefined> Der Exit-Code. Bei String-Typ sind nur Integer-Strings (z. B. '1') erlaubt. Standard: undefined.

Eine Zahl, die der Prozess-Exit-Code ist, wenn der Prozess entweder ordnungsgemäß beendet wird oder über process.exit() beendet wird, ohne einen Code anzugeben.

Der Wert von process.exitCode kann aktualisiert werden, indem entweder process.exitCode ein Wert zugewiesen wird oder ein Argument an process.exit() übergeben wird.

$ node -e 'process.exitCode = 9'; echo $?
9
$ node -e 'process.exit(42)'; echo $?
42
$ node -e 'process.exitCode = 9; process.exit(42)'; echo $?
42
copy

Der Wert kann auch implizit von Node.js gesetzt werden, wenn nicht behebbare Fehler auftreten (z. B. beim Auftreten eines ungelösten Top-Level-Await). Explizite Manipulationen des Exit-Codes haben jedoch immer Vorrang vor impliziten.

$ node --input-type=module -e 'await new Promise(() => {})'; echo $?
13
$ node --input-type=module -e 'process.exitCode = 9; await new Promise(() => {})'; echo $?
9
copy

process.features.cached_builtins#

• Typ: <boolean>

Ein boolescher Wert, der true ist, wenn der aktuelle Node.js-Build eingebaute Module zwischenspeichert.

process.features.debug#

• Typ: <boolean>

Ein boolescher Wert, der true ist, wenn der aktuelle Node.js-Build ein Debug-Build ist.

process.features.inspector#

• Typ: <boolean>

Ein boolescher Wert, der true ist, wenn der aktuelle Node.js-Build den Inspektor enthält.

process.features.ipv6#

process.features.require_module#

• Typ: <boolean>

Ein boolescher Wert, der true ist, wenn der aktuelle Node.js-Build das Laden von ECMAScript-Modulen mittels require() unterstützt.

process.features.tls#

• Typ: <boolean>

Ein boolescher Wert, der true ist, wenn der aktuelle Node.js-Build Unterstützung für TLS enthält.

process.features.tls_alpn#

process.features.tls_ocsp#

process.features.tls_sni#

process.features.typescript#

• Typ: <boolean> | <string>

Ein Wert, der standardmäßig "strip" ist und false, wenn Node.js mit --no-strip-types ausgeführt wird.

process.features.uv#

process.finalization.register(ref, callback)#

• ref <Object> | <Function> Die Referenz auf die Ressource, die verfolgt wird.
• callback <Function> Die Callback-Funktion, die aufgerufen wird, wenn die Ressource finalisiert wird.
• ref <Object> | <Function> Die Referenz auf die Ressource, die verfolgt wird.
• event <string> Das Ereignis, das die Finalisierung ausgelöst hat. Standardmäßig 'exit'.

Diese Funktion registriert einen Callback, der aufgerufen wird, wenn der Prozess das exit-Ereignis auslöst, falls das ref-Objekt nicht von der Garbage Collection bereinigt wurde. Wenn das ref-Objekt vor dem Auslösen des exit-Ereignisses bereinigt wurde, wird der Callback aus der Finalisierungs-Registry entfernt und beim Prozessende nicht aufgerufen.

Innerhalb des Callbacks können Sie die vom ref-Objekt zugewiesenen Ressourcen freigeben. Beachten Sie, dass alle für das beforeExit-Ereignis geltenden Einschränkungen auch für die callback-Funktion gelten; dies bedeutet, dass die Möglichkeit besteht, dass der Callback unter besonderen Umständen nicht aufgerufen wird.

Die Idee dieser Funktion ist es, Ihnen zu helfen, Ressourcen freizugeben, wenn der Prozess beendet wird, aber auch zuzulassen, dass das Objekt von der Garbage Collection bereinigt wird, wenn es nicht mehr verwendet wird.

Z. B.: Sie können ein Objekt registrieren, das einen Puffer enthält, und sicherstellen, dass dieser Puffer bei Prozessende freigegeben wird. Wenn das Objekt jedoch vor Prozessende bereinigt wird, müssen wir den Puffer nicht mehr freigeben, daher entfernen wir in diesem Fall einfach den Callback aus der Finalisierungs-Registry.

const { finalization } = require('node:process');

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  finalization.register(myDisposableObject, onFinalize);
}

setup();
import { finalization } from 'node:process';

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  finalization.register(myDisposableObject, onFinalize);
}

setup();
copy

Der obige Code stützt sich auf die folgenden Annahmen:

• Arrow-Funktionen werden vermieden.
• Reguläre Funktionen werden innerhalb des globalen Kontexts (Root) empfohlen.

Reguläre Funktionen könnten auf den Kontext verweisen, in dem das obj lebt, wodurch das obj nicht Garbage-Collection-fähig wird.

Arrow-Funktionen behalten den vorherigen Kontext bei. Betrachten Sie beispielsweise:

class Test {
  constructor() {
    finalization.register(this, (ref) => ref.dispose());

    // Even something like this is highly discouraged
    // finalization.register(this, () => this.dispose());
  }
  dispose() {}
}
copy

Es ist sehr unwahrscheinlich (nicht unmöglich), dass dieses Objekt von der Garbage Collection bereinigt wird, aber wenn dies nicht geschieht, wird dispose aufgerufen, wenn process.exit aufgerufen wird.

Seien Sie vorsichtig und verlassen Sie sich bei der Entsorgung kritischer Ressourcen nicht auf dieses Feature, da nicht garantiert ist, dass der Callback unter allen Umständen aufgerufen wird.

process.finalization.registerBeforeExit(ref, callback)#

• ref <Object> | <Function> Die Referenz auf die Ressource, die verfolgt wird.
• callback <Function> Die Callback-Funktion, die aufgerufen wird, wenn die Ressource finalisiert wird.
• ref <Object> | <Function> Die Referenz auf die Ressource, die verfolgt wird.
• event <string> Das Ereignis, das die Finalisierung ausgelöst hat. Standardmäßig 'beforeExit'.

Diese Funktion verhält sich genau wie register, außer dass der Callback aufgerufen wird, wenn der Prozess das beforeExit-Ereignis auslöst, falls das ref-Objekt nicht von der Garbage Collection bereinigt wurde.

Beachten Sie, dass alle für das beforeExit-Ereignis geltenden Einschränkungen auch für die callback-Funktion gelten; dies bedeutet, dass die Möglichkeit besteht, dass der Callback unter besonderen Umständen nicht aufgerufen wird.

process.finalization.unregister(ref)#

• ref <Object> | <Function> Die Referenz auf die Ressource, die zuvor registriert wurde.

Diese Funktion entfernt die Registrierung des Objekts aus der Finalisierungs-Registry, sodass der Callback nicht mehr aufgerufen wird.

const { finalization } = require('node:process');

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  finalization.register(myDisposableObject, onFinalize);

  // Do something

  myDisposableObject.dispose();
  finalization.unregister(myDisposableObject);
}

setup();
import { finalization } from 'node:process';

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  // Please make sure that the function passed to finalization.register()
  // does not create a closure around unnecessary objects.
  function onFinalize(obj, event) {
    // You can do whatever you want with the object
    obj.dispose();
  }

  finalization.register(myDisposableObject, onFinalize);

  // Do something

  myDisposableObject.dispose();
  finalization.unregister(myDisposableObject);
}

setup();
copy

process.getActiveResourcesInfo()#

• Rückgabe: <string[]>

Die process.getActiveResourcesInfo()-Methode gibt ein Array von Strings zurück, das die Typen der aktiven Ressourcen enthält, die derzeit die Event-Loop am Laufen halten.

import { getActiveResourcesInfo } from 'node:process';
import { setTimeout } from 'node:timers';

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]
const { getActiveResourcesInfo } = require('node:process');
const { setTimeout } = require('node:timers');

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]
copy

process.getBuiltinModule(id)#

• id <string> ID des angeforderten eingebauten Moduls.
• Rückgabe: <Object> | <undefined>

process.getBuiltinModule(id) bietet eine Möglichkeit, eingebaute Module in einer global verfügbaren Funktion zu laden. ES-Module, die andere Umgebungen unterstützen müssen, können dies verwenden, um ein Node.js-Modul bedingt zu laden, wenn es in Node.js ausgeführt wird, ohne sich mit Auflösungsfehlern auseinandersetzen zu müssen, die von import in einer Nicht-Node.js-Umgebung geworfen werden können, oder dynamische import()-Aufrufe verwenden zu müssen, die entweder das Modul in ein asynchrones Modul verwandeln oder eine synchrone API in eine asynchrone.

if (globalThis.process?.getBuiltinModule) {
  // Run in Node.js, use the Node.js fs module.
  const fs = globalThis.process.getBuiltinModule('fs');
  // If `require()` is needed to load user-modules, use createRequire()
  const module = globalThis.process.getBuiltinModule('module');
  const require = module.createRequire(import.meta.url);
  const foo = require('foo');
}
copy

Wenn id ein in der aktuellen Node.js-Prozessumgebung verfügbares eingebautes Modul spezifiziert, gibt die Methode process.getBuiltinModule(id) das entsprechende Modul zurück. Wenn id keinem eingebauten Modul entspricht, wird undefined zurückgegeben.

process.getBuiltinModule(id) akzeptiert eingebaute Modul-IDs, die von module.isBuiltin(id) erkannt werden. Einige eingebaute Module müssen mit dem node:-Präfix geladen werden, siehe eingebaute Module mit obligatorischem node:-Präfix. Die Referenzen, die von process.getBuiltinModule(id) zurückgegeben werden, zeigen immer auf das eingebaute Modul, das id entspricht, selbst wenn Benutzer require.cache so modifizieren, dass require(id) etwas anderes zurückgibt.

process.getegid()#

Die process.getegid()-Methode gibt die numerische effektive Gruppenidentität des Node.js-Prozesses zurück. (Siehe getegid(2).)

import process from 'node:process';

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}
const process = require('node:process');

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}
copy

Diese Funktion ist nur auf POSIX-Plattformen verfügbar (d. h. nicht unter Windows oder Android).

process.geteuid()#

• Rückgabewert: <Object>

Die process.geteuid()-Methode gibt die numerische effektive Benutzeridentität des Prozesses zurück. (Siehe geteuid(2).)

import process from 'node:process';

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}
const process = require('node:process');

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}
copy

Diese Funktion ist nur auf POSIX-Plattformen verfügbar (d. h. nicht unter Windows oder Android).

process.getgid()#

• Rückgabewert: <Object>

Die process.getgid()-Methode gibt die numerische Gruppenidentität des Prozesses zurück. (Siehe getgid(2).)

import process from 'node:process';

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}
const process = require('node:process');

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}
copy

Diese Funktion ist nur auf POSIX-Plattformen verfügbar (d. h. nicht unter Windows oder Android).

process.getgroups()#

• Gibt zurück: <integer[]>

Die process.getgroups()-Methode gibt ein Array mit den zusätzlichen Gruppen-IDs zurück. POSIX lässt offen, ob die effektive Gruppen-ID enthalten ist, aber Node.js stellt sicher, dass sie immer enthalten ist.

import process from 'node:process';

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}
const process = require('node:process');

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}
copy

Diese Funktion ist nur auf POSIX-Plattformen verfügbar (d. h. nicht unter Windows oder Android).

process.getuid()#

• Gibt zurück: <integer>

Die process.getuid()-Methode gibt die numerische Benutzeridentität des Prozesses zurück. (Siehe getuid(2).)

import process from 'node:process';

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}
const process = require('node:process');

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}
copy

Diese Funktion ist unter Windows nicht verfügbar.

process.hasUncaughtExceptionCaptureCallback()#

• Rückgabewert: <boolean>

Gibt an, ob ein Callback mit process.setUncaughtExceptionCaptureCallback() gesetzt wurde.

process.hrtime([time])#

• time <integer[]> Das Ergebnis eines vorherigen Aufrufs von process.hrtime()
• Gibt zurück: <integer[]>

Dies ist die veraltete Version von process.hrtime.bigint(), bevor bigint in JavaScript eingeführt wurde.

Die Methode process.hrtime() gibt die aktuelle hochauflösende Echtzeit als [Sekunden, Nanosekunden]-Tupel-Array zurück, wobei Nanosekunden den verbleibenden Teil der Echtzeit darstellt, der nicht mit Sekundengenauigkeit abgebildet werden kann.

time ist ein optionaler Parameter, der das Ergebnis eines vorherigen process.hrtime()-Aufrufs sein muss, um eine Differenz zur aktuellen Zeit zu bilden. Wenn der übergebene Parameter kein Tupel-Array ist, wird ein TypeError ausgelöst. Die Übergabe eines benutzerdefinierten Arrays anstelle des Ergebnisses eines vorherigen process.hrtime()-Aufrufs führt zu undefiniertem Verhalten.

Diese Zeiten beziehen sich auf einen willkürlichen Zeitpunkt in der Vergangenheit und stehen in keinem Zusammenhang mit der Tageszeit; sie unterliegen daher keiner Uhrendrift. Die Hauptverwendung liegt in der Leistungsmessung zwischen Zeitintervallen.

import { hrtime } from 'node:process';

const NS_PER_SEC = 1e9;
const time = hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);
const { hrtime } = require('node:process');

const NS_PER_SEC = 1e9;
const time = hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);
copy

process.hrtime.bigint()#

• Gibt zurück: <bigint>

Die bigint-Version der Methode process.hrtime() gibt die aktuelle hochauflösende Echtzeit in Nanosekunden als bigint zurück.

Im Gegensatz zu process.hrtime() unterstützt sie kein zusätzliches time-Argument, da die Differenz einfach durch Subtraktion der beiden bigint-Werte berechnet werden kann.

import { hrtime } from 'node:process';

const start = hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);
const { hrtime } = require('node:process');

const start = hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);
copy

process.initgroups(user, extraGroup)#

• user <string> | <number> Der Benutzername oder die numerische Kennung.
• extraGroup <string> | <number> Ein Gruppenname oder eine numerische Kennung.

Die Methode process.initgroups() liest die Datei /etc/group und initialisiert die Gruppenzugriffsliste unter Verwendung aller Gruppen, denen der Benutzer angehört. Dies ist eine privilegierte Operation, die erfordert, dass der Node.js-Prozess entweder root-Zugriff hat oder über die CAP_SETGID-Fähigkeit verfügt.

Seien Sie vorsichtig beim Ablegen von Privilegien.

import { getgroups, initgroups, setgid } from 'node:process';

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(getgroups());         // [ 27, 30, 46, 1000 ]
const { getgroups, initgroups, setgid } = require('node:process');

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(getgroups());         // [ 27, 30, 46, 1000 ]
copy

Diese Funktion ist nur auf POSIX-Plattformen verfügbar (d. h. nicht unter Windows oder Android). Dieses Feature ist in Worker-Threads nicht verfügbar.

process.kill(pid[, signal])#

• pid <number> Eine Prozess-ID
• signal <string> | <number> Das zu sendende Signal, entweder als String oder Zahl. Standard: 'SIGTERM'.

Die Methode process.kill() sendet das signal an den durch pid identifizierten Prozess.

Signalnamen sind Strings wie 'SIGINT' oder 'SIGHUP'. Weitere Informationen finden Sie unter Signalereignisse und kill(2).

Diese Methode löst einen Fehler aus, wenn die Ziel-pid nicht existiert. Als Spezialfall kann ein Signal von 0 verwendet werden, um die Existenz eines Prozesses zu prüfen. Windows-Plattformen lösen einen Fehler aus, wenn die pid zum Beenden einer Prozessgruppe verwendet wird.

Obwohl der Funktionsname process.kill() lautet, ist es tatsächlich nur ein Signal-Sender, vergleichbar mit dem kill-Systemaufruf. Das gesendete Signal kann etwas anderes bewirken, als den Zielprozess zu beenden.

import process, { kill } from 'node:process';

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

kill(process.pid, 'SIGHUP');
const process = require('node:process');

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

process.kill(process.pid, 'SIGHUP');
copy

Wenn SIGUSR1 von einem Node.js-Prozess empfangen wird, startet Node.js den Debugger. Siehe Signalereignisse.

process.loadEnvFile(path)#

• path <string> | <URL> | <Buffer> | <undefined>. Standard: './.env'

Lädt die .env-Datei in process.env. Die Verwendung von NODE_OPTIONS in der .env-Datei hat keine Auswirkungen auf Node.js.

const { loadEnvFile } = require('node:process');
loadEnvFile();
import { loadEnvFile } from 'node:process';
loadEnvFile();
copy

process.mainModule#

• Typ: <Object>

Die Eigenschaft process.mainModule bietet eine alternative Möglichkeit, auf require.main zuzugreifen. Der Unterschied besteht darin, dass, wenn sich das Hauptmodul zur Laufzeit ändert, require.main möglicherweise immer noch auf das ursprüngliche Hauptmodul verweist, in Modulen, die vor der Änderung angefordert wurden. Im Allgemeinen ist es sicher anzunehmen, dass beide auf dasselbe Modul verweisen.

Wie bei require.main ist process.mainModule undefined, wenn kein Einstiegsskript vorhanden ist.

process.memoryUsage()#

• Rückgabewert: <Object>
  • rss <integer>
  • heapTotal <integer>
  • heapUsed <integer>
  • external <integer>
  • arrayBuffers <integer>

Gibt ein Objekt zurück, das die Speichernutzung des Node.js-Prozesses in Bytes beschreibt.

import { memoryUsage } from 'node:process';

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }
const { memoryUsage } = require('node:process');

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }
copy

• heapTotal und heapUsed beziehen sich auf die Speichernutzung von V8.
• external bezieht sich auf die Speichernutzung von C++-Objekten, die an JavaScript-Objekte gebunden sind, welche von V8 verwaltet werden.
• rss (Resident Set Size) ist die Menge des im Hauptspeicher belegten Platzes für den Prozess, einschließlich aller C++- und JavaScript-Objekte und Code.
• arrayBuffers bezieht sich auf Speicher, der für ArrayBuffers und SharedArrayBuffers zugewiesen wurde, einschließlich aller Node.js-Buffers. Dies ist auch im external-Wert enthalten. Wenn Node.js als eingebettete Bibliothek verwendet wird, kann dieser Wert 0 sein, da Zuweisungen für ArrayBuffers in diesem Fall möglicherweise nicht nachverfolgt werden.

Bei Verwendung von Worker-Threads ist rss ein Wert, der für den gesamten Prozess gültig ist, während sich die anderen Felder nur auf den aktuellen Thread beziehen.

Die Methode process.memoryUsage() iteriert über jede Seite, um Informationen über die Speichernutzung zu sammeln, was je nach Speicherauslastung des Programms langsam sein kann.

Ein Hinweis zur Prozess-Speichernutzung (memoryUsage)#

Unter Linux oder anderen Systemen, auf denen glibc üblicherweise verwendet wird, kann eine Anwendung trotz stabilem heapTotal ein anhaltendes rss-Wachstum aufweisen, was auf Fragmentierung durch die glibc-malloc-Implementierung zurückzuführen ist. Siehe nodejs/node#21973 für Informationen zum Wechsel zu einer alternativen malloc-Implementierung zur Lösung des Leistungsproblems.

process.memoryUsage.rss()#

• Gibt zurück: <integer>

Die Methode process.memoryUsage.rss() gibt eine Ganzzahl zurück, die die Resident Set Size (RSS) in Bytes darstellt.

Die Resident Set Size ist die Menge des im Hauptspeicher belegten Platzes für den Prozess, einschließlich aller C++- und JavaScript-Objekte und Code.

Dies ist derselbe Wert wie die rss-Eigenschaft von process.memoryUsage(), aber process.memoryUsage.rss() ist schneller.

import { memoryUsage } from 'node:process';

console.log(memoryUsage.rss());
// 35655680
const { memoryUsage } = require('node:process');

console.log(memoryUsage.rss());
// 35655680
copy

process.nextTick(callback[, ...args])#

• callback <Function>
• ...args <any> Zusätzliche Argumente, die beim Aufruf des callback übergeben werden sollen.

process.nextTick() fügt den callback zur "Next Tick Queue" hinzu. Diese Warteschlange wird vollständig geleert, nachdem die aktuelle Operation auf dem JavaScript-Stack abgeschlossen ist und bevor die Event-Loop fortgesetzt werden darf. Es ist möglich, eine Endlosschleife zu erzeugen, wenn process.nextTick() rekursiv aufgerufen wird. Siehe die Event Loop-Anleitung für Hintergrundinformationen.

import { nextTick } from 'node:process';

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callback
const { nextTick } = require('node:process');

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callback
copy

Dies ist wichtig bei der Entwicklung von APIs, um Benutzern die Möglichkeit zu geben, Event-Handler zuzuweisen, nachdem ein Objekt konstruiert wurde, aber bevor I/O stattgefunden hat.

import { nextTick } from 'node:process';

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.
const { nextTick } = require('node:process');

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.
copy

Es ist sehr wichtig, dass APIs entweder zu 100 % synchron oder zu 100 % asynchron sind. Betrachten Sie dieses Beispiel:

// WARNING!  DO NOT USE!  BAD UNSAFE HAZARD!
function maybeSync(arg, cb) {
  if (arg) {
    cb();
    return;
  }

  fs.stat('file', cb);
}
copy

Diese API ist gefährlich, da im folgenden Fall:

const maybeTrue = Math.random() > 0.5;

maybeSync(maybeTrue, () => {
  foo();
});

bar();
copy

Es ist nicht klar, ob foo() oder bar() zuerst aufgerufen wird.

Der folgende Ansatz ist wesentlich besser:

import { nextTick } from 'node:process';

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}
const { nextTick } = require('node:process');

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}
copy

Wann queueMicrotask() vs. process.nextTick() verwenden#

Die API queueMicrotask() ist eine Alternative zu process.nextTick(), die anstelle der "Next Tick Queue" die Ausführung einer Funktion unter Verwendung derselben Microtask-Warteschlange verzögert, die auch für die then-, catch- und finally-Handler von aufgelösten Promises verwendet wird.

Innerhalb von Node.js wird jedes Mal, wenn die "Next Tick Queue" geleert wird, die Microtask-Warteschlange unmittelbar danach geleert.

In CJS-Modulen werden daher process.nextTick()-Callbacks immer vor queueMicrotask()-Callbacks ausgeführt. Da ESM-Module jedoch bereits als Teil der Microtask-Warteschlange verarbeitet werden, werden queueMicrotask()-Callbacks dort immer vor process.nextTick()-Callbacks ausgeführt, da Node.js bereits dabei ist, die Microtask-Warteschlange zu leeren.

import { nextTick } from 'node:process';

Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// resolve
// microtask
// nextTick
const { nextTick } = require('node:process');

Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// nextTick
// resolve
// microtask
copy