process.argv في Node.js: قراءة وسائط سطر الأوامر

process.argv مصفوفة تحمل سطر الأوامر الذي شغّل برنامج Node.js. الفهرس 0 هو مسار الملف التنفيذي node، والفهرس 1 هو مسار سكربتك، ووسائطك أنت تبدأ من الفهرس 2. إذن يعطيك process.argv.slice(2) بالضبط ما كتبه المستخدم بعد اسم الملف، ودائمًا كنصوص.

// $ node index.js Ada 42 --verbose
const path = require('path');

console.log('argv[0]:', path.basename(process.argv[0]));
console.log('argv[1]:', path.basename(process.argv[1]));
console.log('your arguments:', process.argv.slice(2));

العنصران الأولان مساران كاملان، لذلك لا يطبع المثال إلا الجزء الأخير من كل منهما (node وindex.js)، ثم [ 'Ada', '42', '--verbose' ]. عدّل صف الوسائط إلى Grace 7 وشغّل من جديد: تتغير المصفوفة معه.

ما الذي يدخل في process.argv

تقسم الصدفة (shell) السطر الواقع بعد node عند المسافات وتسلّم القطع إلى Node.js. الخيارات المكتوبة قبل اسم الملف تخص Node.js نفسه، لا برنامجك:

node --max-old-space-size=4096 index.js --port=8080
# process.argv.slice(2) is [ '--port=8080' ]
# process.execArgv is      [ '--max-old-space-size=4096' ]

علامات الاقتباس تجمع الكلمات في وسيط واحد ("Ada Lovelace" يصل كنص واحد)، وتوسّع الصدفة أنماطًا مثل *.txt إلى أسماء ملفات قبل أن يراها Node.js أصلًا.

احصل على الوسائط عبر slice(2)

تفكك معظم السكربتات الوسائط التي تتوقعها وتعطي كلًا منها قيمة افتراضية:

// $ node index.js Ada
const [name = 'world', greeting = 'Hello'] = process.argv.slice(2);

console.log(`${greeting}, ${name}`);

طبع Hello, Ada: ملأ وسيط واحد name، ورجع greeting إلى قيمته الافتراضية. أضف Hi بعد Ada في صف الوسائط فيطبع Hi, Ada؛ وأفرغ الصف فتحصل على Hello, world.

الأرقام تصل كنصوص

لا أنواع في الصدفة. كل وسيط نص، لذلك تخطئ العمليات الحسابية عليه حتى تحوّله:

// $ node index.js 7 5
const [a, b] = process.argv.slice(2);

console.log('as strings:', a + b);
console.log('as numbers:', Number(a) + Number(b));

const n = Number('ten');
console.log('bad input:', n, Number.isNaN(n));

ضمّ a + b النصين إلى 75، وأعطى Number() القيمة 12. الكلمة التي ليست رقمًا تصبح NaN، فتحقق بـ Number.isNaN واطبع رسالة استخدام بدلًا من المتابعة بقيمة معطوبة.

تحليل خيارات --name=value يدويًا

لخيارين أو ثلاثة تكفي حلقة قصيرة. هذه تحوّل --port=8080 إلى port: '8080'، و--verbose المجرد إلى true، وتحتفظ بكل ما عدا ذلك كوسيط موضعي:

// $ node index.js build --port=8080 --verbose src
const flags = {};
const positional = [];

for (const arg of process.argv.slice(2)) {
    if (arg.startsWith('--')) {
        const [key, value = true] = arg.slice(2).split('=');
        flags[key] = value;
    } else {
        positional.push(arg);
    }
}

console.log(JSON.stringify(flags));
console.log(positional);

طبع {"port":"8080","verbose":true} و[ 'build', 'src' ]، وما زالت port نصًا. لا تتعامل هذه الحلقة مع الخيارات القصيرة مثل -p ولا مع قيمة في الوسيط التالي (--port 8080)؛ لذلك استخدم المحلل المدمج أدناه.

util.parseArgs، المحلل المدمج

يأتي Node.js 18.3 وما بعده مع util.parseArgs، الذي يتعامل مع الخيارات الطويلة والقصيرة، والقيم في الوسيط التالي، والقيم المنطقية، والقيم الافتراضية:

const { parseArgs } = require('node:util');

// node index.js -p 8080 --verbose src
const { values, positionals } = parseArgs({
    options: {
        port: { type: 'string', short: 'p', default: '3000' },
        verbose: { type: 'boolean', short: 'v' },
    },
    allowPositionals: true,
});

console.log(values);      // [Object: null prototype] { port: '8080', verbose: true }
console.log(positionals); // [ 'src' ]

يقرأ parseArgs القيمة process.argv.slice(2) افتراضيًا. ويرمي خطأ عند خيار لم تعلن عنه، وهذا يلتقط الأخطاء الإملائية مثل --prot؛ مرّر strict: false لقبول الخيارات غير المعروفة. أنواع الخيارات هي string وboolean فقط، فما زالت الأرقام تحتاج Number(). وvalues كائن بلا prototype، ولهذا يُطبع مع [Object: null prototype]؛ اقرأه كأي كائن.

أخطاء شائعة

قراءة process.argv[0] على أنه الوسيط الأول. إنه مسار node. وسيطك الأول هو process.argv[2].

نسيان أن كل شيء نص. '10' > '9' قيمته false، لأن النصوص تُقارن حرفًا حرفًا. حوّل أولًا.

وضع الأسرار في الوسائط. تظهر أسطر الأوامر في سجل الصدفة وفي قوائم العمليات التي يستطيع المستخدمون الآخرون على الجهاز قراءتها. مرّر كلمات المرور ومفاتيح API عبر متغيرات البيئة بدلًا من ذلك.