استكشاف أخطاء البناءات الفاشلة

When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…

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

قراءة الفشل

افتح مشروعك في Kapsule Orbit.
افتح علامة التبويب النشرات.
انقر على النشرة التي تحمل حالة فشل.
اقرأ ملخص الفشل فوق السجل أولاً، ثم السجل نفسه.

النشرة الفاشلة تعرض ملخص الفشل المصنف

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

يوجد أيضاً زر الحصول على تشخيص ذكي. يقرأ آخر 120 سطر من السجل جنباً إلى جنب مع إطار العمل المكتشف وفئة الفشل ويعيد شرحاً بلغة عادية.

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

إذا لم يبدأ البناء قط وعلق على قيد الانتظار، انتقل إلى قسم البناءات قيد الانتظار أدناه.

الأعطال التي يتعرف عليها Kapsule Orbit بالاسم

تأتي هذه مع إصلاح محدد مقترح على صفحة النشرة.

ما يكتشفه Kapsule Orbit	ماذا يعني	الإصلاح
وحدة مفقودة	يشير الاستيراد إلى حزمة غير مثبتة	أضف الحزمة إلى `package.json` وقم بالعمل على الإصدار، أو أصلح الخطأ في مسار الاستيراد
`ERESOLVE` تضارب	لا يمكن لـ npm إرضاء اعتماد من نظير	حل التضارب في `package.json`، أو أضف `--legacy-peer-deps` إلى أمر التثبيت الخاص بك في الإعدادات
خطأ TypeScript	فشل التحقق من النوع أثناء البناء	أصلح الأخطاء المدرجة. بالنسبة لمشاكل النوع من جهات خارجية، `skipLibCheck: true` في `tsconfig.json`
نفاد الذاكرة	تجاوز البناء ذاكرة RAM الخاصة بآلة البناء	أضف `NODE_OPTIONS=--max-old-space-size=2048` كمتغير بيئي، أو انتقل إلى خطة بآلة بناء أكبر
امتلاء قرص البناء	ملأ البناء قرصه	ابحث عن `node_modules` أو قطعة أثرية كبيرة بشكل غير متوقع، أو انتقل إلى خطة بقرص بناء أكبر
انتهت مهلة البناء الزمنية	وصل البناء إلى إجهاض المدة 30 دقيقة	فعّل ذاكرة التخزين المؤقت للبناء، وقلل حجم الحزمة، أو ابحث عما يعلق
لم تُعثر على الحزمة (404)	لا توجد تبعية بهذا الاسم أو الإصدار	تحقق من `package.json` بحثاً عن خطأ إملائي، أو أكد أن الحزمة منشورة
أخطاء ESLint	أخطاء التحقق من الأسلوب أوقفت البناء	أصلحها، أو توقف عن جعل التحقق من الأسلوب يفشل في بناء إطار العمل الخاص بك
خطأ في بناء الجملة	مصدر غير قابل للتحليل	قوس مفقود، أو سلسلة غير مغلقة، أو بناء جملة لا يدعمه إصدار Node الخاص بك
لم يتم العثور على الملف	الملف المشار إليه غير موجود في المستودع	أكد أنه تم العمل عليه، وتحقق من حالة المسار
الملف المقفول قديم	الملف المقفول لا يطابق `package.json`	قم بتشغيل تثبيت مدير الحزم محلياً وألزم الملف المقفول المحدث

عدم تطابق الملف المقفول هو أكثر أعطال النشر الأول شيوعاً وأكثرها إرباكاً، لأنه لا يحدث أبداً محلياً. npm ci و yarn install --frozen-lockfile و pnpm install --frozen-lockfile جميعها ترفض المتابعة عندما لا يتفق الملف المقفول مع package.json. أعد إنشاء الملف المقفول محلياً والزم به.

الأعطال الشائعة حسب المرحلة

فشل تثبيت التبعية

حدث خطأ في مرحلة التثبيت.

مدير حزم خاطئ. يختار Kapsule Orbit npm أو yarn أو pnpm من ملفك المقفول. إذا تم العمل على أكثر من ملف مقفول واحد، قد لا يكون الاختيار هو الذي تتوقعه. احذف الملفات التي لا تستخدمها، أو عيّن أمر التثبيت بشكل صريح في الإعدادات.
السجل الخاص. إذا جاءت تبعية من سجل خاص، يجب أن يكون رمز المصادقة متاحاً في وقت البناء كمتغير بيئي، و .npmrc الخاص بك يجب أن يشير إليه.
عدم تطابق إصدار Node.js. بعض الحزم تتطلب إصدار Node بحد أدنى. عيّن إصدار Node.js في الإعدادات إلى رقم الإصدار الرئيسي: 18 أو 20 أو 22.
نفاد الذاكرة على أحادي مستودع كبير. استخدم npm ci بدلاً من npm install، واعتبر خطة بآلة بناء أكبر.

فشل أمر البناء

حدث خطأ في مرحلة البناء.

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

انتهاء مهلة البناء الزمنية

يتم إجهاض البناء عند 30 دقيقة من وقت الجدار على كل خطة. إذا كان الخاص بك يقترب باستمرار من ذلك:

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

البناء لا يبدأ أبداً

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

يمكنك رؤية كل شيء قيد الطيران عبر حسابك في Kapsule Orbit، ثم Queue.

إذا بقيت النشرة قيد الانتظار مع عدم تشغيل أي شيء آخر، فمن المرجح أن يتم احتجازها بدلاً من الانتظار. تحقق من:

في انتظار الموافقة، إذا كان اطلب الموافقة على الإنتاج مفعلاً
قفل النشر على المشروع
جدول تجميد النشر يحجب الوقت أو اليوم الحالي
فحوصات CI المطلوبة في انتظار خط الأنابيب الخاص بك
اطلب نجاح التصريح قبل الإنتاج في انتظار نشر التصريح من الإلزام نفسه

تم تخطي البناء بالكامل

إذا لم ينتج عن الدفع أي نشرة على الإطلاق، فمن المحتمل أنه تم تصفيته عن قصد:

المسارات المتجاهلة: كل ملف في الدفع يطابق نمطاً مثل *.md أو docs/**
أنماط تجاهل الفرع: يطابق الفرع شيئاً مثل dependabot/*
مجلد الجذر: لم يلمس أي شيء في الدفع مجلد أحادي المستودع الفرعي لهذا المشروع
معاينات الفرع مغلقة، والدفع لم يكن للإنتاج أو التصريح

البناء نجح لكن الموقع خاطئ

البناء الأخضر والموقع المعطل هو دائماً مشكلة إعدادات وليس مشكلة أكواد.

404 على كل صفحة. مجلد الإخراج خاطئ: Kapsule Orbit نشر مجلداً ليس إخراج البناء الخاص بك. تحقق من ما ينشره البناء فعلاً. القيم الشائعة هي dist و .next و out و build و .output.

404 فقط على المسارات الديناميكية. التطبيق يحتاج إلى خادم قيد التشغيل ويتم خدمته كملفات ثابتة. فعّل وضع الخادم في الإعدادات ضمن وقت التشغيل. هذا مطلوب لـ Next.js مع SSR و Remix و Nuxt وأي شيء آخر ليس تصديراً ثابتاً.

404 للأصول بعد النشر، للمستخدمين الموجودين بالفعل على الموقع. لقد حملوا الصفحة القديمة ويطلبون عناوين URL حزمة قديمة لم تعد موجودة. فعّل حماية الانحراف في الإعدادات، والتي تحافظ على الأصول الخاصة بالبناء السابق متاحة لفترة احتفاظ بعد نشرة جديدة تصبح مباشرة.

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

إعدادات البناء حسب الإطار في تكوين أمر البناء ومجلد الإخراج الخاص بك.

إعادة المحاولة

على صفحة النشرة الفاشلة:

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

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

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

إيقاف بناء سيء من الوصول إلى المستخدمين

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

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

يمكنك أيضاً جعل Kapsule Orbit تفعل ذلك تلقائياً: التراجع التلقائي عند الفشل يستعيد آخر نشرة صحية عندما تفشل نشرة الإنتاج، و مسار فحص الصحة يستعيده عندما لا تجيب النشرة الجديدة برمز 2xx خلال 15 ثانية.

لا تزال عالقاً

إذا انتهى السجل ببساطة بدون رسالة خطأ، فمن المحتمل أن تكون عملية البناء قد تم قتلها: نفاد الذاكرة، أو تمت إعادة احتلال آلة البناء. أعد المحاولة مرة واحدة. إذا فشلت بنفس الطريقة مرتين، افتح تذكرة من KPanel أو أرسل بريداً إلى support@kapsulehost.com وأرفق معرّف النشرة المعروض على صفحة التفاصيل.