تكوين أمر البناء ودليل الإخراج الخاص بك

Getting Orbit to build your project correctly comes down to a handful of fields in Settings: install command, build command, output directory, root directory and Node.js version. Left blank they are…

تكوين أوامر البناء ودليل الإخراج الخاص بك

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

حيث يمكنك العثور على الإعدادات

افتح مشروعك في Orbit، وانتقل إلى علامة التبويب الإعدادات، وابحث عن بطاقة إعدادات البناء.

الحقل	ما يفعله	العنصر النائب عند تركه فارغاً
أمر التثبيت	كيفية تثبيت التبعيات قبل البناء	`npm ci (auto-detected)`
أمر البناء	الأمر الذي ينتج عنه الإخراج الخاص بك	`npm run build (auto-detected)`
دليل الإخراج	المجلد الذي ينشره Orbit بعد البناء	`dist (auto-detected)`
دليل الجذر	بالنسبة للمستودعات المتعددة، المجلد الفرعي الذي يحتوي على تطبيقك	`/ (monorepo subdirectory)`
إصدار Node.js	إصدار العقدة الرئيسي للبناء والتشغيل معه	الافتراضي للنظام الأساسي

اترك أي حقل فارغاً للسماح لـ Orbit بالكشف التلقائي. انقر على حفظ على بطاقة إعدادات البناء لتطبيق التغييرات.

بطاقة إعدادات البناء في إعدادات مشروع Orbit

تغيير إعداد البناء لا يغير النشر الذي يكون حالياً مباشراً. ينطبق الإعداد الجديد من النشر التالي. أعد النشر بعد الحفظ، وإلا لن يبدو أن أي شيء قد حدث.

إعدادات الإطار الافتراضية

Next.js

يحتوي Next.js على وضعين في Orbit، واختيار الوضع الخاطئ هو الخطأ الأكثر شيوعاً عند النشر الأول.

التصدير الثابت (output: 'export' في next.config.js):

أمر البناء: npm run build
دليل الإخراج: out
وضع الخادم: معطّل

وضع الخادم (SSR أو ISR)، وهو معظم تطبيقات Next.js:

قم بتشغيل وضع الخادم في الإعدادات، ضمن وقت التشغيل
أمر البناء: npm run build
دليل الإخراج: .next

بدون تفعيل وضع الخادم، يتم نشر تطبيق Next.js المعروض على الخادم كملفات ثابتة. سيتم تحميل الصفحة الرئيسية عادة وكل المسار الديناميكي سيعطي 404. إذا كان هذا هو الأعراض لديك، فهذا هو السبب: قم بتشغيل وضع الخادم وأعد النشر قبل تغيير أي شيء آخر.

Astro

مجلد إخراج Astro هو dist في كل وضع. ما يتغير هو ما إذا كنت بحاجة إلى وضع الخادم.

output: 'static'، الافتراضي: دليل الإخراج dist، وضع الخادم معطّل
output: 'server' أو output: 'hybrid': دليل الإخراج dist، وضع الخادم مشغّل
أمر البناء: npm run build، أو astro build

Vite (React و Vue و Svelte)

أمر البناء: npm run build، أو vite build
دليل الإخراج: dist

يكتب Vite دائماً إلى dist إلا إذا قمت بتجاوز build.outDir في vite.config.ts. إذا فعلت ذلك، فعيّن دليل الإخراج ليطابقه.

SvelteKit

أمر البناء: npm run build
دليل الإخراج: build

ما إذا كنت بحاجة إلى وضع الخادم يعتمد على محول الخاص بك: المحول الثابت لا يحتاج إلى ذلك، محول Node يحتاج إلى ذلك.

Nuxt 3

أمر البناء: npm run build
دليل الإخراج: .output
وضع الخادم: مشغّل

Remix

أمر البناء: npm run build
دليل الإخراج: build
وضع الخادم: مشغّل

Express أو واجهة برمجية عادية للعقدة

أمر البناء: npm run build
دليل الإخراج: dist
وضع الخادم: مشغّل

يقوم وضع الخادم بتشغيل npm start بعد البناء، لذا تأكد من أن start البرنامج النصي موجود ويبدأ الخادم.

Create React App

تم إهمال Create React App في المنبع وليس خياراً جيداً لمشروع جديد، لكن المشاريع الموجودة تُنشأ بشكل جيد.

أمر البناء: npm run build
دليل الإخراج: build

HTML عادي أو منشئ موقع ثابت

اترك أمر التثبيت فارغاً إذا لم يكن هناك package.json
اترك أمر البناء فارغاً لنشر المستودع كما هو، أو عيّن أمر منشئ الموقع الخاص بك
دليل الإخراج: . لجذر المستودع، أو أي مجلد يكتب فيه منشئ الموقع

إصدار Node.js

أدخل رقم الإصدار الرئيسي فقط: 18، 20 أو 22. تقول تلميح الحقل ذلك صراحة. أي شيء آخر، مثل 20.11.0 أو v20، ليس ما يتوقعه هذا الحقل.

ينطبق الإصدار على البناء وعند تشغيل وضع الخادم على وقت التشغيل أيضاً.

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

المستودعات المتعددة

عيّن دليل الجذر إلى مسار تطبيقك، على سبيل المثال apps/web. يتغير Orbit إلى هذا المجلد قبل تشغيل أوامر التثبيت والبناء، ثم يكون دليل الإخراج نسبياً إليه.

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

يمكن لكل بيئة تجاوز دليل الجذر بشكل مستقل، ضمن Staging: build overrides في الإعدادات، وهو مفيد عندما ينشئ الإنتاج في بيئة العمل بيئة عمل مختلفة.

تجاوزات الإنتاج المرحلي

إذا كان لمشروعك بيئة إنتاج مرحلية، يعرض الإعدادات قسم Staging: build overrides بنفس الحقول. أي حقل يُترك فارغاً هناك يرث القيمة على مستوى المشروع، لذا يمكنك تغيير أمر البناء فقط للإنتاج المرحلي، على سبيل المثال إلى npm run build:staging، وترك كل شيء آخر وحده.

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

ذاكرة التخزين المؤقت للبناء

يخزن Orbit node_modules مؤقتاً بين البناء على خطط Liftoff و Apex. تعرض صفحة تفاصيل النشر Cache hit أو Cold build، جنباً إلى جنب مع مدة مرحلة التثبيت، لذا يمكنك رؤية ما تستحقه ذاكرة التخزين المؤقت على مشروعك.

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

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

الأخطاء الشائعة

"نجح البناء لكن الموقع يعرض 404." دليل الإخراج خاطئ: نشر Orbit مجلداً ليس إخراج البناء الخاص بك. تحقق من المجلد الذي ينشئه البناء بالفعل. يكتب Vite إلى dist، يكتب التصدير الثابت Next.js out، يستخدم وضع خادم Next.js .next، يكتب Create React App و Remix build، يكتب Nuxt .output.

"404 فقط على المسارات الديناميكية، الصفحة الرئيسية جيدة." وضع الخادم معطّل على تطبيق يحتاجه. انظر قسم Next.js أعلاه.

"Module not found" في النشر الأول. إما أن خطوة التثبيت لم تشتغل، أو تشغلت مع مدير حزم مختلف عن الذي تستخدمه محلياً. عيّن أمر التثبيت صراحة: npm ci، yarn install --frozen-lockfile، أو pnpm install --frozen-lockfile. تحقق أيضاً من أنك التزمت بملف قفل واحد بالضبط: إذا كان كلا من package-lock.json و yarn.lock في المستودع، فقد لا يكون مدير الحزم المكتشف هو الذي تتوقعه.

"Lockfile قديم." npm ci وتجميد معادلات ملف القفل ترفض التشغيل عندما يكون ملف القفل غير متفق مع package.json. شغّل مثبت مدير الحزم محلياً والتزم ملف القفل المُعاد تشغيله. هذا هو الفشل الأكثر شيوعاً عند النشر الأول ولا يتكرر أبداً محلياً، وهو بالضبط السبب في أنه محير.

"تطبيق واحد فقط من monorepo الخاص بي يتم نشره." هذا هو دليل الجذر يقوم بعمله. يحتاج كل تطبيق إلى مشروع Orbit خاص به بدليل جذر خاص به.

"إصدار Node.js خاطئ." عيّن حقل إصدار Node.js إلى رقم الإصدار الرئيسي فقط.

يستنزف البناء الذاكرة أو يملأ القرص. كلاهما حدود الخطة على آلة البناء: يحصل Launch على 1 vCPU و 1 GB RAM و 4 GB قرص؛ Liftoff يحصل على 2 و 2 GB و 8 GB؛ Apex يحصل على 4 و 4 GB و 16 GB. إضافة NODE_OPTIONS=--max-old-space-size=2048 كمتغير بيئة تساعد فقط حتى RAM الفعلية للآلة. انظر Orbit Plan Limits.