نظرة عامة على استكشاف الأخطاء: عند حدوث مشكلة ابدأ بهذه الصفحة (فحص سريع خلال 60 ثانية)
عند ظهور خطأ في ComfyUI، لا تتعجل بالبحث عن نص الخطأ. يمكن تصنيف معظم أخطاء ComfyUI خلال 60 ثانية ضمن أربع فئات: البيئة والتشغيل، وتحميل النماذج، وذاكرة VRAM والتوليد، والعُقد المخصصة. تساعدك هذه الصفحة على إجراء فحص سريع أولي، وتحديد فئة المشكلة، ثم الانتقال إلى الصفحة المتخصصة المقابلة للمعالجة المتعمقة.
ماذا ستستطيع أن تفعل بعد التعلم
- التأكد خلال 60 ثانية باستخدام 3 أوامر من أن بيئة GPU و CUDA و Python تعمل بشكل طبيعي
- تصنيف الأخطاء ضمن فئات «البيئة / النماذج / الذاكرة / العُقد» بدلًا من البحث العشوائي
- مطابقة نصوص الأخطاء عالية التكرار وتطبيق الحلول المُتحقق منها مباشرة
- معرفة المعلومات التي يجب جمعها وأين تطرح سؤالك عندما تدرك أنك لا تستطيع الحل بنفسك
الفحص الأول: فحص سريع خلال 60 ثانية
أول شيء تفعله عند حدوث مشكلة: ارجع إلى نافذة الطرفية التي شغّلت ComfyUI واقرأ السجل. عند فشل التوليد ستظهر الواجهة مربع حوار «Prompt execution failed»، وبالنقر على «Show report» يمكنك رؤية معلومات الخطأ التفصيلية — انسخها أولًا.
ثم نفّذ هذه الأوامر الثلاثة في الطرفية لإجراء فحص للبيئة:
# 1. 确认 GPU 能被系统识别(NVIDIA 显卡)
nvidia-smi
# 2. 确认 PyTorch 的 CUDA 可用
python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
# 3. 确认 Python 版本(需 3.9+,推荐 3.12)
python --versionينبغي أن ترى: الأمر رقم 1 يسرد طراز بطاقة الرسومات وإصدار برنامج التشغيل؛ والأمر رقم 2 يُخرج CUDA available: True؛ والأمر رقم 3 يُخرج رقم إصدار 3.9 أو أحدث. إذا لم يستوفِ أي أمر التوقعات، انتقل أولًا إلى ماذا تفعل إذا فشل التثبيت: استكشاف أخطاء التثبيت والتشغيل وإصلاحها.
💡 استبعد العُقد المخصصة أولًا
من بين بلاغات المشكلات التي يتلقاها الفريق الرسمي، يرتبط معظمها بالعُقد المخصصة. قبل الاستكشاف المتعمق، عطّل جميع العُقد المخصصة أولًا وفقًا لطريقة استكشاف أخطاء العُقد المخصصة: عطّل أولًا ثم استخدم التنصيف الثنائي، للتأكد مما إذا كانت المشكلة ناتجة عن العُقد.
استكشاف المشكلات الشائعة وإصلاحها
أخطاء تتعلق بالبيئة والتشغيل في ComfyUI
"Torch not compiled with CUDA enabled"
السبب: إصدار PyTorch المثبت هو إصدار CPU، بدون دعم CUDA مُصرَّح، لذا لا يمكن لـ GPU المشاركة في الحساب.
الحل:
- أزل نسخة torch الموجودة أولًا:
pip uninstall torch- أعد تثبيت إصدار PyTorch المتوافق مع CUDA (CUDA 13.0):
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130- تحقق من التثبيت:
python -c "import torch; print(torch.cuda.is_available())"ينبغي أن ترى: الناتج True.
"Frontend or Templates Package Not Updated"
السبب: بعد تحديث ComfyUI عبر Git، لم تُحدَّث تبعيات الواجهة الأمامية بالتزامن.
الحل:
pip install -r requirements.txtينبغي أن ترى: بعد اكتمال تثبيت التبعيات، أعد تشغيل ComfyUI وستختفي الرسالة.
مشكلات تتعلق بتحميل النماذج
"Value not in list: ckpt_name: 'model-name.safetensors' not in []"
السبب: ملف النموذج المُشار إليه في سير العمل غير موجود — إما لم يُنزَّل، أو وُضع في دليل فرعي خاطئ. القائمة الفارغة في not in [] تعني أن ComfyUI لم يعثر على أي نموذج في الدليل المقابل.
الحل:
- تحقق من أن النموذج موضوع في الدليل الفرعي الصحيح:
- Checkpoints:
models/checkpoints/ - VAE:
models/vae/ - LoRA:
models/loras/ - ControlNet:
models/controlnet/
- Checkpoints:
- إذا كان النموذج مفقودًا، استخدم ComfyUI Manager لتنزيله تلقائيًا، أو نزّله يدويًا وضعه في الدليل المقابل.
- إذا كانت النماذج في مكان آخر (مثل مشاركتها مع برامج رسم أخرى)، حرّر
extra_model_paths.yamlلإضافة دليل نماذج مخصص، راجع تثبيت الحزمة المحمولة لـ Windows.
ينبغي أن ترى: بعد إعادة تشغيل ComfyUI، يمكنك اختيار النموذج في القائمة المنسدلة للعقدة.
"Error while deserializing header"
السبب: ملف النموذج تالف أثناء التنزيل، أو مساحة القرص غير كافية، أو أذونات الملف غير صحيحة مما يمنع قراءته.
الحل:
- أعد تنزيل النموذج (قد يزيد حجم ملف النموذج عن 2–15GB، تأكد من اكتمال التنزيل).
- تحقق من أن مساحة القرص المتبقية كافية.
- تحقق من أن عملية ComfyUI تملك صلاحية القراءة لملف النموذج.
- جرّب نموذجًا آخر للتأكد مما إذا كانت المشكلة في ملف واحد أم مشكلة شاملة.
أخطاء تتعلق بذاكرة VRAM والتوليد في ComfyUI
"RuntimeError: CUDA out of memory"
السبب: ذاكرة VRAM غير كافية لاستيعاب النموذج الحالي وسير العمل، وهو أمر شائع مع النماذج الكبيرة أو التوليد بدقة عالية.
الحل: قلّل استهلاك ذاكرة VRAM تدريجيًا وبالترتيب، وأعد تشغيل ComfyUI بعد كل تعديل:
# 方案 1:先用 lowvram(文本编码器放到 CPU)
python main.py --lowvram
# 方案 2:不够再换 novram
python main.py --novram
# 方案 3:最后手段,纯 CPU(很慢,仅绝对必要时使用)
python main.py --cpuيمكنك أيضًا تقليل دقة التوليد أو حجم الدفعة، وإغلاق البرامج الأخرى التي تستهلك ذاكرة VRAM. لمزيد من الحلول الشاملة راجع نقص ذاكرة VRAM والتقطيب: حلول شاملة لمشكلة OOM.
ينبغي أن ترى: اكتمال عملية التوليد دون انقطاع أو خطأ.
"نتيجة التوليد سوداء بالكامل أو بلون واحد صافٍ"
السبب: حدثت مشكلة في مرحلة الإخراج. تشمل الأسباب الموثقة: خلل في مرحلة VAE (خط النص إلى صورة الافتراضي هو KSampler → VAE Decode → Save Image، وتحميل VAE غير الصحيح يؤثر مباشرة على الإخراج)؛ معامل تشغيل --fp16-vae الذي يشغّل VAE بدقة fp16 قد يؤدي إلى صور سوداء؛ كما قد تُرجع الواجهة الخلفية للانتباه على النماذج المكمَّمة ناتجًا أسود بصمت.
الحل:
- تحقق من سير العمل: تأكد من أن ما يلي KSampler هو VAE Decode، وأن الـ VAE المحمَّل يطابق بنية النموذج (مثلاً يتطلب Flux استخدام
ae.safetensors، ولا يمكن استخدام sdxl_vae أو taesd). - إذا أضفت
--fp16-vaeعند التشغيل، احذف هذه المعلمة وأعد التشغيل. - إذا كان FlashAttention مفعّلاً (
--use-flash-attentionأو مفعّلاً عبر حزمة العقد)، بدّل إلى واجهة الانتباه الافتراضية وأعد التشغيل ثم أعد المحاولة — لقد ثبت أن تعطيل FlashAttention على النماذج المكمَّمة يحل مشكلة الإخراج الأسود بالكامل. - أغلق المعاينة الفورية لاستبعاد هذا العامل: في بعض الحالات تكون المعاينة فقط هي السوداء بينما الملف المحفوظ سليم في الواقع.
المفترض أن ترى: صورة طبيعية في الإخراج بعد إعادة التوليد.
المشكلات المتعلقة بالعقد المخصصة
"Can't Find Custom Node" (تعذّر العثور على العقدة المخصصة)
السبب: العقدة المخصصة المستخدمة في سير العمل غير مثبتة أو غير مفعّلة بشكل صحيح، فيبلغ التحقق في الواجهة الأمامية عن خطأ.
الحل:
- عطّل التحقق من العقد مؤقتاً في إعدادات ComfyUI أولاً لتحديد نطاق المشكلة.
- ثبّت حزمة العقد المطابقة وفقاً للتنبيه ثم أعد التشغيل.
- إذا استمرت المشكلة، اتبع مسار استكشاف أخطاء العقد المخصصة وإصلاحها: التعطيل أولاً ثم التقسيم الثنائي لتعطيل جميع العقد ثم تحديد المصدر بالتقسيم الثنائي.
"Missing nodes still showing as missing after installation and restart"
السبب: حزمة العقد مثبتة لكن فشل استيراد التبعيات — من الشائع ظهور «Failed to import» في الطرفية/السجلات. الأسباب النموذجية: حزمة العقد تتطلب تبعيات wheel إضافية؛ تعارض متطلبات إصدارات التبعيات بين إضافات مختلفة (مثلاً واحدة تتطلب torch==2.4.1 وأخرى تتطلب torch>=2.4.2)؛ مشكلات الشبكة تمنع تثبيت التبعيات.
الحل:
- افتح سجلات الطرفية، واعثر على اسم حزمة العقد المقابل لرسالة «Failed to import».
- ثبّت يدوياً التبعيات الناقصة لحزمة العقد تلك.
- عند تعارض إصدارات التبعيات، ارجع إلى طرق إدارة بيئة Python في صفحة استكشاف أخطاء العقد المخصصة لإصلاحها.
ما زال لا يعمل؟
اجمع هذه المعلومات قبل طرح سؤالك، فهذا يرفع كفاءة الحل بشكل كبير:
# GPU 型号与驱动版本
nvidia-smi --query-gpu=driver_version --format=csv
# CUDA 是否可用及版本
python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"
# Python 版本
python --versionأرفق عند السؤال: نص رسالة الخطأ الكامل (سجلات الطرفية أو محتوى «Show report»)، وطراز GPU، وإصدار ComfyUI، وطريقة التثبيت (نسخة سطح المكتب / النسخة المحمولة / التثبيت اليدوي)، وما إذا كنت تستخدم عقداً مخصصة.
إلى أين تتوجه للسؤال:
- مشكلات العقد المخصصة: ابدأ بـ استكشاف أخطاء العقد المخصصة وإصلاحها: التعطيل أولاً ثم التقسيم الثنائي
- مشكلات التثبيت والتشغيل: ماذا تفعل إذا فشل التثبيت: استكشاف أخطاء التثبيت والتشغيل وإصلاحها
- الإبلاغ عن خطأ للجهة الرسمية: بعد التأكد من أنه ليس ناتجاً عن عقدة مخصصة، أرسل GitHub issue مرفقاً به المعلومات أعلاه
استعراض الدرس التالي
هذه الصفحة تساعدك في تصنيف أخطاء ComfyUI ضمن أربع فئات رئيسية. الدرس التالي يتعمق في الفئة الأكثر تكراراً: استكشاف أخطاء العقد المخصصة وإصلاحها: التعطيل أولاً ثم التقسيم الثنائي، حيث يعلّمك استخدام التقسيم الثنائي لتحديد العقدة المسببة للمشكلة بسرعة.