العملية

المصدر: lib/process.js

يوفر كائن process معلومات حول عملية Node.js الحالية والتحكم فيها.

ESM

import process from 'node:process'

CJS

const process = require('node:process')

أحداث العملية

كائن process هو مثيل لـ EventEmitter.

الحدث: 'beforeExit'

تم الإضافة في: v0.11.12

يتم إرسال حدث 'beforeExit' عندما تقوم Node.js بإفراغ حلقة الأحداث الخاصة بها وليس لديها عمل إضافي لجدولته. عادةً، ستخرج عملية Node.js عندما لا يكون هناك عمل مجدول، ولكن يمكن لمستمع مسجل على حدث 'beforeExit' إجراء مكالمات غير متزامنة، وبالتالي يتسبب في استمرار عملية Node.js.

يتم استدعاء دالة مُستمع المُستدعى بقيمة process.exitCode المُمرّرة كوسيط وحيد.

لا يتم إرسال حدث 'beforeExit' للظروف التي تسبب إنهاءً صريحًا، مثل استدعاء process.exit() أو الاستثناءات غير المُلْقَطَة.

يجب عدم استخدام 'beforeExit' كبديل لحدث 'exit' إلا إذا كان الهدف هو جدولة عمل إضافي.

ESM

import process from 'node:process'

process.on('beforeExit', code => {
  console.log('حدث Process beforeExit برمز: ', code)
})

process.on('exit', code => {
  console.log('حدث Process exit برمز: ', code)
})

console.log('سيتم عرض هذه الرسالة أولاً.')

// يطبع:
// سيتم عرض هذه الرسالة أولاً.
// حدث Process beforeExit برمز: 0
// حدث Process exit برمز: 0

CJS

const process = require('node:process')

process.on('beforeExit', code => {
  console.log('حدث Process beforeExit برمز: ', code)
})

process.on('exit', code => {
  console.log('حدث Process exit برمز: ', code)
})

console.log('سيتم عرض هذه الرسالة أولاً.')

// يطبع:
// سيتم عرض هذه الرسالة أولاً.
// حدث Process beforeExit برمز: 0
// حدث Process exit برمز: 0

حدث: 'disconnect'

مضاف في: v0.7.7

إذا تم إنشاء عملية Node.js بقناة IPC (راجع وثائق Child Process وCluster)، فسيتم إصدار حدث 'disconnect' عند إغلاق قناة IPC.

حدث: 'exit'

مضاف في: v0.1.7

• code <integer>

يتم إصدار حدث 'exit' عندما تكون عملية Node.js على وشك الخروج نتيجة لما يلي:

• استدعاء طريقة process.exit() صراحةً؛
• عدم وجود أي عمل إضافي يجب تنفيذه في حلقة أحداث Node.js.

لا توجد طريقة لمنع خروج حلقة الأحداث في هذه المرحلة، وبمجرد الانتهاء من تشغيل جميع مستمعي 'exit'، ستنتهي عملية Node.js.

يتم استدعاء دالة استدعاء المستمع برمز الخروج المحدد إما بواسطة خاصية process.exitCode، أو وسيطة exitCode المُمرّرة إلى طريقة process.exit().

ESM

import process from 'node:process'

process.on('exit', code => {
  console.log(`على وشك الخروج برمز: ${code}`)
})

CJS

const process = require('node:process')

process.on('exit', code => {
  console.log(`على وشك الخروج برمز: ${code}`)
})

يجب أن تقوم دوال المستمع فقط بتنفيذ عمليات متزامنة. ستخرج عملية Node.js فورًا بعد استدعاء مستمعي حدث 'exit' مما يتسبب في التخلي عن أي عمل إضافي لا يزال مُدرجًا في قائمة انتظار حلقة الأحداث. على سبيل المثال، في المثال التالي، لن يحدث أبدًا مهلة زمنية:

ESM

import process from 'node:process'

process.on('exit', code => {
  setTimeout(() => {
    console.log('لن يتم تشغيل هذا')
  }, 0)
})

CJS

const process = require('node:process')

process.on('exit', code => {
  setTimeout(() => {
    console.log('لن يتم تشغيل هذا')
  }, 0)
})

حدث: 'message'

تم الإضافة في: v0.5.10

• message <Object> | <boolean> | <number> | <string> | <null> كائن JSON تم تحليله أو قيمة بدائية قابلة للتسلسل.
• sendHandle <net.Server> | <net.Socket> كائن net.Server أو net.Socket، أو غير محدد.

إذا تم إنشاء عملية Node.js بقناة IPC (انظر وثائق Child Process وCluster)، يتم إصدار حدث 'message' كلما تم استلام رسالة أرسلتها عملية أبوية باستخدام childprocess.send() بواسطة العملية الفرعية.

تمر الرسالة بعملية التسلسل والتحليل. قد لا تكون الرسالة الناتجة هي نفسها الرسالة المرسلة في الأصل.

إذا تم تعيين خيار serialization إلى advanced المستخدم عند إنشاء العملية، فقد يحتوي الوسيط message على بيانات لا يمكن لـ JSON تمثيلها. راجع التسلسل المتقدم لـ child_process لمزيد من التفاصيل.

حدث: 'multipleResolves'

تم الإضافة في: v10.12.0

تم إهماله منذ: v17.6.0، v16.15.0

[مستقر: 0 - مهمل]

مستقر: 0 الثبات: 0 - مهمل

• type <string> نوع الحل. واحد من 'resolve' أو 'reject'.
• promise <Promise> الوعد الذي تم حله أو رفضه أكثر من مرة.
• value <any> القيمة التي تم حل الوعد بها أو رفضها بعد الحل الأصلي.

يتم إصدار حدث 'multipleResolves' كلما تم:

• حل وعد أكثر من مرة.
• رفض وعد أكثر من مرة.
• رفض بعد الحل.
• حل بعد الرفض.

هذا مفيد لتتبع الأخطاء المحتملة في تطبيق ما أثناء استخدام مُنشئ Promise، حيث يتم ابتلاع الحلول المتعددة بصمت. ومع ذلك، فإن حدوث هذا الحدث لا يشير بالضرورة إلى خطأ. على سبيل المثال، يمكن أن يؤدي Promise.race() إلى إصدار حدث 'multipleResolves'.

بسبب عدم موثوقية الحدث في حالات مثل المثال Promise.race() أعلاه، فقد تم إهماله.

ESM

import process from 'node:process'

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason)
  setImmediate(() => process.exit(1))
})

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call')
      resolve('Swallowed resolve')
      reject(new Error('Swallowed reject'))
    })
  } catch {
    throw new Error('Failed')
  }
}

main().then(console.log)
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First call

CJS

const process = require('node:process')

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason)
  setImmediate(() => process.exit(1))
})

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call')
      resolve('Swallowed resolve')
      reject(new Error('Swallowed reject'))
    })
  } catch {
    throw new Error('Failed')
  }
}

main().then(console.log)
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First call

الحدث: 'rejectionHandled'

مضاف في: v1.4.1

• promise <Promise> الوعد الذي تم التعامل معه مؤخراً.

يتم إصدار حدث 'rejectionHandled' كلما تم رفض Promise وتم إرفاق مُعالِج أخطاء به (باستخدام promise.catch() ، على سبيل المثال) بعد دورة واحدة من حلقة أحداث Node.js.

كان سيتم إصدار كائن Promise سابقًا في حدث 'unhandledRejection'، ولكن خلال عملية المعالجة، اكتسب مُعالِج رفض.

لا يوجد مفهوم لمستوى أعلى لسلسلة Promise يمكن دائمًا معالجة الرفض فيه. نظرًا لطبيعته غير المتزامنة، يمكن معالجة رفض Promise في وقت لاحق، ربما بعد وقت طويل من دورة حلقة الأحداث التي يتم فيها إصدار حدث 'unhandledRejection'.

طريقة أخرى لبيان هذا هي أنه، على عكس التعليمات البرمجية المتزامنة حيث توجد قائمة متزايدة باستمرار من الاستثناءات التي لم يتم التعامل معها، مع Promises، يمكن أن تكون هناك قائمة متزايدة ومتناقصة من الرفوض التي لم يتم التعامل معها.

في التعليمات البرمجية المتزامنة، يتم إصدار حدث 'uncaughtException' عندما تتزايد قائمة الاستثناءات التي لم يتم التعامل معها.

في التعليمات البرمجية غير المتزامنة، يتم إصدار حدث 'unhandledRejection' عندما تتزايد قائمة الرفوض التي لم يتم التعامل معها، ويتم إصدار حدث 'rejectionHandled' عندما تتقلص قائمة الرفوض التي لم يتم التعامل معها.

ESM

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)
})

CJS

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)
})

في هذا المثال، ستتزايد وتتقلص خريطة unhandledRejections Map بمرور الوقت، مما يعكس الرفوض التي تبدأ غير معالجة ثم تصبح معالجة. من الممكن تسجيل هذه الأخطاء في سجل الأخطاء، إما بشكل دوري (وهو الأفضل على الأرجح للتطبيقات طويلة التشغيل) أو عند خروج العملية (وهو الأنسب على الأرجح للبرامج النصية).

الحدث: 'workerMessage'

مضاف في: v22.5.0

• value <أي> قيمة مُرسلة باستخدام postMessageToThread().
• source <رقم> معرف مؤشر العمل الذي يُرسل الرسالة أو 0 للخيط الرئيسي.

يُصدر حدث 'workerMessage' لأي رسالة واردة مُرسلة من الطرف الآخر باستخدام postMessageToThread().

الحدث: 'uncaughtException'

[السجل]

الإصدار	التغييرات
v12.0.0, v10.17.0	تمت إضافة وسيطة origin.
v0.1.18	مضاف في: v0.1.18

• err <خطأ> الاستثناء غير المُعالج.
• origin <سلسلة> يُشير إلى ما إذا كان الاستثناء ينبع من رفض غير مُعالج أو من خطأ متزامن. يمكن أن يكون إما 'uncaughtException' أو 'unhandledRejection'. ويُستخدم الأخير عندما يحدث استثناء في سياق غير متزامن قائم على Promise (أو إذا تم رفض Promise) وعلامة --unhandled-rejections مُحددة على strict أو throw (وهو الإعداد الافتراضي) ولم يتم معالجة الرفض، أو عندما يحدث رفض أثناء مرحلة التحميل الثابت لوحدة ES في نقطة دخول سطر الأوامر.

يُصدر حدث 'uncaughtException' عندما يصل استثناء جافا سكريبت غير مُعالج إلى حلقة الأحداث. بشكل افتراضي، يُعالج Node.js هذه الاستثناءات بطباعة تتبع المكدس على stderr والخروج برمز 1، مع تجاوز أي process.exitCode مُحدد سابقًا. يُلغي إضافة مُعالج لحدث 'uncaughtException' هذا السلوك الافتراضي. بدلاً من ذلك، قم بتغيير process.exitCode في مُعالج 'uncaughtException' مما سيؤدي إلى خروج العملية برمز الخروج المُقدم. خلاف ذلك، في وجود مثل هذا المُعالج، ستخرج العملية برمز 0.

ESM

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.')

CJS

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.')

من الممكن مراقبة أحداث 'uncaughtException' دون تجاوز السلوك الافتراضي لإنهاء العملية عن طريق تثبيت مُستمع 'uncaughtExceptionMonitor'.

تحذير: استخدام 'uncaughtException' بشكل صحيح

'uncaughtException' آلية بدائية لمعالجة الاستثناءات، يُقصد بها أن تُستخدم كملاذ أخير فقط. يجب عدم استخدام الحدث كبديل لـ On Error Resume Next. تُشير الاستثناءات غير المعالجة بشكل جوهري إلى أن التطبيق في حالة غير مُعرّفة. إن محاولة استئناف كود التطبيق دون التعافي بشكل صحيح من الاستثناء قد يتسبب في مشاكل إضافية غير متوقعة وغير قابلة للتنبؤ.

لن يتم التقاط الاستثناءات التي يتم طرحها من داخل مُعالِج الأحداث. بدلاً من ذلك، ستخرج العملية برمز خروج غير صفري، وسيتم طباعة تتبع المكدس. هذا لتجنب التكرار اللانهائي.

إن محاولة الاستئناف بشكل طبيعي بعد استثناء غير معالج قد يكون مشابهًا لسحب سلك الطاقة عند ترقية جهاز كمبيوتر. في تسع من أصل عشر مرات، لا يحدث شيء. لكن في المرة العاشرة، يتلف النظام.

الاستخدام الصحيح لـ 'uncaughtException' هو إجراء تنظيف متزامن للموارد المخصصة (مثل مُوصِفات الملفات، والمقابض، إلخ) قبل إيقاف تشغيل العملية. ليس من الآمن استئناف التشغيل العادي بعد 'uncaughtException'.

لإعادة تشغيل تطبيق تحطم بطريقة أكثر موثوقية، سواء تم إصدار 'uncaughtException' أم لا، يجب استخدام مُراقِب خارجي في عملية منفصلة لاكتشاف أخطاء التطبيق والتعافي أو إعادة التشغيل حسب الحاجة.

حدث: 'uncaughtExceptionMonitor'

مضاف في: v13.7.0، v12.17.0

• err <Error> الاستثناء غير المعالج.
• origin <string> يُشير إلى ما إذا كان الاستثناء ينشأ من رفض غير معالج أو من أخطاء متزامنة. يمكن أن يكون إما 'uncaughtException' أو 'unhandledRejection'. يُستخدم الأخير عندما يحدث استثناء في سياق غير متزامن قائم على Promise (أو إذا تم رفض Promise) وعلم --unhandled-rejections مُعيّن إلى strict أو throw (وهو الإعداد الافتراضي) ولم يتم التعامل مع الرفض، أو عندما يحدث رفض أثناء مرحلة التحميل الثابت لوحدة ES للنقطة الإدخالية لسطر الأوامر.

يتم إصدار حدث 'uncaughtExceptionMonitor' قبل إصدار حدث 'uncaughtException' أو استدعاء خطاف مُثبت عبر process.setUncaughtExceptionCaptureCallback().

إن تثبيت مُستمع 'uncaughtExceptionMonitor' لا يُغيّر السلوك بمجرد إصدار حدث 'uncaughtException'. ستظل العملية تتعطل إذا لم يتم تثبيت مُستمع 'uncaughtException'.

ESM

import process from 'node:process'

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

// التسبب عمداً في استثناء، لكن لا يتم التقاطه.
nonexistentFunc()
// لا يزال يُنهي Node.js

CJS

const process = require('node:process')

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

// التسبب عمداً في استثناء، لكن لا يتم التقاطه.
nonexistentFunc()
// لا يزال يُنهي Node.js

الحدث: 'unhandledRejection'

[السجل]

الإصدار	التغييرات
v7.0.0	أصبح عدم التعامل مع رفض وعود Promise قديمًا.
v6.6.0	ستصدر الآن تحذيرات عملية عند رفض وعود Promise غير المعالجة.
v1.4.1	تمت الإضافة في: v1.4.1

• reason <Error> | <أي> الكائن الذي تم رفض الوعد به (عادةً كائن Error).
• promise <Promise> الوعد المرفوض.

يتم إصدار حدث 'unhandledRejection' كلما تم رفض Promise ولم يتم إرفاق مُعالِج أخطاء بالوعد خلال دورة حلقة الأحداث. عند البرمجة باستخدام الوعود، يتم تغليف الاستثناءات كـ "وعود مرفوضة". يمكن التقاط الرفض ومعالجته باستخدام promise.catch() ويتم نشره عبر سلسلة Promise. يُعد حدث 'unhandledRejection' مفيدًا لاكتشاف وتتبع الوعود التي تم رفضها والتي لم يتم التعامل مع رفضها بعد.

ESM

import process from 'node:process'

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason)
  // تسجيل محدد بالتطبيق، أو إخراج خطأ، أو منطق آخر هنا
})

somePromise.then(res => {
  return reportToUser(JSON.pasre(res)) // لاحظ الخطأ المطبعي (`pasre`)
}) // لا يوجد `.catch()` أو `.then()`

CJS

const process = require('node:process')

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason)
  // تسجيل محدد بالتطبيق، أو إخراج خطأ، أو منطق آخر هنا
})

somePromise.then(res => {
  return reportToUser(JSON.pasre(res)) // لاحظ الخطأ المطبعي (`pasre`)
}) // لا يوجد `.catch()` أو `.then()`

سوف يؤدي ما يلي أيضًا إلى إصدار حدث 'unhandledRejection':

ESM

import process from 'node:process'

function SomeResource() {
  // تعيين حالة التحميل مبدئيًا إلى وعد مرفوض
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'))
}

const resource = new SomeResource()
// لا يوجد .catch أو .then على resource.loaded لمدة دورة واحدة على الأقل

CJS

const process = require('node:process')

function SomeResource() {
  // تعيين حالة التحميل مبدئيًا إلى وعد مرفوض
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'))
}

const resource = new SomeResource()
// لا يوجد .catch أو .then على resource.loaded لمدة دورة واحدة على الأقل

في هذا المثال، من الممكن تتبع الرفض كخطأ مطور كما هو الحال عادةً مع أحداث 'unhandledRejection' الأخرى. لمعالجة مثل هذه الأخطاء، يمكن إرفاق مُعالِج .catch(() =\> { }) غير عامل بـ resource.loaded، مما سيمنع إصدار حدث 'unhandledRejection'.

الحدث: 'warning'

مضاف في: v6.0.0

• warning <Error> الخصائص الرئيسية للتحذير هي:
  • name <string> اسم التحذير. الافتراضي: 'Warning'.
  • message <string> وصف مُقدم من النظام للتحذير.
  • stack <string> تتبع مُكدس للموقع في الكود حيث تم إصدار التحذير.

يُصدر حدث 'warning' كلما أصدرت Node.js تحذيرًا لعملية.

يشبه تحذير العملية خطأً في أنه يصف ظروفًا استثنائية تُلفت انتباه المستخدم إليها. ومع ذلك، فإن التحذيرات ليست جزءًا من تدفق معالجة الأخطاء العادي في Node.js و JavaScript. يمكن أن تُصدر Node.js تحذيرات كلما اكتشفت ممارسات ترميز سيئة قد تؤدي إلى أداء تطبيق دون المستوى الأمثل، أو أخطاء، أو ثغرات أمنية.

ESM

import process from 'node:process'

process.on('warning', warning => {
  console.warn(warning.name) // طباعة اسم التحذير
  console.warn(warning.message) // طباعة رسالة التحذير
  console.warn(warning.stack) // طباعة تتبع المكدس
})

CJS

const process = require('node:process')

process.on('warning', warning => {
  console.warn(warning.name) // طباعة اسم التحذير
  console.warn(warning.message) // طباعة رسالة التحذير
  console.warn(warning.stack) // طباعة تتبع المكدس
})

بشكل افتراضي، ستطبع Node.js تحذيرات العملية على stderr. يمكن استخدام خيار سطر الأوامر --no-warnings لقمع إخراج وحدة التحكم الافتراضي، لكن حدث 'warning' سيظل يُصدره كائن process. حاليًا، لا يمكن قمع أنواع تحذير محددة بخلاف تحذيرات الإهمال. لقمع تحذيرات الإهمال، تحقق من علم --no-deprecation.

يوضح المثال التالي التحذير الذي يتم طباعته على stderr عند إضافة الكثير من المستمعين إلى حدث:

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: تم الكشف عن تسرب محتمل لذاكرة EventEmitter. تمت إضافة 2 مستمع foo. استخدم emitter.setMaxListeners() لزيادة الحد.

على النقيض من ذلك، فإن المثال التالي يُلغي إخراج التحذير الافتراضي ويضيف مُعامل مخصص لحدث 'warning' :

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('لا تفعل ذلك!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> لا تفعل ذلك!

يمكن استخدام خيار سطر الأوامر --trace-warnings لجعل إخراج وحدة التحكم الافتراضي للتحذيرات يتضمن تتبع المكدس الكامل للتحذير.

سيؤدي تشغيل Node.js باستخدام علم سطر الأوامر --throw-deprecation إلى رمي تحذيرات الإهمال المخصصة كاستثناءات.

سيؤدي استخدام علم سطر الأوامر --trace-deprecation إلى طباعة الإهمال المخصص على stderr بالإضافة إلى تتبع المكدس.

سيؤدي استخدام علم سطر الأوامر --no-deprecation إلى قمع جميع تقارير الإهمال المخصص.

لا تؤثر أعلام سطر الأوامر *-deprecation إلا على التحذيرات التي تستخدم اسم 'DeprecationWarning'.

إصدار تحذيرات مخصصة

راجع طريقة process.emitWarning() لإصدار تحذيرات مخصصة أو خاصة بالتطبيق.

أسماء تحذيرات Node.js

لا توجد إرشادات صارمة لأنواع التحذيرات (كما هو محدد بواسطة خاصية name) التي يصدرها Node.js. يمكن إضافة أنواع جديدة من التحذيرات في أي وقت. بعض أنواع التحذيرات الأكثر شيوعًا تتضمن:

• 'DeprecationWarning' - يشير إلى استخدام واجهة برمجة تطبيقات أو ميزة Node.js مُهملة. يجب أن تتضمن هذه التحذيرات خاصية 'code' تحدد رمز الإهمال.
• 'ExperimentalWarning' - يشير إلى استخدام واجهة برمجة تطبيقات أو ميزة Node.js تجريبية. يجب استخدام هذه الميزات بحذر لأنها قد تتغير في أي وقت وليست خاضعة لنفس سياسات الإصدار الدلالي الصارمة وسياسات الدعم طويلة الأمد مثل الميزات المدعومة.
• 'MaxListenersExceededWarning' - يشير إلى تسجيل عدد كبير جدًا من المستمعين لحدث معين إما على EventEmitter أو EventTarget. غالبًا ما يكون هذا مؤشرًا على تسرب الذاكرة.
• 'TimeoutOverflowWarning' - يشير إلى توفير قيمة رقمية لا يمكنها التناسب ضمن عدد صحيح ذي 32 بت موقّعًا إلى وظائف setTimeout() أو setInterval().
• 'TimeoutNegativeWarning' - يشير إلى توفير رقم سالب لوظائف setTimeout() أو setInterval().
• 'TimeoutNaNWarning' - يشير إلى توفير قيمة ليست رقمًا لوظائف setTimeout() أو setInterval().
• 'UnsupportedWarning' - يشير إلى استخدام خيار أو ميزة غير مدعوم سيتم تجاهله بدلاً من معاملته كخطأ. أحد الأمثلة هو استخدام رسالة حالة استجابة HTTP عند استخدام واجهة برمجة تطبيقات توافق HTTP/2.

الحدث: 'worker'

مضاف في: v16.2.0، v14.18.0

• worker <Worker> <Worker> التي تم إنشاؤها.

يتم إصدار حدث 'worker' بعد إنشاء مؤشر ترابط <Worker> جديد.

أحداث الإشارات

يتم إصدار أحداث الإشارات عندما تتلقى عملية Node.js إشارة. يرجى الرجوع إلى signal(7) للحصول على قائمة بأسماء إشارات POSIX القياسية مثل 'SIGINT', 'SIGHUP', إلخ.

لا تتوفر الإشارات في مؤشرات الترابط Worker.

سيستقبل مُعالِج الإشارات اسم الإشارة ('SIGINT', 'SIGTERM', إلخ) كحجة أولى.

سيكون اسم كل حدث هو الاسم الشائع بالحروف الكبيرة للإشارة (مثل 'SIGINT' لإشارات SIGINT).

ESM

import process from 'node:process'

// البدء في القراءة من stdin حتى لا تغلق العملية.
process.stdin.resume()

process.on('SIGINT', () => {
  console.log('تم استلام SIGINT. اضغط Control-D للخروج.')
})

// استخدام دالة واحدة للتعامل مع إشارات متعددة
function handle(signal) {
  console.log(`تم استلام ${signal}`)
}

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

CJS

const process = require('node:process')

// البدء في القراءة من stdin حتى لا تغلق العملية.
process.stdin.resume()

process.on('SIGINT', () => {
  console.log('تم استلام SIGINT. اضغط Control-D للخروج.')
})

// استخدام دالة واحدة للتعامل مع إشارات متعددة
function handle(signal) {
  console.log(`تم استلام ${signal}`)
}

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

• 'SIGUSR1' محجوز بواسطة Node.js لبدء مُحسّن الأخطاء. من الممكن تثبيت مستمع، لكن القيام بذلك قد يتداخل مع مُحسّن الأخطاء.
• لدى 'SIGTERM' و'SIGINT' مُعالِجات افتراضية على أنظمة غير Windows تقوم بإعادة تعيين وضع المحطة الطرفية قبل الخروج برمز 128 + رقم الإشارة. إذا تم تثبيت مستمع لإحدى هاتين الإشارتين، فسيتم إزالة سلوكه الافتراضي (لن تغلق Node.js بعد الآن).
• يتم تجاهل 'SIGPIPE' افتراضيًا. يمكن تثبيت مستمع له.
• يتم إنشاء 'SIGHUP' في Windows عند إغلاق نافذة وحدة التحكم، وعلى منصات أخرى في ظل ظروف مماثلة مختلفة. انظر signal(7). يمكن تثبيت مستمع له، ومع ذلك، ستُنهى Node.js بدون شروط بواسطة Windows بعد حوالي 10 ثوانٍ. على الأنظمة غير Windows، يكون السلوك الافتراضي لـ SIGHUP هو إنهاء Node.js، ولكن بمجرد تثبيت مستمع، سيتم إزالة سلوكه الافتراضي.
• 'SIGTERM' غير مدعوم في Windows، يمكن الاستماع إليه.
• 'SIGINT' من المحطة الطرفية مدعوم على جميع المنصات، ويمكن عادةً إنشاؤه باستخدام Ctrl+C (على الرغم من أن هذا قد يكون قابلاً للتكوين). لا يتم إنشاؤه عندما يكون وضع المحطة الطرفية الخام مُفعّلاً ويتم استخدام Ctrl+C.
• يتم تسليم 'SIGBREAK' على Windows عند الضغط على Ctrl+Break. على الأنظمة غير Windows، يمكن الاستماع إليه، ولكن لا توجد طريقة لإرساله أو إنشائه.
• يتم تسليم 'SIGWINCH' عندما يتم تغيير حجم وحدة التحكم. في Windows، سيحدث هذا فقط عند الكتابة على وحدة التحكم عندما يتم تحريك المؤشر، أو عندما يتم استخدام tty قابل للقراءة في الوضع الخام.
• لا يمكن تثبيت مستمع لـ 'SIGKILL'، فإنه سينهي Node.js بدون شروط على جميع المنصات.
• لا يمكن تثبيت مستمع لـ 'SIGSTOP'.
• 'SIGBUS', 'SIGFPE', 'SIGSEGV', و'SIGILL', عندما لا يتم رفعها بشكل مصطنع باستخدام kill(2)، تترك العملية بشكل جوهري في حالة لا يكون من الآمن فيها استدعاء مستمعي JS. قد يتسبب القيام بذلك في توقف العملية عن الاستجابة.
• يمكن إرسال 0 لاختبار وجود عملية، ليس له أي تأثير إذا كانت العملية موجودة، ولكنه سيُطرح خطأ إذا لم تكن العملية موجودة.

لا يدعم Windows الإشارات، لذلك لا يوجد ما يعادل الإنهاء بالإشارة، ولكن Node.js يقدم بعض المحاكاة باستخدام process.kill()، وsubprocess.kill():

• سيؤدي إرسال SIGINT, SIGTERM, وSIGKILL إلى الإنهاء غير المشروط لعملية الهدف، وبعد ذلك، ستُبلغ العملية الفرعية بأن العملية قد تم إنهاؤها بواسطة إشارة.
• يمكن استخدام إرسال الإشارة 0 كطريقة مستقلة عن النظام الأساسي لاختبار وجود عملية.

process.abort()

مُضاف في: v0.7.0

تُسببُ طريقة process.abort() في إنهاء عملية Node.js على الفور، وتوليد ملف أساسي.

هذه الميزة غير متوفرة في مؤشرات الترابط Worker.

process.allowedNodeEnvironmentFlags

مُضاف في: v10.10.0

• <Set>

خاصية process.allowedNodeEnvironmentFlags هي مجموعة خاصة للقراءة فقط من الأعلام المسموح بها داخل متغير البيئة NODE_OPTIONS.

يمتدّ process.allowedNodeEnvironmentFlags إلى Set، ولكنه يُعيد كتابة Set.prototype.has للتعرف على العديد من التمثيلات المحتملة للأعلام. ستُعيد process.allowedNodeEnvironmentFlags.has() القيمة true في الحالات التالية:

• قد يُغفل الأعلام شرطة واحدة (-) أو شرطتين مزدوجتين (--) في البداية؛ على سبيل المثال، inspect-brk لـ --inspect-brk، أو r لـ -r.
• قد تُستبدل الأعلام المُمرّرة إلى V8 (كما هو مُدرج في --v8-options) شرطة واحدة أو أكثر غير رائدة بعلامة تحت، أو العكس؛ على سبيل المثال، --perf_basic_prof, --perf-basic-prof, --perf_basic-prof, إلخ.
• قد تحتوي الأعلام على حرف أو أكثر من علامات المساواة (=)؛ سيتم تجاهل جميع الأحرف بعد أول علامة مساواة بما في ذلك هذه العلامة؛ على سبيل المثال، --stack-trace-limit=100.
• يجب أن تكون الأعلام مسموح بها داخل NODE_OPTIONS.

عند التكرار فوق process.allowedNodeEnvironmentFlags، ستظهر الأعلام مرة واحدة فقط؛ سيبدأ كل منها بشرطة واحدة أو أكثر. ستحتوي الأعلام المُمرّرة إلى V8 على علامات تحت بدلاً من الشرطة غير الرائدة:

ESM

import { allowedNodeEnvironmentFlags } from 'node:process'

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

CJS

const { allowedNodeEnvironmentFlags } = require('node:process')

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

لا تفعل طرق add() و clear() و delete() الخاصة بـ process.allowedNodeEnvironmentFlags شيئًا، وستفشل بصمت.

إذا تم تجميع Node.js بدون دعم NODE_OPTIONS (كما هو موضح في process.config)، فسيتضمن process.allowedNodeEnvironmentFlags ما كان سيكون مسموحًا به.

process.arch

أضيف في: v0.5.0

• <string>

هندسة معالج نظام التشغيل التي تم تجميع ثنائي Node.js من أجلها. القيم الممكنة هي: 'arm'، 'arm64'، 'ia32'، 'loong64'، 'mips'، 'mipsel'، 'ppc'، 'ppc64'، 'riscv64'، 's390'، 's390x'، و 'x64'.

ESM

import { arch } from 'node:process'

console.log(`هندسة المعالج هذه هي ${arch}`)

CJS

const { arch } = require('node:process')

console.log(`هندسة المعالج هذه هي ${arch}`)

process.argv

أضيف في: v0.1.27

• <string[]>

تعيد خاصية process.argv مصفوفة تحتوي على وسيطات سطر الأوامر التي تم تمريرها عند بدء تشغيل عملية Node.js. سيكون العنصر الأول هو process.execPath. راجع process.argv0 إذا كانت هناك حاجة للوصول إلى القيمة الأصلية لـ argv[0]. سيكون العنصر الثاني هو المسار إلى ملف JavaScript الذي يتم تنفيذه. ستكون العناصر المتبقية أي وسيطات إضافية لسطر الأوامر.

على سبيل المثال، بافتراض البرنامج النصي التالي لـ process-args.js:

ESM

import { argv } from 'node:process'

// طباعة process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`)
})

CJS

const { argv } = require('node:process')

// طباعة process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`)
})

بدء عملية Node.js كالتالي:

node process-args.js one two=three four

سيؤدي ذلك إلى إنشاء الإخراج التالي:

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

process.argv0

أضيف في: v6.4.0

• <string>

تقوم خاصية process.argv0 بتخزين نسخة للقراءة فقط من القيمة الأصلية لـ argv[0] التي تم تمريرها عند بدء تشغيل Node.js.

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

process.channel

[السجل]

الإصدار	التغييرات
v14.0.0	لم يعد الكائن يعرض ربطات C++ الأصلية عن طريق الخطأ.
v7.1.0	تمت الإضافة في: v7.1.0

• <Object>

إذا تم إنشاء عملية Node.js باستخدام قناة IPC (راجع وثائق Child Process)، فإن الخاصية process.channel هي مرجع لقناة IPC. إذا لم تكن هناك قناة IPC، فإن هذه الخاصية تكون undefined.

process.channel.ref()

تمت الإضافة في: v7.1.0

تجعل هذه الطريقة قناة IPC تحافظ على حلقة الأحداث لعملية التشغيل إذا تم استدعاء .unref() من قبل.

عادةً، يتم إدارة هذا من خلال عدد المستمعين 'disconnect' و 'message' على كائن process. ومع ذلك، يمكن استخدام هذه الطريقة لطلب سلوك محدد صراحةً.

process.channel.unref()

تمت الإضافة في: v7.1.0

تجعل هذه الطريقة قناة IPC لا تحافظ على حلقة الأحداث لعملية التشغيل، وتسمح لها بالانتهاء حتى أثناء فتح القناة.

عادةً، يتم إدارة هذا من خلال عدد المستمعين 'disconnect' و 'message' على كائن process. ومع ذلك، يمكن استخدام هذه الطريقة لطلب سلوك محدد صراحةً.

process.chdir(directory)

تمت الإضافة في: v0.1.17

• directory <string>

تغير طريقة process.chdir() دليل العمل الحالي لعملية Node.js أو تطرح استثناءً إذا فشلت في القيام بذلك (على سبيل المثال، إذا لم يكن directory المحدد موجودًا).

ESM

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

console.log(`دليل البدء: ${cwd()}`)
try {
  chdir('/tmp')
  console.log(`الدليل الجديد: ${cwd()}`)
} catch (err) {
  console.error(`chdir: ${err}`)
}

CJS

const { chdir, cwd } = require('node:process')

console.log(`دليل البدء: ${cwd()}`)
try {
  chdir('/tmp')
  console.log(`الدليل الجديد: ${cwd()}`)
} catch (err) {
  console.error(`chdir: ${err}`)
}

هذه الميزة غير متوفرة في خيوط Worker.

process.config

[History]

الإصدار	التغييرات
v19.0.0	أصبح كائن process.config مجمدًا.
v16.0.0	تم إهمال تعديل process.config.
v0.7.7	تمت الإضافة في: v0.7.7

• <Object>

تعيد خاصية process.config كائنًا مجمدًا يحتوي على التمثيل البرمجي لخيارات التكوين المستخدمة لترجمة الملف التنفيذي الحالي لـ Node.js. هذا هو نفسه ملف config.gypi الذي تم إنتاجه عند تشغيل البرنامج النصي ./configure.

مثال على الإخراج المحتمل يبدو كالتالي:

{
  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
   }
}

process.connected

تمت الإضافة في: v0.7.2

• <boolean>

إذا تم إنشاء عملية Node.js باستخدام قناة IPC (انظر وثائق Child Process و Cluster)، فستعيد خاصية process.connected قيمة true طالما كانت قناة IPC متصلة، وستعيد false بعد استدعاء process.disconnect().

بمجرد أن تصبح process.connected تساوي false، لم يعد من الممكن إرسال الرسائل عبر قناة IPC باستخدام process.send().

process.constrainedMemory()

[History]

الإصدار	التغييرات
v22.0.0, v20.13.0	تم محاذاة قيمة الإرجاع مع uv_get_constrained_memory.
v19.6.0, v18.15.0	تمت الإضافة في: v19.6.0, v18.15.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - تجريبي

• <number>

يحصل على مقدار الذاكرة المتاحة للعملية (بالبايت) بناءً على حدود تفرضها نظام التشغيل. إذا لم يكن هناك مثل هذا القيد، أو كان القيد غير معروف، يتم إرجاع 0.

انظر uv_get_constrained_memory لمزيد من المعلومات.

process.availableMemory()

أضيف في: v22.0.0، v20.13.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

• <number>

يحصل على مقدار الذاكرة الحرة المتوفرة لا تزال للعملية (بالبايت).

انظر إلى uv_get_available_memory لمزيد من المعلومات.

process.cpuUsage([previousValue])

أضيف في: v6.1.0

• previousValue <Object> قيمة إرجاع سابقة من استدعاء process.cpuUsage()
• القيمة المُرجعة: <Object>
  • user <integer>
  • system <integer>

ترجع طريقة process.cpuUsage() استخدام وقت وحدة المعالجة المركزية للمستخدم والنظام للعملية الحالية، في كائن بخصائص user و system، وقيمها هي قيم دقيقة (مليون من الثانية). تقيس هذه القيم الوقت الذي يقضيه في رمز المستخدم والنظام على التوالي، وقد ينتهي الأمر بأن تكون أكبر من الوقت المنقضي الفعلي إذا كانت نوى وحدة المعالجة المركزية المتعددة تؤدي عملًا لهذه العملية.

يمكن تمرير نتيجة مكالمة سابقة إلى process.cpuUsage() كوسيطة للوظيفة، للحصول على قراءة فرق.

ESM

import { cpuUsage } from 'node:process'

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

// تدوير وحدة المعالجة المركزية لمدة 500 مللي ثانية
const now = Date.now()
while (Date.now() - now < 500);

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

CJS

const { cpuUsage } = require('node:process')

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

// تدوير وحدة المعالجة المركزية لمدة 500 مللي ثانية
const now = Date.now()
while (Date.now() - now < 500);

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

process.cwd()

مضاف في: v0.1.8

• مُخرجات: <string>

طريقة process.cwd() تُرجع الدليل العامل الحالي لعملية Node.js.

ESM

import { cwd } from 'node:process'

console.log(`الدليل الحالي: ${cwd()}`)

CJS

const { cwd } = require('node:process')

console.log(`الدليل الحالي: ${cwd()}`)

process.debugPort

مضاف في: v0.7.2

• <number>

المنفذ المُستخدم بواسطة مُصحح أخطاء Node.js عند تمكينه.

ESM

import process from 'node:process'

process.debugPort = 5858

CJS

const process = require('node:process')

process.debugPort = 5858

process.disconnect()

إذا تم إنشاء عملية Node.js بقناة IPC (انظر وثائق Child Process و Cluster)، فإن طريقة process.disconnect() ستغلق قناة IPC إلى العملية الأم، مما يسمح لعملية الطفل بالخروج بشكل سلس بمجرد عدم وجود اتصالات أخرى تُبقيها حية.

تأثير استدعاء process.disconnect() هو نفسه استدعاء ChildProcess.disconnect() من العملية الأم.

إذا لم يتم إنشاء عملية Node.js بقناة IPC، فسيكون process.disconnect() غير مُعرّف.

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

[History]

الإصدار	التغييرات
v9.0.0	تمت إضافة دعم وسيطة flags.
v0.1.16	مضاف في: v0.1.16

• module <Object>
• filename <string>
• flags <os.constants.dlopen> الافتراضي: os.constants.dlopen.RTLD_LAZY

تسمح طريقة process.dlopen() بتحميل الكائنات المشتركة ديناميكيًا. يتم استخدامها بشكل أساسي بواسطة require() لتحميل إضافات C++، ويجب عدم استخدامها مباشرة، إلا في حالات خاصة. بمعنى آخر، يجب تفضيل require() على process.dlopen() ما لم تكن هناك أسباب محددة مثل أعلام dlopen مخصصة أو التحميل من وحدات ES.

وسيطه flags هي عدد صحيح يسمح بتحديد سلوك dlopen. راجع وثائق os.constants.dlopen للحصول على التفاصيل.

شرط مهم عند استدعاء process.dlopen() هو أنه يجب تمرير مثيل module. تصبح الدوال التي تم تصديرها بواسطة إضافة C++ قابلة للوصول من خلال module.exports.

يُظهر المثال أدناه كيفية تحميل إضافة C++، اسمها local.node، والتي تُصدر دالة foo. يتم تحميل جميع الرموز قبل عودة الاستدعاء، عن طريق تمرير ثابت RTLD_NOW. في هذا المثال، يُفترض أن الثابت متوفر.

ESM

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()

CJS

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()

process.emitWarning(warning[, options])

مضاف في: v8.0.0

• warning <string> | <Error> التحذير الذي سيتم إصداره.
• options <Object>
  • type <string> عندما يكون warning عبارة عن String، يكون type هو الاسم الذي سيتم استخدامه لنوع التحذير الذي يتم إصداره. افتراضي: 'Warning'.
  • code <string> معرف فريد لحدث التحذير الذي يتم إصداره.
  • ctor <Function> عندما يكون warning عبارة عن String، يكون ctor دالة اختيارية تُستخدم للحد من تتبع المكدس المُولّد. افتراضي: process.emitWarning.
  • detail <string> نص إضافي لإدراجه مع الخطأ.

يمكن استخدام طريقة process.emitWarning() لإصدار تحذيرات عمليات مخصصة أو خاصة بالتطبيق. ويمكن الاستماع إليها عن طريق إضافة مُعامل إلى حدث 'warning'.

ESM

import { emitWarning } from 'node:process'

// إصدار تحذير برمز وتفاصيل إضافية.
emitWarning('حدث شيء ما!', {
  code: 'MY_WARNING',
  detail: 'هذه بعض المعلومات الإضافية',
})
// يُصدر:
// (node:56338) [MY_WARNING] Warning: حدث شيء ما!
// هذه بعض المعلومات الإضافية

CJS

const { emitWarning } = require('node:process')

// إصدار تحذير برمز وتفاصيل إضافية.
emitWarning('حدث شيء ما!', {
  code: 'MY_WARNING',
  detail: 'هذه بعض المعلومات الإضافية',
})
// يُصدر:
// (node:56338) [MY_WARNING] Warning: حدث شيء ما!
// هذه بعض المعلومات الإضافية

في هذا المثال، يتم إنشاء كائن Error داخليًا بواسطة process.emitWarning() ويتم تمريره إلى مُعامل الحدث 'warning'.

ESM

import process from 'node:process'

process.on('warning', warning => {
  console.warn(warning.name) // 'Warning'
  console.warn(warning.message) // 'حدث شيء ما!'
  console.warn(warning.code) // 'MY_WARNING'
  console.warn(warning.stack) // تتبع المكدس
  console.warn(warning.detail) // 'هذه بعض المعلومات الإضافية'
})

CJS

const process = require('node:process')

process.on('warning', warning => {
  console.warn(warning.name) // 'Warning'
  console.warn(warning.message) // 'حدث شيء ما!'
  console.warn(warning.code) // 'MY_WARNING'
  console.warn(warning.stack) // تتبع المكدس
  console.warn(warning.detail) // 'هذه بعض المعلومات الإضافية'
})

إذا تم تمرير warning ككائن Error، فسيتم تجاهل وسيطة options.

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

مضاف في: v6.0.0

• warning <string> | <Error> التحذير الذي سيتم إصداره.
• type <string> عندما يكون warning عبارة عن String، فإن type هو الاسم الذي سيتم استخدامه لنوع التحذير الذي يتم إصداره. افتراضي: 'Warning'.
• code <string> معرف فريد لحدث التحذير الذي يتم إصداره.
• ctor <Function> عندما يكون warning عبارة عن String، فإن ctor هي دالة اختيارية تُستخدم للحد من تتبع المكدس المُولّد. افتراضي: process.emitWarning.

يمكن استخدام طريقة process.emitWarning() لإصدار تحذيرات عمليات مخصصة أو خاصة بالتطبيق. ويمكن الاستماع إليها عن طريق إضافة مُعالِج لحدث 'warning'.

ESM

import { emitWarning } from 'node:process'

// إصدار تحذير باستخدام سلسلة نصية.
emitWarning('حدث شيء ما!')
// يُصدر: (node: 56338) Warning: حدث شيء ما!

CJS

const { emitWarning } = require('node:process')

// إصدار تحذير باستخدام سلسلة نصية.
emitWarning('حدث شيء ما!')
// يُصدر: (node: 56338) Warning: حدث شيء ما!

ESM

import { emitWarning } from 'node:process'

// إصدار تحذير باستخدام سلسلة نصية ونوع.
emitWarning('حدث شيء ما!', 'CustomWarning')
// يُصدر: (node:56338) CustomWarning: حدث شيء ما!

CJS

const { emitWarning } = require('node:process')

// إصدار تحذير باستخدام سلسلة نصية ونوع.
emitWarning('حدث شيء ما!', 'CustomWarning')
// يُصدر: (node:56338) CustomWarning: حدث شيء ما!

ESM

import { emitWarning } from 'node:process'

emitWarning('حدث شيء ما!', 'CustomWarning', 'WARN001')
// يُصدر: (node:56338) [WARN001] CustomWarning: حدث شيء ما!

CJS

const { emitWarning } = require('node:process')

process.emitWarning('حدث شيء ما!', 'CustomWarning', 'WARN001')
// يُصدر: (node:56338) [WARN001] CustomWarning: حدث شيء ما!

في كل مثال من الأمثلة السابقة، يتم إنشاء كائن Error داخليًا بواسطة process.emitWarning() ويتم تمريره إلى مُعالِج حدث 'warning'.

ESM

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)
})

CJS

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)
})

إذا تم تمرير warning ككائن Error، فسيتم تمريره إلى مُعالِج حدث 'warning' دون تعديل (وسيتم تجاهل الوسائط الاختيارية type و code و ctor).

ESM

import { emitWarning } from 'node:process'

// إصدار تحذير باستخدام كائن Error.
const myWarning = new Error('حدث شيء ما!')
// استخدام خاصية اسم Error لتحديد اسم النوع
myWarning.name = 'CustomWarning'
myWarning.code = 'WARN001'

emitWarning(myWarning)
// يُصدر: (node:56338) [WARN001] CustomWarning: حدث شيء ما!

CJS

const { emitWarning } = require('node:process')

// إصدار تحذير باستخدام كائن Error.
const myWarning = new Error('حدث شيء ما!')
// استخدام خاصية اسم Error لتحديد اسم النوع
myWarning.name = 'CustomWarning'
myWarning.code = 'WARN001'

emitWarning(myWarning)
// يُصدر: (node:56338) [WARN001] CustomWarning: حدث شيء ما!

يتم طرح TypeError إذا كان warning أي شيء آخر غير سلسلة نصية أو كائن Error.

في حين أن تحذيرات العملية تستخدم كائنات Error، فإن آلية تحذير العملية ليست بديلاً لآليات معالجة الأخطاء العادية.

يتم تنفيذ المعالجة الإضافية التالية إذا كان نوع التحذير هو 'DeprecationWarning':

• إذا تم استخدام علم سطر الأوامر --throw-deprecation، فسيتم طرح تحذير الإهمال كاستثناء بدلاً من إصداره كحدث.
• إذا تم استخدام علم سطر الأوامر --no-deprecation، فسيتم قمع تحذير الإهمال.
• إذا تم استخدام علم سطر الأوامر --trace-deprecation، فسيتم طباعة تحذير الإهمال إلى stderr مع تتبع المكدس الكامل.

تجنب تحذيرات الازدواج

كممارسة مثلى، يجب إصدار التحذيرات مرة واحدة فقط لكل عملية. للقيام بذلك، ضع emitWarning() خلف قيمة منطقية.

ESM

import { emitWarning } from 'node:process'

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true
    emitWarning('Only warn once!')
  }
}
emitMyWarning()
// يصدر: (node: 56339) Warning: Only warn once!
emitMyWarning()
// لا يصدر أي شيء

CJS

const { emitWarning } = require('node:process')

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true
    emitWarning('Only warn once!')
  }
}
emitMyWarning()
// يصدر: (node: 56339) Warning: Only warn once!
emitMyWarning()
// لا يصدر أي شيء

process.env

[History]

الإصدار	التغييرات
v11.14.0	ستستخدم خيوط العامل الآن نسخة من process.env لخيط الأصل بشكل افتراضي، ويمكن تكوينه من خلال خيار env في مُنشئ Worker.
v10.0.0	تحويل قيمة المتغير الضمني إلى سلسلة نصية قديم.
v0.1.27	تمت الإضافة في: v0.1.27

• <Object>

تعيد خاصية process.env كائنًا يحتوي على بيئة المستخدم. انظر environ(7).

مثال على هذا الكائن يبدو كالتالي:

{
  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'
}

من الممكن تعديل هذا الكائن، لكن هذه التعديلات لن تُعكس خارج عملية Node.js، أو (ما لم يُطلب صراحةً) إلى خيوط Worker الأخرى. بعبارة أخرى، لن يعمل المثال التالي:

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

بينما سيُعمل التالي:

ESM

import { env } from 'node:process'

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

CJS

const { env } = require('node:process')

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

سيؤدي تعيين خاصية على process.env إلى تحويل القيمة ضمنيًا إلى سلسلة نصية. هذا السلوك قديم. قد تُلقي إصدارات Node.js المستقبلية خطأً عندما لا تكون القيمة سلسلة نصية أو رقمًا أو قيمة منطقية.

ESM

import { env } from 'node:process'

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

CJS

const { env } = require('node:process')

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

استخدم delete لحذف خاصية من process.env.

ESM

import { env } from 'node:process'

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

CJS

const { env } = require('node:process')

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

في أنظمة تشغيل Windows، تكون متغيرات البيئة غير حساسة لحالة الأحرف.

ESM

import { env } from 'node:process'

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

CJS

const { env } = require('node:process')

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

ما لم يتم تحديده صراحةً عند إنشاء مثيل Worker، فإن كل خيط Worker لديه نسخته الخاصة من process.env، بناءً على process.env لخيط الأصل، أو أي شيء تم تحديده كخيار env لـ مُنشئ Worker. لن تكون التغييرات التي تطرأ على process.env مرئية عبر خيوط Worker، وفقط الخيط الرئيسي يمكنه إجراء تغييرات مرئية لنظام التشغيل أو الوظائف الإضافية الأصلية. في Windows، تعمل نسخة من process.env على مثيل Worker بطريقة حساسة لحالة الأحرف على عكس الخيط الرئيسي.

process.execArgv

مضاف في: v0.7.7

• <string[]>

تعيد الخاصية process.execArgv مجموعة خيارات سطر الأوامر الخاصة بـ Node.js التي تم تمريرها عند تشغيل عملية Node.js. لا تظهر هذه الخيارات في المصفوفة التي تُرجعها الخاصية process.argv، ولا تتضمن ملف Node.js التنفيذي، أو اسم البرنامج النصي، أو أي خيارات تلي اسم البرنامج النصي. هذه الخيارات مفيدة من أجل إنشاء عمليات فرعية بنفس بيئة التنفيذ مثل العملية الأصلية.

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

النتيجة في process.execArgv:

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

و process.argv:

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

يرجى الرجوع إلى مُنشئ Worker للحصول على السلوك التفصيلي لخيوط عامل مع هذه الخاصية.

process.execPath

مضاف في: v0.1.100

• <string>

تعيد الخاصية process.execPath المسار المطلق للبرنامج التنفيذي الذي بدأ عملية Node.js. روابط رمزية، إن وجدت، يتم حلها.

'/usr/local/bin/node'

process.exit([code])

[History]

الإصدار	التغييرات
v20.0.0	يقبل فقط رمزًا من نوع رقم، أو من نوع سلسلة إذا كان يمثل عددًا صحيحًا.
v0.1.13	مضاف في: v0.1.13

• code <integer> | <string> | <null> | <undefined> رمز الخروج. بالنسبة لنوع السلسلة، يُسمح فقط بسلاسل الأعداد الصحيحة (مثل، '1'). الافتراضي: 0.

تُرشد طريقة process.exit() Node.js إلى إنهاء العملية بشكل متزامن برمز خروج code. إذا تم حذف code، فإن الخروج يستخدم إما رمز "النجاح" 0 أو قيمة process.exitCode إذا تم تعيينها. لن ينتهي Node.js حتى يتم استدعاء جميع مستمعي أحداث 'exit'.

لإنهاء برمز "فشل":

ESM

import { exit } from 'node:process'

exit(1)

CJS

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

exit(1)

يجب أن يرى shell الذي قام بتشغيل Node.js رمز الخروج كـ 1.

سيؤدي استدعاء process.exit() إلى إجبار العملية على الخروج بأسرع ما يمكن حتى لو كانت هناك عمليات غير متزامنة معلقة لم تكتمل بعد بالكامل، بما في ذلك عمليات الإدخال/الإخراج إلى process.stdout و process.stderr.

في معظم الحالات، ليس من الضروري في الواقع استدعاء process.exit() صراحةً. ستخرج عملية Node.js بنفسها إذا لم يكن هناك عمل إضافي معلق في حلقة الحدث. يمكن تعيين الخاصية process.exitCode لإخبار العملية برمز الخروج الذي يجب استخدامه عندما تخرج العملية بسلاسة.

على سبيل المثال، يوضح المثال التالي سوء استخدام لطريقة process.exit() التي قد تؤدي إلى اقتطاع البيانات المطبوعة على stdout وفقدانها:

ESM

import { exit } from 'node:process'

// هذا مثال على ما *لا يجب* فعله:
if (someConditionNotMet()) {
  printUsageToStdout()
  exit(1)
}

CJS

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

// هذا مثال على ما *لا يجب* فعله:
if (someConditionNotMet()) {
  printUsageToStdout()
  exit(1)
}

السبب في أن هذا أمرٌ مُشكِل هو أن الكتابة إلى process.stdout في Node.js تكون أحيانًا غير متزامنة وقد تحدث عبر عدة دقات من حلقة حدث Node.js. ومع ذلك، فإن استدعاء process.exit() يُجبر العملية على الخروج قبل إجراء عمليات الكتابة الإضافية إلى stdout.

بدلاً من استدعاء process.exit() مباشرةً، يجب أن يُعيّن الكود process.exitCode وأن يسمح للعملية بالخروج بشكل طبيعي عن طريق تجنب جدولة أي عمل إضافي لحلقة الحدث:

ESM

import process from 'node:process'

// كيفية تعيين رمز الخروج بشكل صحيح مع السماح
// للعملية بالخروج بسلاسة.
if (someConditionNotMet()) {
  printUsageToStdout()
  process.exitCode = 1
}

CJS

const process = require('node:process')

// كيفية تعيين رمز الخروج بشكل صحيح مع السماح
// للعملية بالخروج بسلاسة.
if (someConditionNotMet()) {
  printUsageToStdout()
  process.exitCode = 1
}

إذا كان من الضروري إنهاء عملية Node.js بسبب حالة خطأ، فإن طرح خطأ غير معالج والسماح للعملية بالإنهاء وفقًا لذلك يكون أكثر أمانًا من استدعاء process.exit().

في خيوط Worker، تقوم هذه الوظيفة بإيقاف الخيط الحالي بدلاً من العملية الحالية.

process.exitCode

[السجل]

الإصدار	التغييرات
v20.0.0	يقبل فقط رمزًا من نوع رقم، أو من نوع سلسلة إذا كان يمثل عددًا صحيحًا.
v0.11.8	تمت الإضافة في: v0.11.8

• <عدد صحيح> | <سلسلة> | <لا شيء> | <غير معرف> رمز الخروج. بالنسبة لنوع السلسلة، يُسمح فقط بسلاسل الأعداد الصحيحة (مثل، '1'). الافتراضي: غير معرف.

رقم سيكون رمز خروج العملية، عندما تخرج العملية إما بشكل سلس، أو يتم إخراجها عبر process.exit() بدون تحديد رمز.

سيؤدي تحديد رمز إلى process.exit(code) إلى تجاوز أي إعداد سابق لـ process.exitCode.

process.features.cached_builtins

تمت الإضافة في: v12.0.0

• <قيمة منطقية>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يقوم بتخزين وحدات مُدمجة مؤقتًا.

process.features.debug

تمت الإضافة في: v0.5.5

• <قيمة منطقية>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي إصدارًا تصحيحًا.

process.features.inspector

تمت الإضافة في: v11.10.0

• <قيمة منطقية>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن مُفتشًا.

process.features.ipv6

تمت الإضافة في: v0.5.3

تم إهماله منذ: v23.4.0

[مستقر: 0 - مهمل]

مستقر: 0 الثبات: 0 - مهمل. هذه الخاصية دائمًا ما تكون صحيحة، وأي اختبارات تعتمد عليها زائدة عن الحاجة.

• <قيمة منطقية>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن دعمًا لـ IPv6.

بما أن جميع إصدارات Node.js لديها دعم IPv6، فإن هذه القيمة دائمًا ما تكون true.

process.features.require_module

أضيف في: v23.0.0

• <boolean>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يدعم تحميل وحدات ECMAScript باستخدام require().

process.features.tls

أضيف في: v0.5.3

• <boolean>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن دعمًا لـ TLS.

process.features.tls_alpn

أضيف في: v4.8.0

تم إهماله منذ: v23.4.0

[مستقر: 0 - تم إهماله]

مستقر: 0 الثبات: 0 - تم إهماله. استخدم process.features.tls بدلاً من ذلك.

• <boolean>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن دعمًا لـ ALPN في TLS.

في إصدارات Node.js 11.0.0 والإصدارات الأحدث، تتميز مكتبات OpenSSL التابعة بدعم غير مشروط لـ ALPN. لذلك، تكون هذه القيمة مطابقة لقيمة process.features.tls.

process.features.tls_ocsp

أضيف في: v0.11.13

تم إهماله منذ: v23.4.0

[مستقر: 0 - تم إهماله]

مستقر: 0 الثبات: 0 - تم إهماله. استخدم process.features.tls بدلاً من ذلك.

• <boolean>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن دعمًا لـ OCSP في TLS.

في إصدارات Node.js 11.0.0 والإصدارات الأحدث، تتميز مكتبات OpenSSL التابعة بدعم غير مشروط لـ OCSP. لذلك، تكون هذه القيمة مطابقة لقيمة process.features.tls.

process.features.tls_sni

أضيف في: v0.5.3

تم إهماله منذ: v23.4.0

[مستقر: 0 - تم إهماله]

مستقر: 0 الثبات: 0 - تم إهماله. استخدم process.features.tls بدلاً من ذلك.

• <boolean>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن دعمًا لـ SNI في TLS.

في إصدارات Node.js 11.0.0 والإصدارات الأحدث، تتميز مكتبات OpenSSL التابعة بدعم غير مشروط لـ SNI. لذلك، تكون هذه القيمة مطابقة لقيمة process.features.tls.

process.features.typescript

تم الإضافة في: v23.0.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.1 - تطوير نشط

• <boolean> | <string>

قيمة تساوي "strip" إذا تم تشغيل Node.js باستخدام --experimental-strip-types، أو "transform" إذا تم تشغيل Node.js باستخدام --experimental-transform-types، و false بخلاف ذلك.

process.features.uv

تم الإضافة في: v0.5.3

تم إهماله منذ: v23.4.0

[مستقر: 0 - مهمل]

مستقر: 0 استقرار: 0 - مهمل. هذه الخاصية صحيحة دائمًا، وأي عمليات فحص تستند إليها زائدة عن الحاجة.

• <boolean>

قيمة منطقية تساوي true إذا كان إصدار Node.js الحالي يتضمن دعمًا لـ libuv.

بما أنه ليس من الممكن إنشاء Node.js بدون libuv، فإن هذه القيمة دائمًا ما تكون true.

process.finalization.register(ref, callback)

تم الإضافة في: v22.5.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.1 - تطوير نشط

• ref <Object> | <Function> المرجع إلى المورد الذي يتم تعقبه.
• callback <Function> دالة الارتجاع التي سيتم استدعاؤها عند الانتهاء من المورد.
  • ref <Object> | <Function> المرجع إلى المورد الذي يتم تعقبه.
  • event <string> الحدث الذي أثار عملية الانتهاء. الافتراضي هو 'exit'.

هذه الدالة تسجل دالة ارتجاع ليتم استدعاؤها عندما يصدر الحدث exit إذا لم يتم جمع كائن ref بواسطة عملية جمع القمامة. إذا تم جمع كائن ref بواسطة عملية جمع القمامة قبل إصدار حدث exit، فسيتم إزالة دالة الارتجاع من سجل الانتهاء، ولن يتم استدعاؤها عند خروج العملية.

داخل دالة الارتجاع، يمكنك إطلاق الموارد التي تم تخصيصها بواسطة كائن ref. كن على دراية بأن جميع القيود المطبقة على حدث beforeExit تُطبق أيضًا على دالة callback، وهذا يعني أن هناك احتمالًا ألا يتم استدعاء دالة الارتجاع في ظروف خاصة.

فكرة هذه الدالة هي مساعدتك في تحرير الموارد عند بدء عملية الخروج، ولكن أيضًا السماح بجمع كائن القمامة إذا لم يعد قيد الاستخدام.

مثال: يمكنك تسجيل كائن يحتوي على مخزن مؤقت، فأنت تريد التأكد من إطلاق المخزن المؤقت عند خروج العملية، ولكن إذا تم جمع الكائن بواسطة عملية جمع القمامة قبل خروج العملية، فلن نحتاج بعد الآن إلى إطلاق المخزن المؤقت، لذلك في هذه الحالة نقوم فقط بإزالة دالة الارتجاع من سجل الانتهاء.

CJS

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

// يرجى التأكد من أن الدالة الممررة إلى finalization.register()
// لا تُنشئ إغلاقًا حول كائنات غير ضرورية.
function onFinalize(obj, event) {
  // يمكنك القيام بأي شيء تريده مع الكائن
  obj.dispose()
}

function setup() {
  // يمكن جمع هذا الكائن بأمان بواسطة عملية جمع القمامة،
  // ولن يتم استدعاء دالة الإغلاق الناتجة.
  // لا توجد تسربات.
  const myDisposableObject = {
    dispose() {
      // حرر مواردك بشكل متزامن
    },
  }

  finalization.register(myDisposableObject, onFinalize)
}

setup()

ESM

import { finalization } from 'node:process'

// يرجى التأكد من أن الدالة الممررة إلى finalization.register()
// لا تُنشئ إغلاقًا حول كائنات غير ضرورية.
function onFinalize(obj, event) {
  // يمكنك القيام بأي شيء تريده مع الكائن
  obj.dispose()
}

function setup() {
  // يمكن جمع هذا الكائن بأمان بواسطة عملية جمع القمامة،
  // ولن يتم استدعاء دالة الإغلاق الناتجة.
  // لا توجد تسربات.
  const myDisposableObject = {
    dispose() {
      // حرر مواردك بشكل متزامن
    },
  }

  finalization.register(myDisposableObject, onFinalize)
}

setup()

يعتمد الكود أعلاه على الافتراضات التالية:

• تجنب دوال الأسهم
• يوصى باستخدام الدوال العادية في السياق العام (الجذر)

يمكن أن تشير الدوال العادية إلى السياق الذي يعيش فيه obj، مما يجعل obj غير قابل لجمع القمامة.

ستحتفظ دوال الأسهم بالسياق السابق. ضع في اعتبارك، على سبيل المثال:

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

    // حتى شيء مثل هذا يُنصح بشدة بتجنبه
    // finalization.register(this, () => this.dispose());
  }
  dispose() {}
}

من غير المحتمل جدًا (وليس مستحيلًا) أن يتم جمع هذا الكائن بواسطة عملية جمع القمامة، ولكن إذا لم يكن كذلك، فسيتم استدعاء dispose عند استدعاء process.exit.

كن حذرًا وتجنب الاعتماد على هذه الميزة للتخلص من الموارد الحرجة، لأنه ليس مضمونًا أن يتم استدعاء دالة الارتجاع في جميع الظروف.

process.finalization.registerBeforeExit(ref, callback)

تم الإضافة في: v22.5.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1.1 - تطوير نشط

• ref <Object> | <Function> مرجع المورد الذي يتم تعقبه.
• callback <Function> دالة الاستدعاء التي سيتم استدعاؤها عند الانتهاء من المورد.
  • ref <Object> | <Function> مرجع المورد الذي يتم تعقبه.
  • event <string> الحدث الذي أثار عملية الانتهاء. القيمة الافتراضية هي 'beforeExit'.

هذه الدالة تتصرف تمامًا مثل register، إلا أن دالة الاستدعاء سيتم استدعاؤها عندما يصدر المُعالِج حدث beforeExit إذا لم يتم جمع كائن ref بواسطة Garbage Collector.

انتبه إلى أن جميع القيود المطبقة على حدث beforeExit تُطبق أيضًا على دالة callback، وهذا يعني أن هناك احتمال ألا يتم استدعاء دالة الاستدعاء في ظروف خاصة.

process.finalization.unregister(ref)

تم الإضافة في: v22.5.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1.1 - تطوير نشط

• ref <Object> | <Function> مرجع المورد الذي تم تسجيله مسبقًا.

تقوم هذه الدالة بإزالة تسجيل الكائن من سجل الانتهاء، وبالتالي لن يتم استدعاء دالة الاستدعاء بعد الآن.

CJS

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

// يرجى التأكد من أن الدالة التي تم تمريرها إلى finalization.register()
// لا تُنشئ إغلاقًا حول كائنات غير ضرورية.
function onFinalize(obj, event) {
  // يمكنك فعل ما تريد مع الكائن
  obj.dispose()
}

function setup() {
  // يمكن جمع هذا الكائن بأمان بواسطة  Garbage Collector،
  // ولن يتم استدعاء دالة الإغلاق الناتجة.
  // لا توجد تسريبات.
  const myDisposableObject = {
    dispose() {
      // قم بتحرير مواردك بشكل متزامن
    },
  }

  finalization.register(myDisposableObject, onFinalize)

  // افعل شيئًا ما

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

setup()

ESM

import { finalization } from 'node:process'

// يرجى التأكد من أن الدالة التي تم تمريرها إلى finalization.register()
// لا تُنشئ إغلاقًا حول كائنات غير ضرورية.
function onFinalize(obj, event) {
  // يمكنك فعل ما تريد مع الكائن
  obj.dispose()
}

function setup() {
  // يمكن جمع هذا الكائن بأمان بواسطة  Garbage Collector،
  // ولن يتم استدعاء دالة الإغلاق الناتجة.
  // لا توجد تسريبات.
  const myDisposableObject = {
    dispose() {
      // قم بتحرير مواردك بشكل متزامن
    },
  }

  // يرجى التأكد من أن الدالة التي تم تمريرها إلى finalization.register()
  // لا تُنشئ إغلاقًا حول كائنات غير ضرورية.
  function onFinalize(obj, event) {
    // يمكنك فعل ما تريد مع الكائن
    obj.dispose()
  }

  finalization.register(myDisposableObject, onFinalize)

  // افعل شيئًا ما

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

setup()

process.getActiveResourcesInfo()

مضاف في: v17.3.0، v16.14.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• مُخرجات: <string[]>

تعيد طريقة process.getActiveResourcesInfo() مصفوفة من السلاسل التي تحتوي على أنواع الموارد النشطة التي تحافظ حاليًا على حلقة الأحداث قيد التشغيل.

ESM

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

console.log('Before:', getActiveResourcesInfo())
setTimeout(() => {}, 1000)
console.log('After:', getActiveResourcesInfo())
// يطبع:
//   Before: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

CJS

const { getActiveResourcesInfo } = require('node:process')
const { setTimeout } = require('node:timers')

console.log('Before:', getActiveResourcesInfo())
setTimeout(() => {}, 1000)
console.log('After:', getActiveResourcesInfo())
// يطبع:
//   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

process.getBuiltinModule(id)

مضاف في: v22.3.0، v20.16.0

• id <string> معرف الوحدة النمطية المدمجة المطلوبة.
• مُخرجات: <Object> | <undefined>

يوفر process.getBuiltinModule(id) طريقة لتحميل الوحدات النمطية المدمجة في دالة متاحة عالميًا. يمكن لوحدات ES التي تحتاج إلى دعم بيئات أخرى استخدامها لتحميل وحدة مدمجة في Node.js بشكل مشروط عند تشغيلها في Node.js، دون الحاجة إلى التعامل مع خطأ الحل الذي يمكن أن يطرحه import في بيئة غير Node.js أو استخدام import() الديناميكي الذي يحول الوحدة النمطية إما إلى وحدة غير متزامنة، أو يحول واجهة برمجة التطبيقات المتزامنة إلى واجهة برمجة تطبيقات غير متزامنة.

if (globalThis.process?.getBuiltinModule) {
  // يتم التشغيل في Node.js، استخدم وحدة fs في Node.js.
  const fs = globalThis.process.getBuiltinModule('fs')
  // إذا كانت هناك حاجة إلى `require()` لتحميل وحدات المستخدم، استخدم createRequire()
  const module = globalThis.process.getBuiltinModule('module')
  const require = module.createRequire(import.meta.url)
  const foo = require('foo')
}

إذا حدد id وحدة نمطية مدمجة متاحة في عملية Node.js الحالية، فإن طريقة process.getBuiltinModule(id) تُعيد الوحدة النمطية المدمجة المقابلة. إذا لم يتوافق id مع أي وحدة نمطية مدمجة، يتم إرجاع undefined.

يقبل process.getBuiltinModule(id) معرفات الوحدات النمطية المدمجة التي يتم التعرف عليها بواسطة module.isBuiltin(id). يجب تحميل بعض الوحدات النمطية المدمجة مع بادئة node:، راجع الوحدات النمطية المدمجة مع بادئة node: الإلزامية. تشير المراجع التي تُرجعها process.getBuiltinModule(id) دائمًا إلى الوحدة النمطية المدمجة التي تتوافق مع id حتى إذا قام المستخدمون بتعديل require.cache بحيث يُعيد require(id) شيئًا آخر.

process.getegid()

مضاف في: v2.0.0

ترجع طريقة process.getegid() هوية المجموعة الفعالة العددية لعملية Node.js. (انظر getegid(2).)

ESM

import process from 'node:process'

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

CJS

const process = require('node:process')

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

لا تتوفر هذه الدالة إلا على أنظمة POSIX (أي ليس Windows أو Android).

process.geteuid()

مضاف في: v2.0.0

• ترجع: <Object>

ترجع طريقة process.geteuid() هوية المستخدم الفعالة العددية للعملية. (انظر geteuid(2).)

ESM

import process from 'node:process'

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

CJS

const process = require('node:process')

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

لا تتوفر هذه الدالة إلا على أنظمة POSIX (أي ليس Windows أو Android).

process.getgid()

مضاف في: v0.1.31

• ترجع: <Object>

ترجع طريقة process.getgid() هوية المجموعة العددية للعملية. (انظر getgid(2).)

ESM

import process from 'node:process'

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

CJS

const process = require('node:process')

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

لا تتوفر هذه الدالة إلا على أنظمة POSIX (أي ليس Windows أو Android).

process.getgroups()

مضاف في: v0.9.4

• ترجع: <integer[]>

ترجع طريقة process.getgroups() مصفوفة تحتوي على معرفات المجموعات الإضافية. تترك POSIX الأمر غير محدد فيما إذا كانت هوية المجموعة الفعالة مضمنة، لكن Node.js تضمن أنها موجودة دائمًا.

ESM

import process from 'node:process'

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

CJS

const process = require('node:process')

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

لا تتوفر هذه الدالة إلا على أنظمة POSIX (أي ليس Windows أو Android).

process.getuid()

أضيف في: v0.1.28

• المُخرجات: <integer>

ترجع طريقة process.getuid() هوية المستخدم العددية للعملية. (انظر getuid(2).)

ESM

import process from 'node:process'

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

CJS

const process = require('node:process')

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

هذه الدالة متوفرة فقط على أنظمة POSIX (أي ليست Windows أو Android).

process.hasUncaughtExceptionCaptureCallback()

أضيف في: v9.3.0

• المُخرجات: <boolean>

يشير إلى ما إذا تم تعيين مُدعمة باستخدام process.setUncaughtExceptionCaptureCallback().

process.hrtime([time])

أضيف في: v0.7.6

[مستقر: 3 - تراثي]

مستقر: 3 استقرار: 3 - تراثي. استخدم process.hrtime.bigint() بدلاً من ذلك.

• time <integer[]> نتيجة دعوة سابقة إلى process.hrtime()
• المُخرجات: <integer[]>

هذه هي النسخة القديمة من process.hrtime.bigint() قبل إدخال bigint في JavaScript.

ترجع طريقة process.hrtime() وقت التشغيل عالي الدقة الحالي في مجموعة [seconds, nanoseconds] Array، حيث nanoseconds هو الجزء المتبقي من وقت التشغيل الذي لا يمكن تمثيله بدقة الثانية.

time هي معلمة اختيارية يجب أن تكون نتيجة دعوة سابقة لـ process.hrtime() للاختلاف مع الوقت الحالي. إذا لم تكن المعلمة المُمرّرة مجموعة Array، فسيتم طرح TypeError. سيؤدي تمرير مصفوفة مُعرّفة من قِبل المستخدم بدلاً من نتيجة دعوة سابقة إلى process.hrtime() إلى سلوك غير مُعرّف.

هذه الأوقات نسبية لوقت عشوائي في الماضي، وليست مرتبطة بوقت اليوم وبالتالي ليست خاضعة لانحراف الساعة. الاستخدام الأساسي هو قياس الأداء بين الفترات:

ESM

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)

CJS

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)

process.hrtime.bigint()

مضاف في: v10.7.0

• قيمة الإرجاع: <bigint>

طريقة bigint الخاصة بطريقة process.hrtime() تُرجع الوقت الحقيقي عالي الدقة بالنانوثانية كـ bigint.

على عكس process.hrtime()، لا تدعم وسيطة time إضافية لأن الفرق يمكن حسابه مباشرةً بطرح قيمتي bigint.

ESM

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)

CJS

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)

process.initgroups(user, extraGroup)

مضاف في: v0.9.4

• user <string> | <number> اسم المستخدم أو معرفه العددي.
• extraGroup <string> | <number> اسم المجموعة أو معرفها العددي.

تقوم طريقة process.initgroups() بقراءة ملف /etc/group وتهيئة قائمة الوصول للمجموعة، باستخدام جميع المجموعات التي ينتمي إليها المستخدم. هذه عملية مُميزة تتطلب أن يكون لعملية Node.js إما حق الوصول إلى root أو إمكانية CAP_SETGID.

توخ الحذر عند إسقاط الامتيازات:

ESM

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

console.log(getgroups()) // [ 0 ]
initgroups('nodeuser', 1000) // تبديل المستخدم
console.log(getgroups()) // [ 27, 30, 46, 1000, 0 ]
setgid(1000) // إسقاط معرف المجموعة الجذرية
console.log(getgroups()) // [ 27, 30, 46, 1000 ]

CJS

const { getgroups, initgroups, setgid } = require('node:process')

console.log(getgroups()) // [ 0 ]
initgroups('nodeuser', 1000) // تبديل المستخدم
console.log(getgroups()) // [ 27, 30, 46, 1000, 0 ]
setgid(1000) // إسقاط معرف المجموعة الجذرية
console.log(getgroups()) // [ 27, 30, 46, 1000 ]

هذه الوظيفة متاحة فقط على أنظمة POSIX (أي ليست Windows أو Android). هذه الميزة غير متاحة في مؤشرات الترابط Worker.

process.kill(pid[, signal])

مضاف في: v0.0.6

• pid <number> معرف عملية
• signal <string> | <number> الإشارة المراد إرسالها، إما كسلسلة نصية أو رقم. الافتراضي: 'SIGTERM'.

ترسل طريقة process.kill() الإشارة signal إلى العملية التي تم تحديدها بواسطة pid.

أسماء الإشارات هي سلاسل نصية مثل 'SIGINT' أو 'SIGHUP'. راجع أحداث الإشارة و kill(2) لمزيد من المعلومات.

ستطرح هذه الطريقة خطأ إذا لم تكن العملية المستهدفة pid موجودة. كحالة خاصة، يمكن استخدام إشارة 0 للتحقق من وجود عملية. ستطرح أنظمة التشغيل Windows خطأ إذا تم استخدام pid لقتل مجموعة عمليات.

على الرغم من أن اسم هذه الوظيفة هو process.kill()، إلا أنها في الواقع مجرد مرسل إشارة، مثل دعوة النظام kill. قد تقوم الإشارة المرسلة بعمل شيء آخر غير قتل عملية الهدف.

ESM

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')

CJS

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')

عندما تتلقى عملية Node.js إشارة SIGUSR1، ستبدأ Node.js مصحح الأخطاء. راجع أحداث الإشارة.

process.loadEnvFile(path)

مضاف في: v21.7.0, v20.12.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1.1 - تطوير نشط

• path <string> | <URL> | <Buffer> | <undefined>. الافتراضي: './.env'

يقوم بتحميل ملف .env إلى process.env. لن يكون لاستخدام NODE_OPTIONS في ملف .env أي تأثير على Node.js.

CJS

const { loadEnvFile } = require('node:process')
loadEnvFile()

ESM

import { loadEnvFile } from 'node:process'
loadEnvFile()

process.mainModule

مُضافة في: v0.1.17

مُحذّرة منذ: v14.0.0

[مستقر: 0 - مُحذّر]

مستقر: 0 استقرار: 0 - مُحذّر: استخدم require.main بدلاً من ذلك.

• <Object>

تُوفّر خاصية process.mainModule طريقة بديلة لاسترجاع require.main. يكمن الاختلاف في أنه إذا تغير المُعامل الرئيسي أثناء وقت التشغيل، فقد لا يزال require.main يشير إلى المُعامل الرئيسي الأصلي في المُعاملات التي تم طلبها قبل حدوث التغيير. بشكل عام، من الآمن افتراض أن كليهما يشيران إلى نفس المُعامل.

كما هو الحال مع require.main، ستكون قيمة process.mainModule هي undefined إذا لم يكن هناك برنامج نصي إدخال.

process.memoryUsage()

[السجل]

الإصدار	التغييرات
v13.9.0, v12.17.0	تمت إضافة arrayBuffers إلى الكائن المُرجع.
v7.2.0	تمت إضافة external إلى الكائن المُرجع.
v0.1.16	مُضافة في: v0.1.16

• المُرجع: <Object>
  • rss <integer>
  • heapTotal <integer>
  • heapUsed <integer>
  • external <integer>
  • arrayBuffers <integer>

يُرجع كائنًا يصف استخدام الذاكرة لعملية Node.js المقاسة بالبايت.

ESM

import { memoryUsage } from 'node:process'

console.log(memoryUsage())
// يُطبع:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }

CJS

const { memoryUsage } = require('node:process')

console.log(memoryUsage())
// يُطبع:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }

• تشير heapTotal و heapUsed إلى استخدام ذاكرة V8.
• تشير external إلى استخدام ذاكرة كائنات C++ المرتبطة بكائنات JavaScript التي يديرها V8.
• rss، حجم المجموعة المُقيمة، هو مقدار المساحة المُحتلة في جهاز الذاكرة الرئيسي (وهو جزء من الذاكرة المُخصصة الإجمالية) للعملية، بما في ذلك جميع كائنات ورموز C++ و JavaScript.
• تشير arrayBuffers إلى الذاكرة المُخصصة لـ ArrayBuffer و SharedArrayBuffer، بما في ذلك جميع مصفوفات Node.js Buffer. وهذا مُضمن أيضًا في قيمة external. عند استخدام Node.js كـمكتبة مُضمنة، قد تكون هذه القيمة 0 نظرًا لأن تخصيصات ArrayBuffer قد لا يتم تعقّبها في تلك الحالة.

عند استخدام مؤشرات الترابط Worker، ستكون rss قيمة صالحة للعملية بأكملها، بينما ستشير الحقول الأخرى فقط إلى المُؤشر الحالي.

تكرر طريقة process.memoryUsage() كل صفحة لجمع المعلومات حول استخدام الذاكرة، والتي قد تكون بطيئة اعتمادًا على تخصيصات ذاكرة البرنامج.

process.memoryUsage.rss()

مضاف في: v15.6.0، v14.18.0

• مُخرجات: <integer>

تعيدُ طريقة process.memoryUsage.rss() قيمة صحيحة تمثل حجم المجموعة المُقيمة (RSS) بالبايت.

حجم المجموعة المُقيمة هو مقدار المساحة المُحتلة في جهاز الذاكرة الرئيسي (وهو جزء من الذاكرة المُخصصة الكُلية) للعملية، بما في ذلك جميع كائنات ورموز C++ و JavaScript.

هذه هي نفس القيمة التي توفرها خاصية rss بواسطة process.memoryUsage() ولكن process.memoryUsage.rss() أسرع.

ESM

import { memoryUsage } from 'node:process'

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

CJS

const { memoryUsage } = require('node:process')

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

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

[History]

الإصدار	التغييرات
v22.7.0، v20.18.0	تم تغيير الاستقرار إلى تراثي.
v18.0.0	يؤدي تمرير مُستدعى غير صالح إلى وسيطة callback الآن إلى إخراج ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v1.8.1	يتم الآن دعم الوسائط الإضافية بعد callback.
v0.1.26	مُضاف في: v0.1.26

[Stable: 3 - Legacy]

Stable: 3 Stability: 3 - تراثي: استخدم queueMicrotask() بدلاً من ذلك.

• callback <Function>
• ...args <any> وسيطات إضافية لتمريرها عند استدعاء callback

يضيف process.nextTick() callback إلى "مكدس التنفيذ التالي". يتم إفراغ هذا المكدس بالكامل بعد اكتمال العملية الحالية على مكدس JavaScript وقبل السماح لحلقة الأحداث بالاستمرار. من الممكن إنشاء حلقة لا نهائية إذا تم استدعاء process.nextTick() بشكل متكرر. راجع دليل حلقة الأحداث لمزيد من المعلومات.

ESM

import { nextTick } from 'node:process'

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

CJS

const { nextTick } = require('node:process')

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

هذا أمر مهم عند تطوير واجهات برمجة التطبيقات من أجل منح المستخدمين فرصة لتعيين مُعالجات الأحداث بعد إنشاء الكائن ولكن قبل حدوث أي مدخل/مخرج:

ESM

import { nextTick } from 'node:process'

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

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

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

// يتم استدعاء thing.startDoingStuff() الآن، وليس قبل ذلك.

CJS

const { nextTick } = require('node:process')

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

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

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

// يتم استدعاء thing.startDoingStuff() الآن، وليس قبل ذلك.

من المهم جدًا أن تكون واجهات برمجة التطبيقات إما مُزامنة بنسبة 100٪ أو غير مُزامنة بنسبة 100٪. ضع في اعتبارك هذا المثال:

// تحذير! لا تستخدم! خطر غير آمن!
function maybeSync(arg, cb) {
  if (arg) {
    cb()
    return
  }

  fs.stat('file', cb)
}

هذه واجهة برمجة التطبيقات خطيرة لأنها في الحالة التالية:

const maybeTrue = Math.random() > 0.5

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

bar()

ليس من الواضح ما إذا كان سيتم استدعاء foo() أو bar() أولاً.

النهج التالي أفضل بكثير:

ESM

import { nextTick } from 'node:process'

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

  fs.stat('file', cb)
}

CJS

const { nextTick } = require('node:process')

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

  fs.stat('file', cb)
}

متى تستخدم queueMicrotask() مقابل process.nextTick()

واجهة برمجة التطبيقات queueMicrotask() هي بديل لـ process.nextTick() يؤجل أيضًا تنفيذ دالة باستخدام نفس قائمة المهام الدقيقة المستخدمة لتنفيذ مُعالجات then و catch و finally للوعد المُحل. داخل Node.js، في كل مرة يتم فيها إفراغ "قائمة التنفيذ التالي"، يتم إفراغ قائمة المهام الدقيقة مباشرة بعد ذلك.

ESM

import { nextTick } from 'node:process'

Promise.resolve().then(() => console.log(2))
queueMicrotask(() => console.log(3))
nextTick(() => console.log(1))
// الإخراج:
// 1
// 2
// 3

CJS

const { nextTick } = require('node:process')

Promise.resolve().then(() => console.log(2))
queueMicrotask(() => console.log(3))
nextTick(() => console.log(1))
// الإخراج:
// 1
// 2
// 3

بالنسبة لمعظم حالات استخدام المستخدم، توفر واجهة برمجة التطبيقات queueMicrotask() آلية محمولة وموثوقة لتأجيل التنفيذ تعمل عبر بيئات منصات JavaScript متعددة، ويجب تفضيلها على process.nextTick(). في السيناريوهات البسيطة، يمكن أن يكون queueMicrotask() بديلاً مباشراً لـ process.nextTick().

console.log('start')
queueMicrotask(() => {
  console.log('microtask callback')
})
console.log('scheduled')
// الإخراج:
// start
// scheduled
// microtask callback

هناك فرق جدير بالملاحظة بين واجهتي البرمجة هما أن process.nextTick() يسمح بتحديد قيم إضافية سيتم تمريرها كوسائط إلى الدالة المؤجلة عند استدعائها. يتطلب تحقيق نفس النتيجة باستخدام queueMicrotask() استخدام إغلاق أو دالة مرتبطة:

function deferred(a, b) {
  console.log('microtask', a + b)
}

console.log('start')
queueMicrotask(deferred.bind(undefined, 1, 2))
console.log('scheduled')
// الإخراج:
// start
// scheduled
// microtask 3

هناك اختلافات طفيفة في طريقة معالجة الأخطاء التي يتم إثارتها من داخل قائمة التنفيذ التالي وقائمة المهام الدقيقة. يجب معالجة الأخطاء التي يتم طرحها داخل مُعالِج مُهمة دقيقة مُضافة ضمن المُعالِج المُضاف عندما يكون ذلك ممكنًا. إذا لم تكن كذلك، فيمكن استخدام مُعالِج حدث process.on('uncaughtException') لالتقاط الأخطاء ومعالجتها.

عندما تكون في شك، ما لم تكن هناك حاجة إلى إمكانيات محددة لـ process.nextTick()، استخدم queueMicrotask().

process.noDeprecation

مضاف في: v0.8.0

• <boolean>

تُشير خاصية process.noDeprecation إلى ما إذا كانت علامة --no-deprecation مُعيّنة على عملية Node.js الحالية. اطلع على وثائق حدث 'warning' وطريقة emitWarning() لمزيد من المعلومات حول سلوك هذه العلامة.

process.permission

مضاف في: v20.0.0

• <Object>

هذا الـ API متاح من خلال علامة --permission.

process.permission هو كائن تُستخدم طرائقه لإدارة الأذونات لعملية التشغيل الحالية. تتوفر وثائق إضافية في نموذج الأذونات.

process.permission.has(scope[, reference])

مضاف في: v20.0.0

• scope <string>
• reference <string>
• القيمة المُرجعة: <boolean>

يُحقق ما إذا كانت العملية قادرة على الوصول إلى النطاق والمرجع المُعطى. إذا لم يتم توفير مرجع، يُفترض نطاق عام، على سبيل المثال، سيُحقق process.permission.has('fs.read') ما إذا كانت العملية تمتلك جميع أذونات قراءة نظام الملفات.

للمرجع معنى بناءً على النطاق المُقدّم. على سبيل المثال، يعني المرجع عندما يكون النطاق نظام الملفات الملفات والمجلدات.

النطاقات المتاحة هي:

• fs - جميع أنظمة الملفات
• fs.read - عمليات قراءة نظام الملفات
• fs.write - عمليات كتابة نظام الملفات
• child - عمليات إنشاء عمليات فرعية
• worker - عملية إنشاء مؤشر عمل

// التحقق مما إذا كانت العملية لديها إذن لقراءة ملف README
process.permission.has('fs.read', './README.md')
// التحقق مما إذا كانت العملية لديها عمليات إذن القراءة
process.permission.has('fs.read')

process.pid

أضيف في: v0.1.15

• <integer>

تعيد خاصية process.pid معرف الهوية (PID) للعملية.

ESM

import { pid } from 'node:process'

console.log(`معرف هوية هذه العملية هو ${pid}`)

CJS

const { pid } = require('node:process')

console.log(`معرف هوية هذه العملية هو ${pid}`)

process.platform

أضيف في: v0.1.16

• <string>

تعيد خاصية process.platform سلسلةً تُعرّف نظام التشغيل الذي تم تجميع ثنائي Node.js من أجله.

القيم الممكنة حاليًا هي:

• 'aix'
• 'darwin'
• 'freebsd'
• 'linux'
• 'openbsd'
• 'sunos'
• 'win32'

ESM

import { platform } from 'node:process'

console.log(`هذا النظام الأساسي هو ${platform}`)

CJS

const { platform } = require('node:process')

console.log(`هذا النظام الأساسي هو ${platform}`)

قد يتم أيضًا إرجاع القيمة 'android' إذا تم بناء Node.js على نظام تشغيل Android. ومع ذلك، فإن دعم Android في Node.js تجريبي.

process.ppid

أضيف في: v9.2.0، v8.10.0، v6.13.0

• <integer>

تعيد خاصية process.ppid معرف الهوية (PID) للوالد للعملية الحالية.

ESM

import { ppid } from 'node:process'

console.log(`معرف هوية عملية الوالد هو ${ppid}`)

CJS

const { ppid } = require('node:process')

console.log(`معرف هوية عملية الوالد هو ${ppid}`)

process.release

[السجل]

الإصدار	التغييرات
v4.2.0	خاصية lts مدعومة الآن.
v3.0.0	أضيف في: v3.0.0

• <Object>

تعيد خاصية process.release كائنًا يحتوي على بيانات وصفية تتعلق بالإصدار الحالي، بما في ذلك عناوين URL لكرة المصدر وكرة الملفات العلوية فقط.

يحتوي process.release على الخصائص التالية:

• name <string> قيمة ستكون دائمًا 'node'.
• sourceUrl <string> عنوان URL مطلق يشير إلى ملف .tar.gz يحتوي على شفرة المصدر للإصدار الحالي.
• headersUrl<string> عنوان URL مطلق يشير إلى ملف .tar.gz يحتوي فقط على ملفات رأس المصدر للإصدار الحالي. هذا الملف أصغر بكثير من ملف المصدر الكامل ويمكن استخدامه لتجميع إضافات Node.js الأصلية.
• libUrl <string> | <undefined> عنوان URL مطلق يشير إلى ملف node.lib مطابق لهندسة ونُسخة الإصدار الحالي. يستخدم هذا الملف لتجميع إضافات Node.js الأصلية. هذه الخاصية موجودة فقط في إصدارات Windows من Node.js وستكون مفقودة في جميع الأنظمة الأساسية الأخرى.
• lts <string> | <undefined> تسمية سلسلة تُعرّف تسمية LTS لهذا الإصدار. توجد هذه الخاصية فقط لإصدارات LTS وهي undefined لجميع أنواع الإصدارات الأخرى، بما في ذلك الإصدارات الحالية. تتضمن القيم الصالحة أسماء رموز إصدار LTS (بما في ذلك تلك التي لم تعد مدعومة).
  • 'Fermium' لسلسلة LTS 14.x بدءًا من 14.15.0.
  • 'Gallium' لسلسلة LTS 16.x بدءًا من 16.13.0.
  • 'Hydrogen' لسلسلة LTS 18.x بدءًا من 18.12.0. لأسماء رموز إصدار LTS الأخرى، انظر أرشيف سجل تغييرات Node.js

{
  name: 'node',
  lts: 'Hydrogen',
  sourceUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz',
  headersUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz',
  libUrl: 'https://nodejs.org/download/release/v18.12.0/win-x64/node.lib'
}

في الإصدارات المُخصصة من الإصدارات غير المُصدرة من شجرة المصدر، قد تكون خاصية name فقط موجودة. يجب عدم الاعتماد على الخصائص الإضافية على أنها موجودة.

process.report

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v11.8.0	تمت الإضافة في: v11.8.0

• <Object>

process.report هو كائن تستخدم طرقه لإنشاء تقارير تشخيصية للعملية الحالية. تتوفر وثائق إضافية في وثائق التقرير.

process.report.compact

تمت الإضافة في: v13.12.0، v12.17.0

• <boolean>

كتابة التقارير بتنسيق مضغوط، وهو JSON أحادي السطر، أسهل في الاستهلاك بواسطة أنظمة معالجة السجلات من التنسيق الافتراضي متعدد الأسطر المصمم للاستهلاك البشري.

ESM

import { report } from 'node:process'

console.log(`Reports are compact? ${report.compact}`)

CJS

const { report } = require('node:process')

console.log(`Reports are compact? ${report.compact}`)

process.report.directory

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v11.12.0	تمت الإضافة في: v11.12.0

• <string>

الدليل الذي يُكتب فيه التقرير. القيمة الافتراضية هي سلسلة فارغة، مما يشير إلى أن التقارير تُكتب في دليل العمل الحالي لعملية Node.js.

ESM

import { report } from 'node:process'

console.log(`Report directory is ${report.directory}`)

CJS

const { report } = require('node:process')

console.log(`Report directory is ${report.directory}`)

process.report.filename

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v11.12.0	تمت الإضافة في: v11.12.0

• <string>

اسم الملف الذي يُكتب فيه التقرير. إذا تم تعيينه إلى سلسلة فارغة، فسيتكون اسم ملف الإخراج من طابع زمني و PID ورقم تسلسل. القيمة الافتراضية هي سلسلة فارغة.

إذا تم تعيين قيمة process.report.filename إلى 'stdout' أو 'stderr'، فسيتم كتابة التقرير إلى stdout أو stderr للعملية على التوالي.

ESM

import { report } from 'node:process'

console.log(`Report filename is ${report.filename}`)

CJS

const { report } = require('node:process')

console.log(`Report filename is ${report.filename}`)

process.report.getReport([err])

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا API تجريبيًا.
v11.8.0	تمت الإضافة في: v11.8.0

• err <Error> خطأ مخصص يستخدم للإبلاغ عن مُكدس JavaScript.
• القيمة المُرجعة: <Object>

يُرجِع تمثيلًا لهدف JavaScript لتقرير تشخيصي لعملية قيد التشغيل. يتم أخذ مُكدس JavaScript الخاص بالتقرير من err، إذا وُجد.

ESM

import { report } from 'node:process'
import util from 'node:util'

const data = report.getReport()
console.log(data.header.nodejsVersion)

// مشابه لـ process.report.writeReport()
import fs from 'node:fs'
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8')

CJS

const { report } = require('node:process')
const util = require('node:util')

const data = report.getReport()
console.log(data.header.nodejsVersion)

// مشابه لـ process.report.writeReport()
const fs = require('node:fs')
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8')

تتوفر وثائق إضافية في وثائق التقرير.

process.report.reportOnFatalError

[History]

الإصدار	التغييرات
v15.0.0، v14.17.0	لم يعد هذا API تجريبيًا.
v11.12.0	تمت الإضافة في: v11.12.0

• <boolean>

إذا كانت true، فسيتم إنشاء تقرير تشخيصي عند حدوث أخطاء قاتلة، مثل أخطاء نفاد الذاكرة أو تأكيدات C++ الفاشلة.

ESM

import { report } from 'node:process'

console.log(`Report on fatal error: ${report.reportOnFatalError}`)

CJS

const { report } = require('node:process')

console.log(`Report on fatal error: ${report.reportOnFatalError}`)

process.report.reportOnSignal

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v11.12.0	تمت الإضافة في: v11.12.0

• <boolean>

إذا كانت true، فسيتم إنشاء تقرير تشخيصي عندما تتلقى العملية الإشارة المحددة بواسطة process.report.signal.

ESM

import { report } from 'node:process'

console.log(`Report on signal: ${report.reportOnSignal}`)

CJS

const { report } = require('node:process')

console.log(`Report on signal: ${report.reportOnSignal}`)

process.report.reportOnUncaughtException

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v11.12.0	تمت الإضافة في: v11.12.0

• <boolean>

إذا كانت true، فسيتم إنشاء تقرير تشخيصي عند حدوث استثناء غير معالج.

ESM

import { report } from 'node:process'

console.log(`Report on exception: ${report.reportOnUncaughtException}`)

CJS

const { report } = require('node:process')

console.log(`Report on exception: ${report.reportOnUncaughtException}`)

process.report.excludeEnv

تمت الإضافة في: v23.3.0

• <boolean>

إذا كانت true، فسيتم إنشاء تقرير تشخيصي بدون متغيرات البيئة.

process.report.signal

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v11.12.0	تمت الإضافة في: v11.12.0

• <string>

الإشارة المستخدمة لبدء إنشاء تقرير تشخيصي. القيمة الافتراضية هي 'SIGUSR2'.

ESM

import { report } from 'node:process'

console.log(`Report signal: ${report.signal}`)

CJS

const { report } = require('node:process')

console.log(`Report signal: ${report.signal}`)

process.report.writeReport([filename][, err])

[History]

الإصدار	التغييرات
v13.12.0، v12.17.0	لم يعد هذا API تجريبيًا.
v11.8.0	تمت الإضافة في: v11.8.0

• filename <string> اسم الملف الذي سيتم كتابة التقرير فيه. يجب أن يكون هذا مسارًا نسبيًا، سيتم إرفاقه بالدليل المحدد في process.report.directory، أو الدليل العامل الحالي لعملية Node.js، إذا لم يتم تحديده.
• err <Error> خطأ مخصص يستخدم للإبلاغ عن مُكدس JavaScript.
• المُرجَع: <string> يُرجع اسم الملف للتقرير المُولّد.

يكتب تقريرًا تشخيصيًا في ملف. إذا لم يتم توفير filename، فإن اسم الملف الافتراضي يتضمن التاريخ والوقت وPID ورقم تسلسل. يتم أخذ مُكدس JavaScript للتقرير من err، إذا وُجد.

إذا تم تعيين قيمة filename إلى 'stdout' أو 'stderr'، فسيتم كتابة التقرير إلى stdout أو stderr للعملية على التوالي.

ESM

import { report } from 'node:process'

report.writeReport()

CJS

const { report } = require('node:process')

report.writeReport()

تتوفر وثائق إضافية في وثائق التقرير.

process.resourceUsage()

تمت الإضافة في: v12.6.0

• المُرجَع: <Object> استخدام الموارد للعملية الحالية. تأتي جميع هذه القيم من مكالمة uv_getrusage التي تُرجع بنية uv_rusage_t.
  • userCPUTime <integer> يُطابق ru_utime المحسوبة بوحدات الميكروثانية. إنها نفس القيمة مثل process.cpuUsage().user.
  • systemCPUTime <integer> يُطابق ru_stime المحسوبة بوحدات الميكروثانية. إنها نفس القيمة مثل process.cpuUsage().system.
  • maxRSS <integer> يُطابق ru_maxrss وهو الحد الأقصى لحجم المجموعة المقيمة المستخدمة بالكيلوبايت.
  • sharedMemorySize <integer> يُطابق ru_ixrss لكن لا يدعمه أي نظام أساسي.
  • unsharedDataSize <integer> يُطابق ru_idrss لكن لا يدعمه أي نظام أساسي.
  • unsharedStackSize <integer> يُطابق ru_isrss لكن لا يدعمه أي نظام أساسي.
  • minorPageFault <integer> يُطابق ru_minflt وهو عدد أخطاء الصفحة الطفيفة للعملية، راجع هذه المقالة لمزيد من التفاصيل.
  • majorPageFault <integer> يُطابق ru_majflt وهو عدد أخطاء الصفحة الكبرى للعملية، راجع هذه المقالة لمزيد من التفاصيل. هذا الحقل غير مدعوم على Windows.
  • swappedOut <integer> يُطابق ru_nswap لكن لا يدعمه أي نظام أساسي.
  • fsRead <integer> يُطابق ru_inblock وهو عدد المرات التي اضطر فيها نظام الملفات إلى إجراء الإدخال.
  • fsWrite <integer> يُطابق ru_oublock وهو عدد المرات التي اضطر فيها نظام الملفات إلى إجراء الإخراج.
  • ipcSent <integer> يُطابق ru_msgsnd لكن لا يدعمه أي نظام أساسي.
  • ipcReceived <integer> يُطابق ru_msgrcv لكن لا يدعمه أي نظام أساسي.
  • signalsCount <integer> يُطابق ru_nsignals لكن لا يدعمه أي نظام أساسي.
  • voluntaryContextSwitches <integer> يُطابق ru_nvcsw وهو عدد المرات التي نتج عنها تبديل سياق وحدة المعالجة المركزية بسبب عملية تتخلى طواعية عن المعالج قبل اكتمال شريحة الوقت الخاصة بها (عادةً لانتظار توفر مورد). هذا الحقل غير مدعوم على Windows.
  • involuntaryContextSwitches <integer> يُطابق ru_nivcsw وهو عدد المرات التي نتج عنها تبديل سياق وحدة المعالجة المركزية بسبب عملية ذات أولوية أعلى أصبحت قابلة للتشغيل أو لأن العملية الحالية تجاوزت شريحة وقتها. هذا الحقل غير مدعوم على Windows.

ESM

import { resourceUsage } from 'node:process'

console.log(resourceUsage())
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/

CJS

const { resourceUsage } = require('node:process')

console.log(resourceUsage())
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/

process.send(message[, sendHandle[, options]][, callback])

مضاف في: v0.5.9

• message <Object>

• sendHandle <net.Server> | <net.Socket>

• options <Object> مستخدم لمعلمات إرسال أنواع معينة من المُعالِجات. يدعم options الخصائص التالية:

  • keepOpen <boolean> قيمة يمكن استخدامها عند تمرير مثيلات من net.Socket. عندما تكون true، يبقى المقبس مفتوحًا في عملية الإرسال. افتراضيًا: false.

• callback <Function>

• المُخرج: <boolean>

إذا تم إنشاء Node.js بقناة IPC، فيمكن استخدام طريقة process.send() لإرسال الرسائل إلى العملية الأصلية. سيتم استقبال الرسائل كحدث 'message' على كائن ChildProcess للوالد.

إذا لم يتم إنشاء Node.js بقناة IPC، فسيكون process.send undefined.

تمر الرسالة عبر عمليات التجميع والتحليل. قد لا تكون الرسالة الناتجة هي نفسها التي تم إرسالها في الأصل.

process.setegid(id)

مضاف في: v2.0.0

• id <string> | <number> اسم المجموعة أو معرفها

تعيّن طريقة process.setegid() هوية المجموعة الفعّالة للعملية. (انظر setegid(2).) يمكن تمرير id كمعرف رقمي أو كسلسلة اسم مجموعة. إذا تم تحديد اسم المجموعة، فإن هذه الطريقة تُحجِز أثناء حل معرفها الرقمي المُرتبط.

ESM

import process from 'node:process'

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`)
  try {
    process.setegid(501)
    console.log(`New gid: ${process.getegid()}`)
  } catch (err) {
    console.error(`Failed to set gid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`)
  try {
    process.setegid(501)
    console.log(`New gid: ${process.getegid()}`)
  } catch (err) {
    console.error(`Failed to set gid: ${err}`)
  }
}

هذه الوظيفة متوفرة فقط على أنظمة POSIX (أي ليست Windows أو Android). هذه الميزة غير متوفرة في خيوط Worker.

process.seteuid(id)

أضيف في: v2.0.0

• id <string> | <number> اسم مستخدم أو معرف

تعيّن طريقة process.seteuid() هوية المستخدم الفعّالة للعملية. (انظر seteuid(2).) يمكن تمرير id كمعرف رقمي أو كسلسلة اسم مستخدم. إذا تمّ تحديد اسم مستخدم، فإنّ الطريقة تُحجِز أثناء حلّ معرفها الرقمي المُرتبط.

ESM

import process from 'node:process'

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`)
  try {
    process.seteuid(501)
    console.log(`New uid: ${process.geteuid()}`)
  } catch (err) {
    console.error(`Failed to set uid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`)
  try {
    process.seteuid(501)
    console.log(`New uid: ${process.geteuid()}`)
  } catch (err) {
    console.error(`Failed to set uid: ${err}`)
  }
}

تتوفر هذه الدالة فقط على منصات POSIX (أي ليست ويندوز أو أندرويد). هذه الميزة غير متوفرة في مؤشرات الترابط Worker.

process.setgid(id)

أضيف في: v0.1.31

• id <string> | <number> اسم المجموعة أو معرفها

تعيّن طريقة process.setgid() هوية المجموعة للعملية. (انظر setgid(2).) يمكن تمرير id كمعرف رقمي أو كسلسلة اسم مجموعة. إذا تمّ تحديد اسم مجموعة، فإنّ هذه الطريقة تُحجِز أثناء حلّ معرفها الرقمي المُرتبط.

ESM

import process from 'node:process'

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`)
  try {
    process.setgid(501)
    console.log(`New gid: ${process.getgid()}`)
  } catch (err) {
    console.error(`Failed to set gid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`)
  try {
    process.setgid(501)
    console.log(`New gid: ${process.getgid()}`)
  } catch (err) {
    console.error(`Failed to set gid: ${err}`)
  }
}

تتوفر هذه الدالة فقط على منصات POSIX (أي ليست ويندوز أو أندرويد). هذه الميزة غير متوفرة في مؤشرات الترابط Worker.

process.setgroups(groups)

أضيف في: v0.9.4

• groups <integer[]>

تعيّنُ طريقة process.setgroups() معرفات المجموعات الثانوية لعملية Node.js. هذه عملية مُميزة تتطلب امتلاك عملية Node.js لصلاحيات root أو صلاحية CAP_SETGID.

يمكن أن تحتوي مصفوفة groups على معرفات مجموعات عددية، أو أسماء مجموعات، أو كليهما.

ESM

import process from 'node:process'

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501])
    console.log(process.getgroups()) // المجموعات الجديدة
  } catch (err) {
    console.error(`فشل في تعيين المجموعات: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501])
    console.log(process.getgroups()) // المجموعات الجديدة
  } catch (err) {
    console.error(`فشل في تعيين المجموعات: ${err}`)
  }
}

تتوفر هذه الدالة فقط على أنظمة POSIX (أي ليست Windows أو Android). هذه الميزة غير متوفرة في مؤشرات الترابط Worker.

process.setuid(id)

أضيف في: v0.1.28

• id <integer> | <string>

تعيّنُ طريقة process.setuid(id) هوية المستخدم لعملية. (انظر setuid(2).) يمكن تمرير id كمعرف رقمي أو كسلسلة نصية لاسم المستخدم. إذا تم تحديد اسم مستخدم، فإن الطريقة تُعَطِّل نفسها أثناء حل معرفها الرقمي المُرتبط.

ESM

import process from 'node:process'

if (process.getuid && process.setuid) {
  console.log(`معرف المستخدم الحالي: ${process.getuid()}`)
  try {
    process.setuid(501)
    console.log(`معرف المستخدم الجديد: ${process.getuid()}`)
  } catch (err) {
    console.error(`فشل في تعيين معرف المستخدم: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getuid && process.setuid) {
  console.log(`معرف المستخدم الحالي: ${process.getuid()}`)
  try {
    process.setuid(501)
    console.log(`معرف المستخدم الجديد: ${process.getuid()}`)
  } catch (err) {
    console.error(`فشل في تعيين معرف المستخدم: ${err}`)
  }
}

تتوفر هذه الدالة فقط على أنظمة POSIX (أي ليست Windows أو Android). هذه الميزة غير متوفرة في مؤشرات الترابط Worker.

process.setSourceMapsEnabled(val)

مضاف في: v16.6.0، v14.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

• val <boolean>

هذه الدالة تُمكن أو تُعطل دعم خريطة المصدر v3 لمسارات المكدس.

وهي توفر نفس الميزات مثل إطلاق عملية Node.js باستخدام خيارات سطر الأوامر --enable-source-maps.

سيتم تحليل وتحميل خرائط المصدر في ملفات JavaScript التي يتم تحميلها فقط بعد تمكين خرائط المصدر.

process.setUncaughtExceptionCaptureCallback(fn)

مضاف في: v9.3.0

• fn <Function> | <null>

تُعيّن دالة process.setUncaughtExceptionCaptureCallback() دالة سيتم استدعاؤها عند حدوث استثناء غير معالج، والتي ستستلم قيمة الاستثناء نفسها كوسيطة أولى لها.

إذا تم تعيين مثل هذه الدالة، فلن يتم إصدار حدث 'uncaughtException'. إذا تم تمرير --abort-on-uncaught-exception من سطر الأوامر أو تم تعيينه من خلال v8.setFlagsFromString()، فلن يتم إلغاء العملية. ستتأثر أيضًا الإجراءات المُهيأة لتُنفذ عند حدوث استثناءات مثل توليد التقارير.

لإلغاء تعيين دالة التقاط، يمكن استخدام process.setUncaughtExceptionCaptureCallback(null). سيؤدي استدعاء هذه الطريقة باستخدام وسيطة غير null أثناء تعيين دالة التقاط أخرى إلى إخراج خطأ.

يُعد استخدام هذه الدالة متبادلاً مع استخدام وحدة domain المُدمجة المُهملة.

process.sourceMapsEnabled

مضاف في: v20.7.0، v18.19.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

• <boolean>

تُعيد خاصية process.sourceMapsEnabled ما إذا كان دعم خريطة المصدر v3 لمسارات المكدس مُمكّنًا.

process.stderr

• <Stream>

تُعيد خاصية process.stderr دفقًا متصلًا بـ stderr (وحدة وصف الملف 2). وهي عبارة عن net.Socket (وهي دفق Duplex) ما لم تشير وحدة وصف الملف 2 إلى ملف، وفي هذه الحالة تكون دفقًا Writable.

تختلف process.stderr عن دفقات Node.js الأخرى بطرق مهمة. راجع ملاحظة حول مدخلات/مخرجات العملية لمزيد من المعلومات.

process.stderr.fd

• <number>

تشير هذه الخاصية إلى قيمة واصف الملف الأساسي لـ process.stderr. القيمة ثابتة عند 2. في مؤشرات الترابط Worker، لا يوجد هذا الحقل.

process.stdin

• <Stream>

تُعيد خاصية process.stdin دفقًا متصلًا بـ stdin (وحدة وصف الملف 0). وهي عبارة عن net.Socket (وهي دفق Duplex) ما لم تشير وحدة وصف الملف 0 إلى ملف، وفي هذه الحالة تكون دفقًا Readable.

للحصول على تفاصيل حول كيفية القراءة من stdin، راجع readable.read().

كدفق Duplex، يمكن أيضًا استخدام process.stdin في الوضع "القديم" المتوافق مع البرامج النصية المكتوبة لـ Node.js قبل الإصدار v0.10. لمزيد من المعلومات، راجع توافق الدفق.

في وضع الدفق "القديم"، يتم إيقاف دفق stdin افتراضيًا، لذلك يجب عليك الاتصال بـ process.stdin.resume() للقراءة منه. لاحظ أيضًا أن الاتصال بـ process.stdin.resume() نفسه سيؤدي إلى تبديل الدفق إلى الوضع "القديم".

process.stdin.fd

• <number>

تشير هذه الخاصية إلى قيمة واصف الملف الأساسي لـ process.stdin. القيمة ثابتة عند 0. في مؤشرات الترابط Worker، لا يوجد هذا الحقل.

process.stdout

• <Stream>

ترجع خاصية process.stdout دفقًا متصلًا بـ stdout (fd 1). إنه عبارة عن net.Socket (وهو دفق Duplex) ما لم يشير fd 1 إلى ملف، وفي هذه الحالة يكون دفقًا Writable.

على سبيل المثال، لنسخ process.stdin إلى process.stdout:

ESM

import { stdin, stdout } from 'node:process'

stdin.pipe(stdout)

CJS

const { stdin, stdout } = require('node:process')

stdin.pipe(stdout)

يختلف process.stdout عن دفقات Node.js الأخرى بطرق مهمة. راجع ملاحظة حول مدخلات/مخرجات العملية لمزيد من المعلومات.

process.stdout.fd

• <number>

تشير هذه الخاصية إلى قيمة مُعرّف الملف الأساسي لـ process.stdout. القيمة ثابتة عند 1. في خيوط Worker، لا يوجد هذا الحقل.

ملاحظة حول مدخلات/مخرجات العملية

يختلف process.stdout و process.stderr عن دفقات Node.js الأخرى بطرق مهمة:

هذه السلوكيات جزئيًا لأسباب تاريخية، حيث أن تغييرها سيخلق عدم توافق مع الإصدارات القديمة، لكن بعض المستخدمين يتوقعونها أيضًا.

تتجنب عمليات الكتابة المتزامنة مشاكل مثل المخرجات المكتوبة باستخدام console.log() أو console.error() التي يتم تداخلها بشكل غير متوقع، أو عدم كتابتها على الإطلاق إذا تم استدعاء process.exit() قبل اكتمال الكتابة غير المتزامنة. راجع process.exit() لمزيد من المعلومات.

تحذير: عمليات الكتابة المتزامنة تُعيق حلقة الأحداث حتى اكتمال الكتابة. قد يكون هذا شبه آني في حالة الإخراج إلى ملف، ولكن تحت حمولة نظام عالية، الأنابيب التي لا يتم قراءتها في الطرف المستقبل، أو مع أجهزة طرفية أو أنظمة ملفات بطيئة، من الممكن أن يتم حظر حلقة الأحداث بشكل متكرر بما يكفي وطويلًا بما يكفي ليحدث تأثيرات سلبية شديدة على الأداء. قد لا تكون هذه مشكلة عند الكتابة إلى جلسة طرفية تفاعلية، ولكن ضع هذا في الاعتبار بعناية خاصة عند إجراء تسجيل الإنتاج إلى دفقات إخراج العملية.

للتحقق مما إذا كان الدفق متصلاً بسياق TTY، تحقق من خاصية isTTY.

على سبيل المثال:

$ node -p "Boolean(process.stdin.isTTY)"
true
$ echo "foo" | node -p "Boolean(process.stdin.isTTY)"
false
$ node -p "Boolean(process.stdout.isTTY)"
true
$ node -p "Boolean(process.stdout.isTTY)" | cat
false

راجع وثائق TTY لمزيد من المعلومات.

process.throwDeprecation

مضاف في: v0.9.12

• <boolean>

تشير القيمة الأولية لـprocess.throwDeprecation إلى ما إذا كانت علامة --throw-deprecation مُعيّنة على عملية Node.js الحالية. process.throwDeprecation قابلة للتغيير، وبالتالي فإن ما إذا كانت تحذيرات الإهمال تؤدي إلى أخطاء يمكن تعديلها أثناء وقت التشغيل. راجع وثائق حدث 'warning' وطريقة emitWarning() لمزيد من المعلومات.

$ node --throw-deprecation -p "process.throwDeprecation"
true
$ node -p "process.throwDeprecation"
undefined
$ node
> process.emitWarning('test', 'DeprecationWarning');
undefined
> (node:26598) DeprecationWarning: test
> process.throwDeprecation = true;
true
> process.emitWarning('test', 'DeprecationWarning');
Thrown:
[DeprecationWarning: test] { name: 'DeprecationWarning' }

process.title

مضاف في: v0.1.104

• <string>

ترجع خاصية process.title عنوان العملية الحالية (أي ترجع القيمة الحالية لـ ps). يُعدّل تعيين قيمة جديدة لـ process.title القيمة الحالية لـ ps.

عند تعيين قيمة جديدة، ستفرض منصات مختلفة قيودًا قصوى مختلفة على طول العنوان. عادةً ما تكون هذه القيود محدودة للغاية. على سبيل المثال، في Linux و macOS، يقتصر process.title على حجم اسم الملف الثنائي بالإضافة إلى طول وسيطات سطر الأوامر لأن تعيين process.title يُعيد كتابة ذاكرة argv للعملية. سمح Node.js v0.8 بسلاسل أطول لعناوين العمليات عن طريق إعادة كتابة ذاكرة environ أيضًا، لكن هذا كان غير آمن واحتمالًا مربكًا في بعض الحالات (الغامضة إلى حد ما).

قد لا يؤدي تعيين قيمة لـ process.title إلى تسمية دقيقة داخل تطبيقات إدارة العمليات مثل macOS Activity Monitor أو Windows Services Manager.

process.traceDeprecation

مضاف في: v0.8.0

• <boolean>

تشير خاصية process.traceDeprecation إلى ما إذا كانت علامة --trace-deprecation مُحددة في عملية Node.js الحالية. راجع وثائق حدث 'warning' وطريقة emitWarning() لمزيد من المعلومات حول سلوك هذه العلامة.

process.umask()

[السجل]

الإصدار	التغييرات
v14.0.0, v12.19.0	تم إلغاء استخدام استدعاء process.umask() بدون وسيطات.
v0.1.19	مضاف في: v0.1.19

[مستقر: 0 - مُلغى]

مستقر: 0 الثبات: 0 - مُلغى. يؤدي استدعاء process.umask() بدون وسيطة إلى كتابة قناع umask على مستوى العملية مرتين. هذا يُدخِل حالة تنافس بين الخيوط، وهو ثغرة أمنية محتملة. لا يوجد واجهة برمجة تطبيقات بديلة آمنة ومتوافقة مع جميع الأنظمة الأساسية.

يعيد process.umask() قناع إنشاء وضع الملف لعملية Node.js. ترث عمليات الطفل القناع من عملية الوالد.

process.umask(mask)

مضاف في: v0.1.19

• mask <string> | <integer>

يُعيّن process.umask(mask) قناع إنشاء وضع الملف لعملية Node.js. ترث عمليات الطفل القناع من عملية الوالد. يُعيد القناع السابق.

ESM

import { umask } from 'node:process'

const newmask = 0o022
const oldmask = umask(newmask)
console.log(`Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`)

CJS

const { umask } = require('node:process')

const newmask = 0o022
const oldmask = umask(newmask)
console.log(`Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`)

في خيوط Worker، سيؤدي process.umask(mask) إلى إلقاء استثناء.

process.uptime()

مضاف في: v0.5.0

• مُخرجات: <number>

تعيدُ طريقة process.uptime() عددَ الثواني التي عملت فيها عملية Node.js الحالية.

تتضمن قيمة الإرجاع أجزاءً من الثانية. استخدم Math.floor() للحصول على ثوانٍ كاملة.

process.version

مضاف في: v0.1.3

• <string>

تحتوي خاصية process.version على سلسلة إصدار Node.js.

ESM

import { version } from 'node:process'

console.log(`Version: ${version}`)
// Version: v14.8.0

CJS

const { version } = require('node:process')

console.log(`Version: ${version}`)
// Version: v14.8.0

للحصول على سلسلة الإصدار بدون الرمز v المُضاف في البداية، استخدم process.versions.node.

process.versions

[History]

الإصدار	التغييرات
v9.0.0	خاصية v8 تتضمن الآن لاحقة خاصة بـ Node.js.
v4.2.0	خاصية icu مدعومة الآن.
v0.2.0	مضاف في: v0.2.0

• <Object>

تعيد خاصية process.versions كائنًا يسرد سلاسل إصدارات Node.js وما يعتمد عليها. يشير process.versions.modules إلى إصدار ABI الحالي، والذي يزداد كلما تغيرت واجهة برمجة التطبيقات C++. سيرفض Node.js تحميل الوحدات التي تم تجميعها مقابل إصدار ABI مختلف للوحدة النمطية.

ESM

import { versions } from 'node:process'

console.log(versions)

CJS

const { versions } = require('node:process')

console.log(versions)

سوف يُنتج كائنًا مشابهًا لما يلي:

{ node: '23.0.0',
  acorn: '8.11.3',
  ada: '2.7.8',
  ares: '1.28.1',
  base64: '0.5.2',
  brotli: '1.1.0',
  cjs_module_lexer: '1.2.2',
  cldr: '45.0',
  icu: '75.1',
  llhttp: '9.2.1',
  modules: '127',
  napi: '9',
  nghttp2: '1.61.0',
  nghttp3: '0.7.0',
  ngtcp2: '1.3.0',
  openssl: '3.0.13+quic',
  simdjson: '3.8.0',
  simdutf: '5.2.4',
  sqlite: '3.46.0',
  tz: '2024a',
  undici: '6.13.0',
  unicode: '15.1',
  uv: '1.48.0',
  uvwasi: '0.0.20',
  v8: '12.4.254.14-node.11',
  zlib: '1.3.0.1-motley-7d77fb7' }

رموز الخروج

يخرج Node.js عادةً برمز حالة 0 عندما لا توجد عمليات غير متزامنة معلقة. تُستخدم رموز الحالة التالية في حالات أخرى:

• 1 استثناء خطير غير معالج: حدث استثناء غير معالج، ولم يتم التعامل معه بواسطة نطاق أو مُعالِج حدث 'uncaughtException'.
• 2: غير مستخدم (محجوز بواسطة Bash لإساءة استخدام مُدمج)
• 3 خطأ تحليل داخلي في JavaScript: تسبب كود مصدر JavaScript الداخلي في عملية تمهيد Node.js في حدوث خطأ في التحليل. هذا نادر للغاية، وعادةً ما يمكن أن يحدث فقط أثناء تطوير Node.js نفسه.
• 4 فشل تقييم داخلي في JavaScript: فشل كود مصدر JavaScript الداخلي في عملية تمهيد Node.js في إرجاع قيمة دالة عند تقييمه. هذا نادر للغاية، وعادةً ما يمكن أن يحدث فقط أثناء تطوير Node.js نفسه.
• 5 خطأ خطير: حدث خطأ خطير لا يمكن إصلاحه في V8. عادةً ما يتم طباعة رسالة إلى stderr مع بادئة FATAL ERROR.
• 6 معالج استثناء داخلي غير دالة: حدث استثناء غير معالج، لكن دالة معالج الاستثناء الخطير الداخلية تم تعيينها بطريقة ما إلى غير دالة، ولم يمكن استدعاؤها.
• 7 فشل وقت التشغيل لمعالج الاستثناء الداخلي: حدث استثناء غير معالج، وألقت دالة معالج الاستثناء الخطير الداخلية نفسها خطأً أثناء محاولة التعامل معه. يمكن أن يحدث هذا، على سبيل المثال، إذا ألقى مُعالِج 'uncaughtException' أو domain.on('error') خطأً.
• 8: غير مستخدم. في الإصدارات السابقة من Node.js، أشار رمز الخروج 8 أحيانًا إلى استثناء غير معالج.
• 9 حجة غير صالحة: إما تم تحديد خيار غير معروف، أو تم توفير خيار يتطلب قيمة بدون قيمة.
• 10 فشل وقت التشغيل الداخلي لـ JavaScript: ألقى كود مصدر JavaScript الداخلي في عملية تمهيد Node.js خطأً عند استدعاء دالة التمهيد. هذا نادر للغاية، وعادةً ما يمكن أن يحدث فقط أثناء تطوير Node.js نفسه.
• 12 حجة تصحيح غير صالحة: تم تعيين خيارات --inspect و/أو --inspect-brk، لكن رقم المنفذ المختار كان غير صالح أو غير متوفر.
• 13 انتظار مستوى أعلى غير مستقر: تم استخدام await خارج دالة في كود المستوى الأعلى، لكن Promise المُمرر لم يستقر أبدًا.
• 14 فشل اللقطة: تم بدء تشغيل Node.js لإنشاء لقطة بدء تشغيل V8 وفشلت لأن بعض متطلبات حالة التطبيق لم يتم استيفاؤها.
• \>128 خروجات الإشارة: إذا تلقى Node.js إشارة خطيرة مثل SIGKILL أو SIGHUP، فسيكون رمز الخروج الخاص به 128 بالإضافة إلى قيمة رمز الإشارة. هذه ممارسة POSIX قياسية، نظرًا لأن رموز الخروج مُعرّفة بأنها أعداد صحيحة من 7 بتات، وتعيّن خروجات الإشارة البت ذي الترتيب الأعلى، ثم تحتوي على قيمة رمز الإشارة. على سبيل المثال، الإشارة SIGABRT لها قيمة 6، لذلك سيكون رمز الخروج المتوقع 128 + 6، أو 134.