رابط خط فرمان Node.js: گزینه‌ها و مجوزها

1. مقدمه

رابط خط فرمان Node.js ابزارهای دیباگ داخلی، روش‌های مختلف اجرای اسکریپت و گزینه‌های پیکربندی زمان اجرا را در اختیار توسعه‌دهندگان قرار می‌دهد. اجرای دستور man node در ترمینال صفحهٔ راهنمای این گزینه‌ها را نمایش می‌دهد.

2. نحو (Synopsis)

node [options] [V8 options] [ | -e "script" | -] [--] [arguments]
node inspect [ | -e "script" | :] …
node --v8-options

اجرای node بدون آرگومان محیط REPL را آغاز می‌کند.

3. نقطهٔ ورود برنامه

• اگر مسیر مطلق نباشد، به‌صورت نسبی از دایرکتوری جاری حل می‌شود.
• به‌طور پیش‌فرض با require() بارگذاری می‌شود، مگر شرایطی که بارگذاری با ماژول ECMAScript اجباری باشد (مانند --import، پسوندهای .mjs/.mts/.wasm یا وجود "type": "module" در package.json).

4. گزینه‌های عمومی

• -: معادل stdin، اسکریپت از ورودی خوانده می‌شود.
• --: پایان گزینه‌های Node.js را مشخص می‌کند و آرگومان‌های بعدی به اسکریپت منتقل می‌شوند.
• --abort-on-uncaught-exception: به‌جای خروج، فایل core برای دیباگ تولید می‌کند.

5. گزینه‌های مدل مجوز

Node.js مدلی برای محدودسازی عملیات حساس معرفی کرده است. برای فعال‌سازی باید پرچم‌ها به‌طور صریح ارسال شوند.

• --allow-addons: بارگذاری افزونه‌های بومی را فعال می‌کند. بدون آن، خطای ERR_DLOPEN_DISABLED رخ می‌دهد.
• --allow-child-process: اجازهٔ ایجاد فرآیندهای فرزند را می‌دهد. بدون آن، خطای ERR_ACCESS_DENIED رخ می‌دهد.
• --allow-fs-read: دسترسی خواندن فایل‌ها را برای مسیرهای مشخص فعال می‌کند. می‌توان چند مسیر را با چند پرچم مجزا تعیین کرد.
• --allow-fs-write: دسترسی نوشتن فایل‌ها را برای مسیرهای مشخص فعال می‌کند. استفاده از مسیرهای جداشده با کاما منسوخ شده است.
• --allow-inspector: اجازهٔ اتصال از طریق پروتکل inspector را می‌دهد. بدون آن، خطای ERR_ACCESS_DENIED رخ می‌دهد.

6. مثال‌ها

// مثال: اجازهٔ خواندن از همهٔ مسیرها
$ node --permission --allow-fs-read=* index.js

// مثال: اجازهٔ ایجاد فرآیند فرزند
$ node --permission --allow-child-process index.js

// مثال: فعال‌سازی inspector
$ node --permission --allow-inspector index.js

7. نکات مهم

• گزینه‌ها می‌توانند با خط تیره یا زیرخط نوشته شوند (مثلاً --pending-deprecation معادل --pending_deprecation است).
• گزینه‌های خط فرمان بر گزینه‌های محیطی NODE_OPTIONS اولویت دارند.
• اگر گزینه‌ای چندبار تکرار شود، آخرین مقدار استفاده می‌شود.

نتیجه‌گیری

رابط خط فرمان Node.js ابزارهای قدرتمندی برای پیکربندی رفتار زمان اجرا و اعمال امنیت از طریق مدل مجوز فراهم می‌کند. درک و استفاده از پرچم‌هایی مانند --allow-addons، --allow-child-process و --allow-fs-read/write تضمین می‌کند که برنامه‌ها به‌صورت امن و کارآمد اجرا شوند.

1. گزینه‌های Permission Model

• --allow-net: اجازهٔ دسترسی به شبکه. بدون آن، هر اتصال شبکه‌ای خطای ERR_ACCESS_DENIED ایجاد می‌کند.
• --allow-wasi: اجازهٔ ایجاد نمونه‌های WASI. بدون آن، خطای ERR_ACCESS_DENIED رخ می‌دهد.
• --allow-worker: اجازهٔ ایجاد Worker Threads. بدون آن، خطای ERR_ACCESS_DENIED رخ می‌دهد.

2. Snapshot Options

• --build-snapshot: ایجاد Snapshot از وضعیت برنامه و ذخیرهٔ آن در فایل blob.
• --build-snapshot-config: استفاده از فایل JSON برای پیکربندی رفتار ساخت Snapshot (مانند builder یا withoutCodeCache).

3. بررسی و تکمیل

• -c, --check: بررسی نحوی اسکریپت بدون اجرا.
• --completion-bash: تولید اسکریپت تکمیل خودکار برای Bash.
• -C condition, --conditions=condition: تعریف شرایط سفارشی برای exports resolution.

4. CPU Profiling

• --cpu-prof: فعال‌سازی پروفایل‌گیری CPU و ذخیرهٔ خروجی در فایل.
• --cpu-prof-dir: تعیین مسیر ذخیرهٔ پروفایل‌ها.
• --cpu-prof-interval: تعیین بازهٔ نمونه‌گیری (به میکروثانیه).
• --cpu-prof-name: تعیین نام فایل پروفایل.

5. گزینه‌های تشخیصی و امنیتی

• --diagnostic-dir: مسیر پیش‌فرض برای خروجی‌های تشخیصی.
• --disable-proto=mode: غیرفعال‌سازی ویژگی Object.prototype.__proto__ (حذف یا پرتاب خطا).
• --disable-sigusr1: غیرفعال‌سازی شروع دیباگ با سیگنال SIGUSR1.
• --disable-warning=code-or-type: غیرفعال‌سازی هشدارهای خاص بر اساس کد یا نوع (مانند DeprecationWarning یا ExperimentalWarning).

6. مثال‌ها

// اجازهٔ دسترسی به شبکه
$ node --permission --allow-net index.js

// ساخت Snapshot
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

// پروفایل‌گیری CPU
$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js

// غیرفعال‌سازی هشدار خاص
$ node --disable-warning=DEP0025 index.js

نتیجه‌گیری

گزینه‌های پیشرفتهٔ CLI در Node.js ابزارهای قدرتمندی برای مدیریت امنیت، کارایی و دیباگ فراهم می‌کنند. استفادهٔ صحیح از پرچم‌هایی مانند --allow-net، --build-snapshot و --cpu-prof به توسعه‌دهندگان کمک می‌کند برنامه‌های مقیاس‌پذیر و امن بسازند.

1. WebAssembly Options

• --disable-wasm-trap-handler: غیرفعال‌سازی بهینه‌سازی trap-handler برای WebAssembly. این کار اجازهٔ اجرای WebAssembly را در سیستم‌هایی با فضای آدرس محدود می‌دهد، هرچند با کارایی کمتر.

2. Code Generation Restrictions

• --disallow-code-generation-from-strings: باعث می‌شود ویژگی‌هایی مانند eval و new Function که کد را از رشته تولید می‌کنند، استثنا پرتاب کنند. این گزینه امنیت را افزایش می‌دهد.

3. DNS Options

• --dns-result-order: تعیین ترتیب پیش‌فرض در dns.lookup() و dnsPromises.lookup(). مقادیر مجاز: ipv4first, ipv6first, verbatim.

4. Security and Networking

• --enable-fips: فعال‌سازی رمزنگاری سازگار با FIPS در زمان اجرا (نیازمند OpenSSL سازگار).
• --enable-network-family-autoselection: فعال‌سازی الگوریتم انتخاب خودکار خانوادهٔ شبکه.

5. Source Maps

• --enable-source-maps: فعال‌سازی پشتیبانی از Source Maps برای نمایش stack trace مرتبط با فایل‌های اصلی (مانند TypeScript). این گزینه می‌تواند تأخیر ایجاد کند اگر Error.stack زیاد استفاده شود.

6. Entry Point Options

• --entry-url: تفسیر نقطهٔ ورود به‌عنوان URL به‌جای مسیر فایل. از قوانین ECMAScript module resolution پیروی می‌کند.

7. Environment File Options

• --env-file: بارگذاری متغیرهای محیطی از فایل. اگر فایل وجود نداشته باشد خطا پرتاب می‌شود.
• --env-file-if-exists: مشابه --env-file اما بدون خطا در صورت نبود فایل.

8. Eval Option

• -e, --eval "script": اجرای مستقیم کد جاوااسکریپت از خط فرمان. در ویندوز باید از " برای نقل قول استفاده شود.

9. Experimental Features

• --experimental-addon-modules: پشتیبانی آزمایشی برای import افزونه‌های .node.
• --experimental-config-file: بارگذاری فایل پیکربندی JSON سفارشی برای تنظیمات Node.js.
• --experimental-default-config-file: بارگذاری خودکار فایل node.config.json از دایرکتوری جاری.
• --experimental-eventsource: فعال‌سازی API جهانی EventSource.
• --experimental-import-meta-resolve: پشتیبانی از import.meta.resolve() با آرگومان parentURL.
• --experimental-inspector-network-resource: پشتیبانی آزمایشی از منابع شبکه در inspector.

10. Examples

// اجرای WebAssembly بدون trap-handler
$ node --disable-wasm-trap-handler index.js

// بارگذاری متغیرهای محیطی
$ node --env-file=.env --env-file=.development.env index.js

// اجرای کد جاوااسکریپت از خط فرمان
$ node -e "console.log('Hello World')"

// فعال‌سازی Source Maps
$ node --enable-source-maps index.js

نتیجه‌گیری

گزینه‌های پیشرفتهٔ CLI در Node.js ابزارهای قدرتمندی برای مدیریت امنیت، پیکربندی و ویژگی‌های آزمایشی فراهم می‌کنند. استفادهٔ صحیح از پرچم‌هایی مانند --disable-wasm-trap-handler، --enable-source-maps و --experimental-config-file به توسعه‌دهندگان کمک می‌کند برنامه‌های امن‌تر، قابل‌دیباگ‌تر و انعطاف‌پذیرتر بسازند.

1. Experimental Loader

• --experimental-loader=module: مشخص کردن ماژولی برای hooks سفارشی. استفاده از این پرچم توصیه نمی‌شود و ممکن است حذف شود.

2. Networking and Protocols

• --experimental-network-inspection: پشتیبانی آزمایشی از بازرسی شبکه با Chrome DevTools.
• --experimental-quic: فعال‌سازی پشتیبانی آزمایشی از پروتکل QUIC.

3. Module and Language Features

• --experimental-require-module: بارگذاری گراف ماژول ES به‌صورت synchronous در require().
• --experimental-shadow-realm: فعال‌سازی پشتیبانی از ShadowRealm.
• --experimental-transform-types: تبدیل سینتکس مخصوص TypeScript به کد جاوااسکریپت. ضمنی --enable-source-maps.
• --experimental-vm-modules: پشتیبانی آزمایشی از ماژول‌های ES در node:vm.
• --experimental-wasi-unstable-preview1: پشتیبانی آزمایشی از WASI.

4. Testing Features

• --experimental-test-coverage: تولید گزارش پوشش کد هنگام اجرای تست‌ها.
• --experimental-test-module-mocks: فعال‌سازی mocking ماژول‌ها در تست رانر.

5. SEA and Config

• --experimental-sea-config: تولید blob برای ساخت اپلیکیشن تک‌فایلی.

6. Inspection

• --experimental-worker-inspection: پشتیبانی آزمایشی از بازرسی Worker با Chrome DevTools.

7. Garbage Collection

• --expose-gc: نمایش تابع gc() از V8 برای مدیریت دستی garbage collection.

8. Security Flags

• --force-context-aware: جلوگیری از بارگذاری افزونه‌های بومی غیر context-aware.
• --force-fips: فعال‌سازی اجباری رمزنگاری سازگار با FIPS.
• --force-node-api-uncaught-exceptions-policy: enforce رفتار صحیح برای uncaughtException در Node-API callbacks.
• --frozen-intrinsics: فریز کردن اشیاء داخلی مانند Array و Object.

9. Heap Profiling

• --heap-prof: فعال‌سازی پروفایل‌گیری heap و ذخیرهٔ خروجی در فایل.
• --heap-prof-dir: تعیین مسیر ذخیرهٔ پروفایل‌ها.
• --heap-prof-interval: تعیین بازهٔ نمونه‌گیری (به بایت).
• --heap-prof-name: تعیین نام فایل پروفایل.

10. Heap Snapshots

• --heapsnapshot-near-heap-limit=max_count: تولید snapshot زمانی که استفادهٔ heap نزدیک به محدودیت است.
• --heapsnapshot-signal=signal: نوشتن heap dump هنگام دریافت سیگنال مشخص.

11. Help Option

• -h, --help: نمایش گزینه‌های خط فرمان Node.js.

Examples

// فعال‌سازی پروفایل‌گیری heap
$ node --heap-prof index.js

// تولید snapshot هنگام نزدیک شدن به محدودیت heap
$ node --heapsnapshot-near-heap-limit=3 index.js

// نمایش کمک
$ node --help

نتیجه‌گیری

گزینه‌های آزمایشی و پروفایل‌گیری در Node.js ابزارهای قدرتمندی برای تست ویژگی‌های جدید، افزایش امنیت و بررسی عملکرد حافظه و CPU فراهم می‌کنند. استفادهٔ صحیح از پرچم‌هایی مانند --experimental-quic، --heap-prof و --expose-gc به توسعه‌دهندگان کمک می‌کند برنامه‌های پایدارتر و امن‌تر بسازند.

1. Module and Import Options

• --icu-data-dir=file: مشخص کردن مسیر بارگذاری داده‌های ICU.
• --import=module: بارگذاری ماژول‌های ES در زمان شروع. ماژول‌های --require قبل از --import اجرا می‌شوند.
• --input-type=type: تعیین نوع ورودی برای --eval یا STDIN (commonjs, module, typescript).

2. HTTP and Parser Options

• --insecure-http-parser: فعال‌سازی حالت lenient برای HTTP parser. استفاده از این پرچم خطرناک است و می‌تواند حملات امنیتی ایجاد کند.

3. Inspector and Debugging

• --inspect: فعال‌سازی دیباگر V8 روی host:port.
• --inspect-brk: فعال‌سازی دیباگر و توقف در ابتدای اجرای اسکریپت.
• --inspect-port: تعیین host:port برای دیباگر.
• --inspect-wait: فعال‌سازی دیباگر و انتظار برای اتصال debugger.
• --inspect-publish-uid: تعیین نحوهٔ انتشار URL دیباگر.

4. Interactive and Execution Options

• -i, --interactive: باز کردن REPL حتی اگر stdin ترمینال نباشد.
• --jitless: غیرفعال‌سازی تخصیص حافظه اجرایی در زمان اجرا (امنیت بیشتر، کارایی کمتر).
• --localstorage-file=file: تعیین فایل برای ذخیرهٔ داده‌های localStorage.

5. Memory Management

• --max-http-header-size=size: تعیین حداکثر اندازهٔ هدرهای HTTP.
• --max-old-space-size-percentage: تخصیص درصدی از حافظهٔ سیستم به V8 heap.

6. Security and Addons

• --no-addons: غیرفعال‌سازی بارگذاری افزونه‌های بومی.
• --no-deprecation: بی‌صدا کردن هشدارهای deprecation.
• --no-warnings: بی‌صدا کردن همهٔ هشدارها.
• --permission: فعال‌سازی Permission Model برای محدودسازی دسترسی‌ها.

7. OpenSSL Options

• --openssl-config=file: بارگذاری فایل پیکربندی OpenSSL.
• --openssl-legacy-provider: فعال‌سازی provider قدیمی در OpenSSL 3.0.
• --openssl-shared-config: فعال‌سازی بخش پیکربندی پیش‌فرض OpenSSL.

8. Symlink Options

• --preserve-symlinks: حفظ مسیر symlink هنگام بارگذاری ماژول‌ها.
• --preserve-symlinks-main: اعمال رفتار مشابه برای ماژول اصلی.

9. Profiling and Reports

• --prof: تولید خروجی پروفایل V8.
• --prof-process: پردازش خروجی پروفایل V8.
• --redirect-warnings=file: نوشتن هشدارها در فایل به‌جای stderr.
• --report-compact: تولید گزارش در قالب JSON تک‌خطی.
• --report-dir: تعیین مسیر ذخیرهٔ گزارش‌ها.
• --report-exclude-env: حذف متغیرهای محیطی از گزارش تشخیصی.

Examples

// فعال‌سازی دیباگر روی پورت تصادفی
$ node --inspect=0 index.js

// بارگذاری ماژول ES در زمان شروع
$ node --import=module.js index.js

// اجرای REPL حتی بدون ترمینال
$ node -i

// بی‌صدا کردن هشدارها
$ node --no-warnings index.js

نتیجه‌گیری

گزینه‌های CLI در Node.js ابزارهای قدرتمندی برای مدیریت ماژول‌ها، دیباگ و امنیت فراهم می‌کنند. استفادهٔ صحیح از پرچم‌هایی مانند --inspect، --permission و --openssl-config به توسعه‌دهندگان کمک می‌کند برنامه‌های امن‌تر و قابل‌دیباگ‌تر بسازند.

1. Diagnostic Report Options

• --report-exclude-network: حذف اطلاعات شبکه از گزارش تشخیصی.
• --report-filename=filename: تعیین نام فایل گزارش (stdout یا stderr نیز قابل استفاده است).
• --report-on-fatalerror: تولید گزارش هنگام خطاهای کشنده (مانند out-of-memory).
• --report-on-signal: تولید گزارش هنگام دریافت سیگنال مشخص.
• --report-signal=signal: تعیین سیگنال برای تولید گزارش (پیش‌فرض SIGUSR2).
• --report-uncaught-exception: تولید گزارش هنگام خروج به دلیل استثنای مدیریت‌نشده.

2. Module Preloading

• -r, --require module: بارگذاری ماژول مشخص در زمان شروع. این ماژول‌ها قبل از --import اجرا می‌شوند.

3. Run Scripts

• --run: اجرای اسکریپت‌های تعریف‌شده در package.json. ساده‌تر و سریع‌تر از npm run اما با امکانات محدودتر.

4. Secure Heap Options

• --secure-heap=n: ایجاد heap امن در OpenSSL برای جلوگیری از نشت داده‌های حساس.
• --secure-heap-min=n: تعیین حداقل تخصیص از heap امن.

5. Snapshot Options

• --snapshot-blob=path: تعیین مسیر blob برای ذخیره یا بارگذاری snapshot برنامه.

6. Test Runner Options

• --test: اجرای تست‌ها با استفاده از test runner داخلی Node.js.
• --test-concurrency: تعیین حداکثر تعداد فایل‌های تست همزمان.
• --test-coverage-branches/functions/lines: تعیین حداقل درصد پوشش کد برای شاخه‌ها، توابع و خطوط.
• --test-coverage-include / --test-coverage-exclude: مدیریت فایل‌های شامل یا حذف‌شده از گزارش پوشش کد.
• --test-force-exit: خروج از فرآیند پس از پایان همهٔ تست‌ها.
• --test-global-setup=module: بارگذاری ماژول برای تنظیمات سراسری قبل از اجرای تست‌ها.
• --test-isolation=mode: تعیین نوع ایزولاسیون تست‌ها (process یا none).
• --test-name-pattern / --test-skip-pattern: اجرای یا رد تست‌ها بر اساس الگوی نام.
• --test-only: اجرای فقط تست‌هایی که با only مشخص شده‌اند.
• --test-reporter / --test-reporter-destination: تعیین گزارشگر تست و مقصد آن.
• --test-rerun-failures: اجرای مجدد تست‌های ناموفق با استفاده از فایل وضعیت.
• --test-shard: تقسیم مجموعهٔ تست‌ها به بخش‌های مساوی و اجرای یک بخش خاص.

Examples

// تولید گزارش هنگام خطای کشنده
$ node --report-on-fatalerror index.js

// اجرای تست‌ها با ایزولاسیون فرآیندی
$ node --test --test-isolation=process

// اجرای فقط تست‌های مشخص‌شده با only
$ node --test --test-only

// اجرای اسکریپت test از package.json
$ node --run test

نتیجه‌گیری

گزینه‌های CLI در Node.js برای گزارش‌گیری تشخیصی و مدیریت تست‌ها ابزارهای قدرتمندی فراهم می‌کنند. پرچم‌هایی مانند --report-on-fatalerror، --test-coverage-lines و --secure-heap به توسعه‌دهندگان کمک می‌کنند مشکلات را بهتر تحلیل کرده و تست‌های پایدارتر و امن‌تر اجرا کنند.

1. Test Runner Options

• --test-timeout: تعیین زمان حداکثر اجرای تست‌ها (به میلی‌ثانیه). پیش‌فرض Infinity.
• --test-update-snapshots: بازتولید فایل‌های snapshot برای تست‌های snapshot.

2. Deprecation and Title Options

• --throw-deprecation: پرتاب خطا هنگام استفاده از APIهای منسوخ.
• --trace-deprecation: چاپ stack trace برای هشدارهای deprecation.
• --title=title: تعیین عنوان فرآیند در زمان شروع.

3. TLS Options

• --tls-cipher-list: تعیین لیست cipherهای TLS.
• --tls-keylog=file: ذخیرهٔ کلیدهای TLS در فایل برای تحلیل ترافیک.
• --tls-min-v1.2 / --tls-max-v1.3: تعیین نسخه‌های حداقل و حداکثر TLS.

4. Environment Variable Tracing

• --trace-env: چاپ دسترسی‌ها به متغیرهای محیطی.
• --trace-env-js-stack: چاپ stack trace جاوااسکریپت هنگام دسترسی.
• --trace-env-native-stack: چاپ stack trace بومی هنگام دسترسی.

5. Trace Events

• --trace-event-categories: تعیین دسته‌های رویداد برای ردیابی.
• --trace-event-file-pattern: تعیین قالب فایل خروجی رویدادها.
• --trace-events-enabled: فعال‌سازی جمع‌آوری اطلاعات رویدادها.

6. Other Trace Options

• --trace-exit: چاپ stack trace هنگام خروج فرآیند.
• --trace-uncaught: چاپ stack trace برای استثناهای مدیریت‌نشده.
• --trace-warnings: چاپ stack trace برای هشدارها.
• --trace-sync-io: چاپ stack trace هنگام شناسایی I/O همزمان.
• --trace-tls: چاپ اطلاعات بسته‌های TLS.

7. Memory and Heap Options

• --track-heap-objects: ردیابی تخصیص اشیاء heap برای snapshotها.
• --unhandled-rejections=mode: تعیین رفتار هنگام رخداد promiseهای مدیریت‌نشده (throw, strict, warn, none).

8. CA and Proxy Options

• --use-bundled-ca: استفاده از CAهای بسته‌بندی‌شده توسط Node.js.
• --use-openssl-ca: استفاده از CAهای پیش‌فرض OpenSSL.
• --use-system-ca: استفاده از CAهای سیستم.
• --use-env-proxy: استفاده از متغیرهای محیطی HTTP_PROXY و HTTPS_PROXY.

9. Watch Mode Options

• --watch: اجرای Node.js در حالت watch و ری‌استارت هنگام تغییر فایل‌ها.
• --watch-path: تعیین مسیرهای خاص برای watch.
• --watch-preserve-output: جلوگیری از پاک شدن خروجی کنسول هنگام ری‌استارت.
• --watch-kill-signal: تعیین سیگنال برای پایان فرآیند هنگام ری‌استارت.

10. Environment Variables

• NODE_OPTIONS: تعیین گزینه‌های CLI به‌صورت پیش‌فرض.
• NODE_EXTRA_CA_CERTS: افزودن گواهی‌های CA اضافی.
• NODE_ICU_DATA: تعیین مسیر داده‌های ICU.
• NODE_V8_COVERAGE: فعال‌سازی خروجی پوشش کد V8.
• NODE_REPL_HISTORY: تعیین مسیر ذخیرهٔ تاریخچهٔ REPL.
• NODE_TLS_REJECT_UNAUTHORIZED: غیرفعال‌سازی اعتبارسنجی TLS (غیرامن).
• UV_THREADPOOL_SIZE