واجهة سطر الأوامر (CLI) في Next.js

تتيح لك واجهة سطر الأوامر (CLI) في Next.js تطوير وبناء وتشغيل تطبيقك والمزيد.

الاستخدام الأساسي:

Terminal

npm run next [command] [options]

مرجع

الخيارات التالية متاحة:

الخيارات	الوصف
`-h` أو `--help`	يعرض جميع الخيارات المتاحة
`-v` أو `--version`	يعرض رقم إصدار Next.js

الأوامر

الأوامر التالية متاحة:

الأمر	الوصف
`dev`	يبدأ Next.js في وضع التطوير مع إعادة تحميل الوحدات الساخنة (HMR)، وإعداد التقارير عن الأخطاء، والمزيد.
`build`	ينشئ بناءً مُحسّنًا للإنتاج لتطبيقك. يعرض معلومات عن كل مسار.
`start`	يبدأ Next.js في وضع الإنتاج. يجب تجميع التطبيق أولاً باستخدام `next build`.
`info`	يطبع تفاصيل ذات صلة عن النظام الحالي والتي يمكن استخدامها للإبلاغ عن أخطاء Next.js.
`lint`	يشغل ESLint لجميع الملفات في مجلدات `/src`، `/app`، `/pages`، `/components`، و `/lib`. كما يوفر إعدادًا موجهًا لتثبيت أي تبعيات مطلوبة إذا لم يكن ESLint مضبوطًا بالفعل في تطبيقك.
`telemetry`	يسمح لك بتمكين أو تعطيل جمع بيانات التتبع المجهولة بالكامل في Next.js.

معلومة مفيدة: تشغيل next بدون أمر يعادل next dev.

خيارات `next dev`

يبدأ next dev التطبيق في وضع التطوير مع إعادة تحميل الوحدات الساخنة (HMR)، وإعداد التقارير عن الأخطاء، والمزيد. الخيارات التالية متاحة عند تشغيل next dev:

الخيار	الوصف
`-h, --help`	يعرض جميع الخيارات المتاحة.
`[directory]`	مجلد لبناء التطبيق فيه. إذا لم يتم توفيره، يتم استخدام المجلد الحالي.
`--turbo`	يبدأ وضع التطوير باستخدام Turbopack.
`-p` أو `--port <port>`	يحدد رقم المنفذ لبدء التطبيق عليه. الافتراضي: 3000، متغير البيئة: PORT
`-H` أو `--hostname <hostname>`	يحدد اسم المضيف لبدء التطبيق عليه. مفيد لجعل التطبيق متاحًا للأجهزة الأخرى على الشبكة. الافتراضي: 0.0.0.0
`--experimental-https`	يبدأ الخادم باستخدام HTTPS وينشئ شهادة موقعة ذاتيًا.
`--experimental-https-key <path>`	مسار إلى ملف مفتاح HTTPS.
`--experimental-https-cert <path>`	مسار إلى ملف شهادة HTTPS.
`--experimental-https-ca <path>`	مسار إلى ملف سلطة شهادة HTTPS.
`--experimental-upload-trace <traceUrl>`	يرسل مجموعة فرعية من تتبع التصحيح إلى عنوان URL بعيد.

خيارات `next build`

ينشئ next build بناءً مُحسّنًا للإنتاج لتطبيقك. يعرض المخرجات معلومات عن كل مسار. على سبيل المثال:

Terminal

المسار (app)                              الحجم     أول تحميل لـ JS
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB

○  (ثابت)   تم تقديمه مسبقًا كمحتوى ثابت
ƒ  (ديناميكي)  يتم تقديمه من الخادم عند الطلب

الحجم: حجم الأصول التي يتم تنزيلها عند التنقل إلى الصفحة من جانب العميل. حجم كل مسار يشمل فقط تبعياته.
أول تحميل لـ JS: حجم الأصول التي يتم تنزيلها عند زيارة الصفحة من الخادم. يتم عرض مقدار JS المشترك بين الجميع كمقياس منفصل.

كلا هذين القيمتين مضغوطتين باستخدام gzip. يُشار إلى أول تحميل باللون الأخضر أو الأصفر أو الأحمر. استهدف اللون الأخضر للحصول على تطبيقات عالية الأداء.

الخيارات التالية متاحة لأمر next build:

الخيار	الوصف
`-h, --help`	يعرض جميع الخيارات المتاحة.
`[directory]`	مجلد لبناء التطبيق فيه. إذا لم يتم توفيره، سيتم استخدام المجلد الحالي.
`-d` أو `--debug`	يمكّن مخرجات بناء أكثر تفصيلاً. مع تمكين هذا العلم، سيتم عرض مخرجات بناء إضافية مثل إعادة الكتابة، التوجيهات، والعناوين.

`--profile`	يمكّن تخصيص الأداء لـ React في الإنتاج.
`--no-lint`	يعطل فحص الأخطاء (linting).
`--no-mangling`	يعطل تشويه الأسماء. قد يؤثر هذا على الأداء ويجب استخدامه فقط لأغراض التصحيح.
`--experimental-app-only`	يبني فقط مسارات موجه التطبيق (App Router).
`--experimental-build-mode [mode]`	يستخدم وضع بناء تجريبي. (الاختيارات: "compile", "generate", الافتراضي: "default")

خيارات `next start`

يبدأ next start التطبيق في وضع الإنتاج. يجب تجميع التطبيق أولاً باستخدام next build.

الخيارات التالية متاحة لأمر next start:

الخيار	الوصف
`-h` أو `--help`	يعرض جميع الخيارات المتاحة.
`[directory]`	مجلد لبدء التطبيق منه. إذا لم يتم توفير مجلد، سيتم استخدام المجلد الحالي.
`-p` أو `--port <port>`	يحدد رقم المنفذ لبدء التطبيق عليه. (الافتراضي: 3000، متغير البيئة: PORT)
`-H` أو `--hostname <hostname>`	يحدد اسم المضيف لبدء التطبيق عليه (الافتراضي: 0.0.0.0).
`--keepAliveTimeout <keepAliveTimeout>`	يحدد الحد الأقصى للملي ثانية للانتظار قبل إغلاق الاتصالات غير النشطة.

يطبع next info تفاصيل ذات صلة عن النظام الحالي والتي يمكن استخدامها للإبلاغ عن أخطاء Next.js عند فتح مشكلة في GitHub. تتضمن هذه المعلومات نظام التشغيل (المنصة/الهيكل/الإصدار)، والثنائيات (Node.js، npm، Yarn، pnpm)، وإصدارات الحزم (next، react، react-dom)، والمزيد.

يجب أن تبدو المخرجات كالتالي:

Terminal

نظام التشغيل:
  المنصة: darwin
  الهيكل: arm64
  الإصدار: Darwin Kernel Version 23.6.0
  الذاكرة المتاحة (MB): 65536
  أنوية المعالج المتاحة: 10
الثنائيات:
  Node: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0
الحزم ذات الصلة:
  next: 15.0.0-canary.115 // يتم اكتشاف أحدث إصدار متاح (15.0.0-canary.115).
  eslint-config-next: 14.2.5
  react: 19.0.0-rc
  react-dom: 19.0.0
  typescript: 5.5.4
إعدادات Next.js:
  output: N/A

الخيارات التالية متاحة لأمر next info:

الخيار	الوصف
`-h` أو `--help`	يعرض جميع الخيارات المتاحة
`--verbose`	يجمع معلومات إضافية لأغراض التصحيح.

خيارات `next lint`

يشغل next lint ESLint لجميع الملفات في مجلدات pages/، app/، components/، lib/، و src/. كما يوفر إعدادًا موجهًا لتثبيت أي تبعيات مطلوبة إذا لم يكن ESLint مضبوطًا بالفعل في تطبيقك.

الخيارات التالية متاحة لأمر next lint:

الخيار	الوصف
`[directory]`	مجلد أساسي لفحص الأخطاء فيه. إذا لم يتم توفيره، سيتم استخدام المجلد الحالي.
`-d, --dir, <dirs...>`	يتضمن مجلد، أو مجلدات، لتشغيل ESLint عليها.
`--file, <files...>`	يتضمن ملف، أو ملفات، لتشغيل ESLint عليها.
`--ext, [exts...]`	يحدد امتدادات ملفات JavaScript. (الافتراضي: [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"])
`-c, --config, <config>`	يستخدم ملف التكوين هذا، متجاوزًا جميع خيارات التكوين الأخرى.
`--resolve-plugins-relative-to, <rprt>`	يحدد مجلدًا يجب حل الملحقات منه.
`--strict`	ينشئ ملف `.eslintrc.json` باستخدام التكوين الصارم لـ Next.js.
`--rulesdir, <rulesdir...>`	يستخدم قواعد إضافية من هذا المجلد (أو المجلدات).
`--fix`	يصحح مشاكل الفحص تلقائيًا.
`--fix-type <fixType>`	يحدد أنواع التصحيحات لتطبيقها (مثل: problem, suggestion, layout).
`--ignore-path <path>`	يحدد ملفًا لتجاهله.
`--no-ignore <path>`	يعطل خيار `--ignore-path`.
`--quiet`	يبلغ عن الأخطاء فقط.
`--max-warnings [maxWarnings]`	يحدد عدد التحذيرات قبل تشغيل رمز خروج غير صفري. (الافتراضي: -1)
`-o, --output-file, <outputFile>`	يحدد ملفًا لكتابة التقرير فيه.
`-f, --format, <format>`	يستخدم تنسيق مخرجات محدد.
`--no-inline-config`	يمنع التعليقات من تغيير التكوين أو القواعد.
`--report-unused-disable-directives-severity <level>`	يحدد مستوى الخطورة لتوجيهات eslint-disable غير المستخدمة. (الاختيارات: "error", "off", "warn")
`--no-cache`	يعطل التخزين المؤقت.
`--cache-location, <cacheLocation>`	يحدد موقعًا للتخزين المؤقت.
`--cache-strategy, [cacheStrategy]`	يحدد استراتيجية للكشف عن الملفات المتغيرة في التخزين المؤقت. (الافتراضي: "metadata")
`--error-on-unmatched-pattern`	يبلغ عن الأخطاء عندما لا تتطابق أنماط الملفات.
`-h, --help`	يعرض هذه الرسالة.

خيارات `next telemetry`

يجمع Next.js بيانات تتبع مجهولة بالكامل عن الاستخدام العام. المشاركة في هذا البرنامج المجهول اختيارية، ويمكنك الانسحاب إذا كنت تفضل عدم مشاركة المعلومات.

الخيارات التالية متاحة لأمر next telemetry:

الخيار	الوصف
`-h, --help`	يعرض جميع الخيارات المتاحة.
`--enable`	يمكّن جمع بيانات التتبع في Next.js.
`--disable`	يعطل جمع بيانات التتبع في Next.js.

تعلم المزيد عن بيانات التتبع.

أمثلة

تغيير المنفذ الافتراضي

بشكل افتراضي، يستخدم Next.js http://localhost:3000 أثناء التطوير ومع أمر next start. يمكن تغيير المنفذ الافتراضي باستخدام خيار -p، كما يلي:

Terminal

next dev -p 4000

أو باستخدام متغير البيئة PORT:

Terminal

PORT=4000 next dev

معلومة مفيدة: لا يمكن تعيين PORT في ملف .env لأن تشغيل خادم HTTP يحدث قبل تهيئة أي كود آخر.

استخدام HTTPS أثناء التطوير

لحالات استخدام معينة مثل webhooks أو المصادقة، قد يكون مطلوبًا استخدام HTTPS للحصول على بيئة آمنة على localhost. يمكن لـ Next.js إنشاء شهادة موقعة ذاتيًا باستخدام next dev مع علم --experimental-https:

Terminal

next dev --experimental-https

يمكنك أيضًا توفير شهادة ومفتاح مخصصين باستخدام --experimental-https-key و --experimental-https-cert. اختياريًا، يمكنك توفير شهادة CA مخصصة باستخدام --experimental-https-ca أيضًا.

Terminal

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-https مخصص للتطوير فقط وينشئ شهادة موثوقة محليًا باستخدام mkcert. في الإنتاج، استخدم شهادات صادرة بشكل صحيح من جهات موثوقة.

معلومة مفيدة: عند النشر على Vercel، يتم تكوين HTTPS تلقائيًا لتطبيق Next.js الخاص بك.

تكوين مهلة للوكلاء المتتالين (Downstream Proxies)

عند نشر Next.js خلف وكيل متتالي (مثل موازن حمل مثل AWS ELB/ALB)، من المهم تكوين خادم HTTP الأساسي لـ Next.js مع مهلات keep-alive تكون أكبر من مهلات الوكيل المتتالي. وإلا، بمجرد الوصول إلى مهلة keep-alive لاتصال TCP معين، سيقوم Node.js بإنهاء هذا الاتصال فورًا دون إخطار الوكيل المتتالي. هذا يؤدي إلى خطأ في الوكيل كلما حاول إعادة استخدام اتصال قام Node.js بإنهائه بالفعل.

لتكوين قيم المهلة لخادم Next.js في الإنتاج، مرر --keepAliveTimeout (بالميلي ثانية) إلى next start، كما يلي:

Terminal

next start --keepAliveTimeout 70000

تمرير وسائط Node.js

يمكنك تمرير أي وسائط Node.js إلى أوامر next. على سبيل المثال:

Terminal

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next

واجهة سطر الأوامر (CLI) في Next.js

مرجع

الأوامر

خيارات `next dev`

خيارات `next build`

خيارات `next start`

خيارات `next info`

خيارات `next lint`

خيارات `next telemetry`

أمثلة

تغيير المنفذ الافتراضي

استخدام HTTPS أثناء التطوير

تكوين مهلة للوكلاء المتتالين (Downstream Proxies)

تمرير وسائط Node.js

On this page