Skip to content

ماذا تفعل إذا فشل التثبيت: استكشاف أخطاء التثبيت والإقلاع وإصلاحها ​

أكثر لحظة إحباطًا عند تثبيت ComfyUI ليست بطء التنزيل، بل ما بعد اكتمال التثبيت: تنقر نقرًا مزدوجًا على .bat فتومض النافذة السوداء وتختفي، أو يبدأ الخدمة لكن المتصفح يعرض صفحة فارغة تمامًا. إذا لم يفتح ComfyUI، فالغالب أن المشكلة عالقة في ثلاث نقاط — بيئة كرت الشاشة غير صحيحة، أو الخدمة لم تبدأ فعلًا، أو المشكلة في المتصفح. في هذا الدرس نأخذ أخطاء مرحلتي التثبيت والإقلاع الشائعة واحدًا واحدًا حسب «النص الأصلي» مع السبب والحل: أولًا فحص سريع في 60 ثانية لتحديد المرحلة، ثم طابِق حالتك مع الخطأ المناسب.

الحلول والأوامر كلها مأخوذة من وثائق استكشاف الأخطاء الرسمية وسكربتات الحزمة المحمولة الرسمية والمستودع الرسمي؛ نصوص الأخطاء مأخوذة من الوثائق الرسمية أو من عناوين المشكلات العامة في مستودع ComfyUI الرسمي على GitHub. أخطاء مرحلة توليد الصور (العقد الحمراء، نقص ذاكرة كرت الشاشة) خارج نطاق هذا الدرس، راجع استكشاف الأخطاء الشامل.

ماذا ستستطيع أن تفعل بعد إكمال الدرس ​

  • تحديد أي حلقة بها المشكلة — كرت الشاشة أم PyTorch أم Python — باستخدام 4 أوامر في 60 ثانية
  • مطابقة فشل إقلاع ComfyUI مع حالته: نافذة سوداء تومض وتختفي، أخطاء CUDA، مكتبات مفقودة في Linux — سبب كل منها وطريقة إصلاحه
  • حل ثلاث مشكلات واجهة تمنع فتح ComfyUI: تعذر الاتصال بـ 127.0.0.1:8188، شاشة بيضاء أو مشوهة، شاشة سوداء وانهيار
  • معالجة عدم إقلاع النسخة المكتبية: حجب أمني، حلقة تحديث، كرت شاشة غير مدعوم، وكيفية العثور على ملف السجل الرسمي app.log
  • تعلّم الطريقة الرسمية لطرح الأسئلة: خذ معك عناصر معلومات النظام الستة ونص الخطأ الكامل قبل الذهاب إلى GitHub Issues

مأزقك الحالي ​

  • تنقر نقرًا مزدوجًا على .bat، فتومض النافذة السوداء وتختفي دون أن تتمكن حتى من قراءة الخطأ، ويفشل إقلاع ComfyUI دون أي دليل
  • النافذة السوداء تعرض كومة من السجلات بوضوح، لكن المتصفح لا يفتح 127.0.0.1:8188، أو تكون الواجهة سوداء تارة وبيضاء تارة أخرى
  • سلسلة خطأ بالإنجليزية (Torch not compiled with CUDA enabled؟)، تنسخها وتبحث عنها فتجد إجابات شتى ومتناقضة

متى تستخدم هذه الطريقة ​

عندما تحتاج إلى:

  • إصلاح مشكلات التثبيت والإقلاع العالقة في التثبيت: الحزمة المحمولة لـ Windows أو الطرق البديلة
  • تحديد المشكلة بنفسك قبل النشر وطلب المساعدة: هل الملفات لم تثبّت بشكل صحيح، أم البيئة غير مناسبة، أم الخدمة لم تبدأ، أم أن الذنب على المتصفح

ولا تريد:

  • اللجوء إلى المنتديات وانتظار الردود عند كل خطأ — الفحص السريع في 60 ثانية يوفر معظم هذه الذهابات والإيابات
  • أن تحكم خطأً على «المتصفح يحتاج إلى تحديث» بأنه «ComfyUI لم يثبّت بشكل صحيح» فتعيد التثبيت عبثًا

🎒 الاستعداد قبل البدء ​

  • أن تكون قد مررت بـ التثبيت: الحزمة المحمولة لـ Windows أو الطرق البديلة (لا مشكلة إن علقت، فهذا الدرس مخصص لحل العلق)
  • أن تستطيع العثور على نافذة سطر الأوامر السوداء التي تقلع ComfyUI (الحزمة المحمولة / التثبيت اليدوي) أو تطبيق Comfy Desktop (النسخة المكتبية)
  • مستخدمو النسخة المكتبية: تعرف أن قائمة ☰ في الزاوية العلوية اليسرى تفتح Desktop Settings
  • كوب من الماء ☕

💡 مستخدمو النسخة المكتبية انظروا هنا

يتولى Comfy Desktop إدارة بيئة Python والتبعيات، لذا يناسب استكشاف أخطاء Python / pip في هذه الصفحة بشكل أساسي مستخدمي الحزمة المحمولة والتثبيت اليدوي. إذا لم تقلع النسخة المكتبية فراجع أولًا المجموعة رقم 4؛ وللحصول على السجلات انتقل مباشرة إلى «ما زال لا يعمل؟» — موقع app.log الرسمي موجود هناك.

الفكرة الأساسية ​

**ComfyUI ذو بنية من طبقتين: «خدمة محلية + واجهة ويب». **نافذة سطر الأوامر السوداء (أو النسخة التي يطلقها Comfy Desktop) هي الخدمة نفسها، بينما الوصول عبر المتصفح إلى http://127.0.0.1:8188 هو مجرد عرض لصفحتها. لذا يجب تفكيك «عدم فتح ComfyUI» إلى سؤالين: هل بدأت الخدمة؟ وهل يستطيع المتصفح الاتصال؟ — في استكشاف الأخطاء ابدأ بالطبقات أولًا، ثم انظر إلى نص الخطأ.

أعراضكفي أي طبقة عالقةإلى أي مجموعة تذهب
7z فشل فك الضغط أو توقف التنزيلالملفات لم تصل بعدالمجموعة 5
النافذة السوداء تظهر وتختفي في لحظة / الخروج مع خطأالخدمة لا تعمل (التعريفات، PyTorch)المجموعتان 1 و3
النافذة موجودة لكن السطر To see the GUI لا يظهر أبدًاانقطاع في بدء تشغيل الخدمةالمجموعة 1
يوجد سطر To see the GUI لكن المتصفح لا يفتحبين الخدمة والمتصفحالمجموعة 2
الواجهة بيضاء أو مشوهة أو سوداءالواجهة الأمامية / المتصفحالمجموعة 2
نسخة سطح المكتب لا تفتح أو تخرج تلقائيًا بعد التحديثتطبيق سطح المكتب نفسهالمجموعة 4

الخطوتان الأوليان «الشاملتان» اللتان توصي بهما الجهة الرسمية. أول إصلاحين سريعين يذكرهما مستند استكشاف الأخطاء الرسمي لحالة «ComfyUI لا يعمل» هما: التحقق من الحد الأدنى من متطلبات النظام، وتحديث تعريف GPU إلى أحدث إصدار. ويقول ملف README للحزمة المحمولة الرسمية جملة صريحة: إذا لم يعمل، فحدّث تعريف NVIDIA لديك. قم بهذين الأمرين أولًا، فهما يقضيان على أكثر من نصف أخطاء فترة التثبيت.

نص رسالة الخطأ هو أفضل كلمة بحث. الأسطر الأخيرة في النافذة السوداء، أو المقطع الأخير في app.log، هي النص الذي تحتاجه — قارنه بعناوين H4 أدناه، أو انسخه مباشرة وابحث به في GitHub Issues.

الفحص الأول: فحص سريع في 60 ثانية ​

نفّذ الأوامر الأربعة بالترتيب (في الطرفية / سطر الأوامر). ملاحظة لمستخدمي الحزمة المحمولة: بايثون المضمّن ليس في متغير PATH الخاص بالنظام، لذا استبدل python في الأوامر بـ .\python_embeded\python.exe (أولًا نفّذ cd للدخول إلى مجلد ComfyUI_windows_portable)، وقد وُضع مثال في التعليقات.

bash
# 1. NVIDIA 显卡被识别吗?——应该看到显卡型号和驱动版本(AMD / Intel / Apple Silicon 用户跳过)
nvidia-smi

# 2. PyTorch 认得你的 GPU 吗?——应该看到 True
python -c "import torch; print(torch.cuda.is_available())"
#    Windows 便携包用户改用下面这条
#    .\python_embeded\python.exe -c "import torch; print(torch.cuda.is_available())"

# 3. 版本号(报 bug 时官方要这两项)
python -c "import torch; print(torch.__version__)"
python --version
#    便携包用户同上替换 python;官方便携包当前自带 Python 3.13 与 CUDA 13.0 版 PyTorch

ما يجب أن تراه: الأمر 1 يطبع جدول معلومات بطاقة الرسوميات؛ الأمر 2 يطبع True؛ الأمر 3 يطبع رقمي إصدار PyTorch و Python.

أصلح من النقطة التي انقطعت عندها: الأمر 1 يُظهر خطأ أو «الأمر غير موجود» → مشكلة تعريفات (المجموعة 3)؛ الأمر 2 يطبع False → بيئة PyTorch (المجموعة 3)؛ كلا الأمرين طبيعيان لكن الخدمة لا تعمل → المجموعة 1؛ الخدمة طبيعية لكن الواجهة لا تفتح → المجموعة 2.

استكشاف المشكلات الشائعة ​

فشل بدء التشغيل: البرنامج لا يعمل (فشل بدء ComfyUI) ​

بعد النقر المزدوج على .bat تظهر النافذة السوداء وتختفي في لحظة، وComfyUI لم يعمل ​

السبب: فشل سكربت بدء التشغيل في تشغيل ComfyUI — والسبب الأكثر شيوعًا هو قدم تعريف بطاقة الرسوميات أو نقص مكتبات التشغيل. كتبت الجهة الرسمية داخل run_nvidia_gpu.bat فقرة تنبيه مباشرة، ونصها الأصلي:

text
If you see this and ComfyUI did not start try updating your Nvidia Drivers to the latest.
If you get a c10.dll error you need to install vc redist that you can find: https://aka.ms/vc14/vc_redist.x64.exe

الحل:

  1. حدّث أولًا تعريف NVIDIA إلى أحدث إصدار (نص README للحزمة المحمولة الرسمية: Update your Nvidia drivers if it doesn't start)، ثم انقر نقرًا مزدوجًا على .bat
  2. عند ظهور خطأ c10.dll: ثبّت مكتبات تشغيل VC++ من مايكروسوفت، والعنوان الرسمي هو https://aka.ms/vc14/vc_redist.x64.exe، وبعد التثبيت أعد المحاولة
  3. تحقق من صحة الحزمة التي نزّلتها: بطاقات RTX من سلسلة 20 فأحدث يجب أن تستخدم الحزمة القياسية، وحزمة cu126 مخصصة فقط لبطاقات GTX من سلسلة 10 فأقدم (انظر المجموعة 5 «تنزيل حزمة التثبيت الخاطئة»)
  4. إذا لم ينجح ذلك: انقر نقرًا مزدوجًا على run_cpu.bat وجرّب وضع CPU مرة واحدة — توضح الجهة الرسمية أن وضع CPU يعمل على أي عتاد، لكنه بطيء جدًا (تصنّفه الجهة الرسمية كملاذ أخير فقط، ونستخدمه هنا للتحقق من استكشاف الأخطاء فقط). إذا عمل، فالمشكلة محصورة في بيئة GPU، انتقل إلى المجموعة 3

ما يجب أن تراه: بعد تحديث التعريف، انقر نقرًا مزدوجًا مجددًا على .bat، وتبقى النافذة السوداء مستقرة وتتدحرج السجلات، ثم يظهر في النهاية To see the GUI go to: http://127.0.0.1:8188.

"Torch not compiled with CUDA enabled" ​

السبب: تم تثبيت PyTorch بإصدار CPU أو بإصدار غير متوافق مع بطاقة الرسوميات — ComfyUI يريد استخدام CUDA لكن هذا الـ torch غير مُجمّع بدعم CUDA. هذا هو الأكثر شيوعًا لدى مستخدمي التثبيت اليدوي؛ والشكل الكامل لنفس الخطأ في قسم issues بالمستودع الرسمي هو AssertionError: Torch not compiled with CUDA enabled.

الحل:

  1. أزل التثبيت أولًا، ثم أعد التثبيت حسب بطاقة الرسوميات (بند استكشاف الأخطاء في README الرسمي):
bash
pip uninstall torch
# NVIDIA 稳定版(CUDA 13.0)
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
  1. التحقق (الأمر 2 من الفحص السريع): يُعد الإصلاح ناجحًا فقط عندما يطبع python -c "import torch; print(torch.cuda.is_available())" القيمة True
  2. ملاحظة لمستخدمي بطاقات Intel الرسومية: هذا الخطأ على Intel له معنى آخر — الواجهة الخلفية XPU غير متاحة، وComfyUI يعاملها خطأً كبطاقة CUDA. لا تطبّق خطوات إعادة تثبيت CUDA أعلاه حرفيًا، بل نفّذ أولًا أمر الفحص الرسمي:
bash
python -c "import torch; print('XPU available:', hasattr(torch, 'xpu') and torch.xpu.is_available())"

إذا طُبعت False فثبّت نسخة PyTorch المبنية لـ XPU (الأمر الرسمي الأصلي)، وتؤكد الجهة الرسمية صراحةً أن مستخدمي Intel يجب ألا يثبتوا حزمة wheel الخاصة بـ CUDA:

bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu
  1. مستخدمو الحزمة المحمولة: الحزمة تتضمن PyTorch متوافقًا مسبقًا، وعادةً لن تصادف هذا الخطأ؛ ووجوده يعني أن البيئة عُدّلت، ويمكن التفكير في update\update_comfyui_and_python_dependencies.bat (تصنّفه الجهة الرسمية للاستخدام فقط عند وجود مشكلة في التبعيات، وقبل تشغيله اعمل نسخة احتياطية من مجلد التثبيت بالكامل)

"cuDNN Frontend error: No valid execution plans built" ​

السبب: على بطاقات بنية Blackwell (سلسلة RTX 50)، قد يختار SDPA الافتراضي في PyTorch الواجهة الخلفية cuDNN، وهذه البنية لا تملك خطط تنفيذ صالحة. الوصف الرسمي: عند تشغيل FLUX يحدث الخطأ عند أول كتلة انتباه في UNet، ولا تُنتج أي صورة على الإطلاق.

الحل:

  1. فعّل تنفيذ الانتباه المكتوب يدويًا عند بدء التشغيل، لتجاوز SDPA و cuDNN (تعتبره الجهة الرسمية إصلاحًا موثوقًا):
bash
python main.py --use-split-cross-attention
  1. وتأكد في الوقت نفسه من نسخة PyTorch المبنية: توضح الجهة الرسمية أن Blackwell تتطلب نسخة مبنية بإصدار CUDA 12.8 فأحدث، وأن النسخة cu121 المبنية لا تعمل إطلاقًا على هذه البطاقات — بدّل إلى نسخة CUDA 12.8+ / cu130

💡 لا تسلك طريقًا ملتويًا

قالت الجهة الرسمية صراحةً: استخدام sitecustomize.py قبل بدء التشغيل لاستدعاء torch.backends.cuda.enable_cudnn_sdp(False) لإيقاف الواجهة الخلفية cuDNN لا يفيد — هذا الخيار لا يُحفظ عند تهيئة CUDA. معاملات بدء التشغيل هي الإصلاح الموثوق.

"libcuda.so.1: cannot open shared object file" ​

السبب: على Linux يثبّت PyTorch مكتبات NVIDIA داخل site-packages/nvidia/، والنظام لا يبحث هناك افتراضيًا. تصنّف الجهة الرسمية الأخطاء الثلاثة libcuda.so.1 وlibnccl.so وlibnvinfer.so.X من النوع نفسه كأعراض LD_LIBRARY_PATH واحدة.

الحل:

  1. أضف مسار المكتبات إلى متغيرات البيئة (لمستخدمي البيئات الافتراضية، انتبه لاستبدال python3.12 بإصدارك):
bash
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
# conda 环境改用 $CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nvjitlink/lib
  1. إن لم ترغب في كتابة المسار يدويًا، دع بايثون يجد site-packages بنفسه (الأمر الرسمي الأصلي):
bash
PYTHON_PATH=$(python -c "import site; print(site.getsitepackages()[0])")
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
# 可能还需要其他 NVIDIA 库目录
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cuda_runtime/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cublas/lib:$LD_LIBRARY_PATH
  1. لحلّ الأمر نهائيًا: أضِفها إلى سكربت activate الخاص بالبيئة الافتراضية أو إلى ~/.bashrc (وثّقت الجهة الرسمية طريقتين للكتابة)
  2. التحقق: python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"

يجب أن ترى: الخطوة 4 تطبع CUDA available: True ورقم إصدار CUDA، ثم ينطلق python main.py بشكل طبيعي.

ComfyUI لا يفتح: 127.0.0.1:8188، الشاشة السوداء والبيضاء ​

"Failed to connect to server" ​

السبب: انقطع الاتصال بين الخدمة والمتصفح. أعطت صفحة Connection Issues الرسمية أربعة بنود للفحص: الجدار الناري، والمنفذ، وVPN، والبروكسي؛ ويُضاف إليها الحالة الخامسة الأكثر شيوعًا — الخدمة لم تنطلق أصلًا.

الحل:

  1. انظر أولًا إن كان السطر هذا موجودًا في النافذة السوداء — To see the GUI go to: http://127.0.0.1:8188. إذا لم يكن موجودًا فالخدمة لم تنطلق، عُد إلى المجموعة 1
  2. السطر موجود لكن المتصفح لم يفتح تلقائيًا: هذا ليس عطلًا — توضح الوثيقة الرسمية أنه يفتح تلقائيًا عادةً، وإذا لم يفتح تلقائيًا فافتح المتصفح بنفسك وادخل إلى http://127.0.0.1:8188
  3. جرّب منفذًا آخر (الافتراضي 8188، وتنصح الجهة الرسمية بتجربة 8189 أو 8190). مستخدمو الحزمة المحمولة يعدّلون .bat بالمفكرة لإضافة المعامل (عرضت الجهة الرسمية طريقة تعديل .bat لإضافة معاملات الإقلاع):
bat
.\python_embeded\python.exe -s ComfyUI\main.py --port 8189 --windows-standalone-build
pause

أما مستخدمو التثبيت اليدوي فمباشرة: python main.py --port 8189.

  1. راجع القائمة الرسمية بندًا بندًا: اسمح لـ ComfyUI في الجدار الناري، وأوقف VPN مؤقتًا، وإذا لم تكن بحاجة إلى بروكسي فأوقفه
  2. من فعّلوا وصول الشبكة المحلية عبر --listen فليتنبهوا: سيُظهر السجل To see the GUI go to: http://0.0.0.0:8188، وعلى الأجهزة الأخرى استخدام IP جهازك المحلي للوصول (يُفحص عبر Win + R → cmd → ipconfig)، ومعنى 127.0.0.1 هو «الجهاز نفسه»، وعلى الهاتف لا يمثل حاسوبك

يجب أن ترى: يفتح المتصفح http://127.0.0.1:8188 (أو المنفذ الجديد)، وتظهر لوحة العُقد.

واجهة بيضاء أو مشوّهة أو بعرض غير طبيعي ​

السبب: المتصفح قديم جدًا. تنص متطلبات النظام الرسمية صراحةً: إصدارات Chrome 142 وما دونها بها مشكلات معروفة تسبب عرضًا غير طبيعي للواجهة ومشكلات في الأداء. وتوجد في قسم GitHub issue تقارير علنية متعلقة بالشاشة البيضاء (مثل White screen wen loading Comfyui).

الحل:

  1. ارقِ Chrome إلى 143 أو أعلى ثم افتح (نص المتطلب الرسمي حرفيًا)
  2. إذا بقيت الشاشة بيضاء بعد تغيير المتصفح: اجمع أخطاء وحدة تحكم المتصفح وفق قسم «ما زال لا يعمل؟» (F12 → Console)، ثم ابحث في GitHub Issues

يجب أن ترى: بعد الترقية يعرض http://127.0.0.1:8188 لوحة العُقد بشكل طبيعي.

شاشة سوداء عند الإقلاع أو انهيار مباشر (شاشة ComfyUI سوداء) ​

السبب: تصنّف الجهة الرسمية «انهيار الإقلاع، الشاشة السوداء، فشل التحميل» ضمن العَرَض نفسه «ComfyUI Won't Start»، ولا تقدّم للإصلاح السريع سوى خطوتين: التحقق من الحد الأدنى لمتطلبات النظام + تحديث تعريف GPU.

الحل:

  1. تحقق من متطلبات النظام: قارن معجدول متطلبات كرت الشاشة السريع من الدرس السابق، وتأكد أن الكرت في قائمة الدعم (NVIDIA / AMD / Intel Arc / Apple Silicon)، ومن لا يملك كرتًا منفصلًا فليستخدم وضع CPU
  2. حدّث تعريف GPU (من مواقع NVIDIA / AMD / Intel الرسمية، وهذا هو الإصلاح السريع الثاني رسميًا)
  3. مستخدمو الحزمة المحمولة ينقرون مرتين على run_cpu.bat (والتثبيت اليدوي بالإقلاع مع --cpu) ثم يعيدون المحاولة: وضع CPU يعمل على أي عتاد لكنه بطيء جدًا — إذا انطلق فالمشكلة في بيئة GPU، انتقل إلى المجموعة 3 وواصل الفحص
  4. مستخدمو macOS: عند وجود مشكلة في MPS قدّمت الجهة الرسمية بنفسها مخرجًا بديلًا عبر CPU python main.py --cpu (ويمكن استخدام --force-fp16 --cpu لتحسين الذاكرة)

يجب أن ترى: بعد تحديث التعريف (أو التحويل إلى وضع CPU)، تنطلق الخدمة بالكامل حتى To see the GUI go to: http://127.0.0.1:8188، ولا تعود الواجهة سوداء.

"Frontend or Templates Package Not Updated" ​

السبب: حدّثت كود ComfyUI عبر git pull لكن التبعيات الأساسية لم تواكب — فالواجهة الأمامية وقوالب تدفقات العمل ووثائق العُقد كلها حزم pip مستقلة. وعند فشل تحديث التبعيات يرتد النظام إلى الإصدار القديم، ويظهر في سجل الإقلاع Falling back to the default frontend..

الحل:

  1. ثبّت التبعيات الناقصة في بيئة Python الخاصة بـ ComfyUI (الحل الرسمي):
bash
pip install -r requirements.txt
  1. للشبكات داخل الصين أضِف مرآة Tsinghua (أعطتها الجهة الرسمية):
bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  1. إذا فشل مجددًا: نفّذ أولًا pip list لمقارنة الإصدارات، ثم ثبّت واحدًا واحدًا وفق أرقام الإصدارات المكتوبة في ComfyUI/requirements.txt (تنبه الجهة الرسمية إلى عدم الترقية إلى أحدث إصدار من تلقاء نفسك):
bash
pip install comfyui-frontend-package==<版本号>
pip install comfyui-workflow-templates==<版本号>
  1. إذا كانت الصلاحيات غير كافية: شغّل سطر الأوامر بصلاحيات المسؤول (إحدى خطوات استكشاف الأخطاء الرسمية)

يجب أن ترى: بعد اكتمال تثبيت التبعيات، لا يعود Falling back to the default frontend. يظهر في سجل الإقلاع، وتكون وظائف الواجهة كاملة.

مشكلات كرت الشاشة والتعريفات ​

"CUDA error: no kernel image is available for execution on the device" ​

السبب: بنية CUDA الخاصة بـ PyTorch لا تتضمن نواة مُجمّعة لمعمارية كرتك — عدم تطابق بين البنية والكرت. الحالة النموذجية: كرت جديد مع بنية قديمة (مثل Blackwell مع cu121)، أو كرت قديم مع بنية حديثة أكثر من اللازم.

الحل:

  1. بدّل الحزمة / البنية الصحيحة وفق الجدول الرسمي:
كرت الشاشةما يجب استخدامه من
سلسلة RTX 20 فأعلىالحزمة / البنية القياسية (CUDA 13.0)
سلسلة GTX 10 فأقدمحزمة cu126 (CUDA 12.6، Python 3.12)
سلسلة RTX 50 (Blackwell)بنية CUDA 12.8 فأعلى (رسميًا: بنية cu121 لا تعمل إطلاقًا)
  1. مستخدمو الحزمة المحمولة: احذف الحزمة الخاطئة، وأعد التنزيل والفك وفقجدول اختيار الحزم من الدرس السابق
  2. مستخدمو التثبيت اليدوي: نفّذ pip uninstall torch ثم ثبّت الإصدار المقابل، وتحقق بعدها عبر python -c "import torch; print(torch.cuda.is_available())"

"HIP error: invalid device function when running ComfyUI" ​

السبب: معمارية كرت AMD ليست ضمن قائمة الدعم في بنية ROCm المستخدمة. قدّمت الوثيقة الرسمية حلًا عبر تجاوز متغيرات البيئة خصيصًا «لكروت AMD غير المدعومة».

الحل (اختر واحدًا حسب المعمارية، بالأوامر الرسمية الأصلية):

bash
# RDNA2 或更旧(如 6700、6600)
HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py

# RDNA3(如 7600)
HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py

وتأكد في الوقت نفسه من صحة مصدر PyTorch — لكروت AMD على Linux استخدم إصدار ROCm المستقر:

bash
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2

"My GPU is not detected" ​

السبب: النسخة المكتبية لم تكتشف GPU — تعريف قديم، أو غياب سلسلة أدوات CUDA على Linux، أو أن نوع التثبيت نفسه لا يستخدم GPU المحلي أصلًا (الثلاث حالات المذكورة في الأسئلة الشائعة الرسمية).

الحل:

  1. حدّث تعريف NVIDIA
  2. على Linux، تأكد من تثبيت CUDA toolkit
  3. تأكد من أن نوع التثبيت يدعم GPU: يدعم كل من Standalone و Git Clone؛ أما اتصال Cloud فيستخدم GPU عن بُعد
  4. التحقق من سطر الأوامر (نسخة معزّزة من البند السريع 1، الأمر الرسمي الأصلي):
bash
nvidia-smi
nvidia-smi --query-gpu=driver_version --format=csv

يجب أن ترى: يطبع nvidia-smi طراز كرت الشاشة وإصدار التعريف؛ وتكتشف النسخة المكتبية GPU وتستخدمه بشكل طبيعي.

مشكلات Comfy Desktop النسخة المكتبية ​

"The app won't start after installation" ​

السبب: اعتراض عند الإقلاع مرتبط بالمنصة — صلاحيات، أو إعدادات أمان، أو مكتبات ناقصة. قدمت الأسئلة الشائعة الرسمية أربعة حلول حسب المنصة.

الحل:

  1. Windows: شغّل التطبيق مرة واحدة بصلاحيات المسؤول
  2. macOS: عند ظهور تحذير أمني، انتقل إلى إعدادات النظام ← الخصوصية والأمان واضغط فتح على أي حال (Open Anyway)
  3. Linux: تأكد من تثبيت FUSE 2(sudo apt install libfuse2)؛ وإذا كان AppArmor في Ubuntu 24.04+ يعترض صندوق العزل Electron، أضف --no-sandbox وأعد المحاولة — ⚠️ تحذير رسمي: هذا الخيار يعطّل صندوق عزل Electron لكل عملية، فلا تستخدمه إلا عند فشل إقلاع صندوق العزل
  4. انتقل إلى صفحة التنزيل وتأكد من حصولك على أحدث إصدار

يجب أن ترى: بعد معالجة الأمر حسب المنصة، تُفتح نافذة Comfy Desktop وتدخل إلى لوحة التحكم أو الإعداد الأول.

"App is damaged" ​

السبب: آلية أمان macOS تضع علامة «تالف» على التطبيق. وهي أول بند في دليل استكشاف أخطاء macOS الرسمي وإصلاحها.

الحل: انتقل إلى إعدادات النظام ← الخصوصية والأمان واسمح بالتطبيق. وتتضمن الصفحة الرسمية نفسها أيضًا: منح صلاحية الوصول الكامل للقرص عند مشكلات الأداء؛ وعند الانهيار، راجع تقارير الانهيار في تطبيق «Console».

"Comfy Desktop closes by itself after an update (Windows)" ​

السبب: خطأ مؤكد رسميًا — في نسخ Windows 1.0.46 وما قبلها، إذا لم يكتمل تنزيل التحديث يومض التطبيق بواجهة التحديث ثم يغلق من تلقاء نفسه، ويتكرر ذلك عند كل إقلاع دون أن يلحق الإصلاح الذاتي بالتنفيذ. تم إصلاحه اعتبارًا من 1.0.47.

الحل: ثبّت أحدث إصدار يدويًا (خطوات الاستعادة الرسمية):

  1. نزّل أحدث مثبّت Windows (أو احصل عليه من صفحة التنزيل)
  2. شغّل التثبيت مباشرة، ولا حاجة لإلغاء تثبيت الإصدار القديم أولًا
  3. شغّل Comfy Desktop

يجب أن ترى: يفتح التطبيق بشكل طبيعي ولا يخرج تلقائيًا — نسخة التثبيت والنماذج والإعدادات لديك كلها موجودة (مؤكد رسميًا أنها محفوظة).

"Unsupported device" ​

السبب: نسخة Windows من Comfy Desktop تدعم كروت NVIDIA CUDA فقط — نص حرفي من وثيقة استكشاف الأخطاء الرسمية. أصحاب كروت AMD / Intel على Windows سيواجهونه عند تثبيت النسخة المكتبية.

الحل: على مستخدمي Windows بكروت AMD / Intel سلوك أحد المسارين الرسميين الآخرين:

فشل التنزيل، أو التعليق في صفحة Maintenance، أو تنبيه مساحة القرص غير الكافية ​

السبب: تسحب النسخة المكتبية ملفات من GitHub / PyPI، وقد تتعطل إذا كانت الشبكة أو المرايا غير صحيحة؛ كما تفرض فحصًا لمساحة القرص عند إنشاء نسخة جديدة.

الحل:

  1. التعليق في صفحة Maintenance: توصي الوثيقة الرسمية بـ فحص إعدادات المرايا — في الواجهة الصينية يمكنك تفعيل Use Chinese Mirrors (Git & PyPI) في الإعدادات: تتحول مستودعات Git إلى gitcode.com وتستخدم PyPI مرايا Alibaba Cloud وTencent، وتوضح الوثيقة الرسمية أن هذا أسرع في الصين القارية
  2. Low Disk Space مجرد تحذير، واختيار Continue Anyway يتيح المتابعة (أو غيّر مسار التثبيت)؛ أما Not Enough Space for Template Models فيحجب هذا القالب — بدّل إلى سير عمل أخف أو نظّف القرص
  3. فشل المثبّت: توصي الوثيقة الرسمية بالتشغيل بصلاحيات المسؤول + التأكد من وجود مساحة قرص لا تقل عن 15GB؛ وتتطلب الوثيقة الرسمية للنسخة المكتبية ما لا يقل عن 4.85GB لكل تثبيت مستقل

مشكلات التنزيل وفك الضغط (لا يمكن تثبيت ComfyUI) ​

فشل فك ضغط 7z أو نقص الملفات بعد فك الضغط ​

السبب: يضيف Windows علامة «قفل» إلى الملفات المنزّلة من الإنترنت، مما يسبب مشكلات في فك الضغط. ويخصص README الرسمي لذلك جملة: If you have trouble extracting it, right click the file -> properties -> unblock.

الحل:

  1. انقر بزر الماوس الأيمن على ملف .7z ← خصائص ← ضع علامة على «إلغاء الحظر (Unblock)» ← موافق، ثم أعد فك الضغط
  2. إذا لم ينجح ذلك: استخدم 7-Zip لفك الضغط (وتوضح الوثيقة الرسمية أيضًا أن مستكشف Windows الأحدث يستطيع فك الضغط مباشرة)

يجب أن ترى: فك ضغط مجلد ComfyUI_windows_portable كاملًا، يحتوي على run_nvidia_gpu.bat وpython_embeded وغيرها.

تنزيل حزمة تثبيت خاطئة: تنزيل حزمة cu126 لكرت جديد (أو العكس) ​

السبب: أصدرت الجهة الرسمية عدة حزم حسب كرت الشاشة، والوحيد الذي يسهل اختياره خطأً هو حزمتا NVIDIA. حزمة cu126 مخصصة فقط لسلسلة GTX 10 والكروت الأقدم، وتؤكد الوثيقة الرسمية بحروف كبيرة: DO NOT USE THIS ON NEWER 20 SERIES AND ABOVE GPUS.

الحل: راجع اسم الملف وأعد التنزيل (الجدول الكامل في الدرس السابق)):

كرت الشاشة لديكاسم الملف الصحيح
سلسلة RTX 20 وما فوقComfyUI_windows_portable_nvidia.7z
GTX 10 وأقدمComfyUI_windows_portable_nvidia_cu126.7z
AMDComfyUI_windows_portable_amd.7z
IntelComfyUI_windows_portable_intel.7z

يجب أن ترى: بعد فك ضغط الحزمة الجديدة، انقر نقرًا مزدوجًا على .bat المقابل، ولن يظهر خطأ متعلق بالبنية عند التشغيل.

التنزيل بطيء أو فاشل (الشبكة داخل الصين) ​

السبب: حِزم التثبيت مستضافة على GitHub Releases — تشير الوثائق الرسمية إلى أن مستخدمي الصين القارية قد يحتاجون إلى إعداد وسيط (proxy) للوصول إلى مستودعات GitHub بثبات. بطء التنزيل لا يعني أنك أخطأت في الخطوات.

الحل:

  1. إعداد وسيط للوصول إلى GitHub (الحل الرسمي)
  2. لمستخدمي النسخة المكتبية: تفعيل المرايا الصينية (Git عبر gitcode.com، وPyPI عبر مرايا Alibaba Cloud وTencent، راجع البند السابق)
  3. عند تثبيت التبعيات يدويًا، بدّل pip إلى مرآة Tsinghua (كما توصي الجهة الرسمية): pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  4. احصل على الحزم من القنوات الرسمية فقط: GitHub Releases و comfy.org/download

ما زال لا يعمل؟ ​

اجمع الأدلة أولًا قبل السؤال. يتطلب قالب الإبلاغ عن الأخطاء الرسمي ستة عناصر من معلومات النظام، فجهّزها مسبقًا:

عنصر المعلوماتكيفية الحصول عليه
نظام التشغيلWindows: systeminfo | findstr /C:"OS Name" /C:"OS Version"؛ macOS/Linux: uname -a
إصدار ComfyUIمن الواجهة Settings → About
إصدار Pythonpython --version
إصدار PyTorchpython -c "import torch; print(f'PyTorch: {torch.__version__}')"
طراز GPU والتعريفWindows: wmic path win32_VideoController get name؛ Linux: lspci | grep VGA؛ إصدار التعريف nvidia-smi --query-gpu=driver_version --format=csv
طريقة التثبيتDesktop / Portable / Manual / comfy-cli

أضف ثلاثة أشياء أخرى: النص الكامل لرسالة الخطأ من وحدة التحكم، وأخطاء وحدة تحكم المتصفح (F12 → Console)، وسير عمل .json قادر على إعادة إنتاج المشكلة مع قائمة العقد المخصصة.

لمستخدمي النسخة المكتبية، ابحث عن السجلات أولًا. يكتب Comfy Desktop سجلات متجددة app.log، وأسرع مدخل هو Desktop Settings → Logs → Diagnostics → Open logs folder (من قائمة ☰ إلى الإعدادات). الموقع الافتراضي:

المنصةمجلد السجلات
Windows%APPDATA%\Comfy Desktop\logs
macOS~/Library/Logs/Comfy Desktop
Linux~/.config/Comfy Desktop/logs

راجع app.log (الجلسات القديمة في app.log_*.log التي تحمل طابعًا زمنيًا). للاطلاع على مخرجات عملية ComfyUI نفسها، افتح لوحة Manage للمثيل واستخدم علامة تبويب Terminal.

إلى أين تتوجه للسؤال (مقارنة القنوات الرسمية):

القناةأي نوع من المشكلات
ComfyUI GitHub Issuesمشكلات ComfyUI الجوهرية
Comfy-Desktop Issuesمشكلات النسخة المكتبية
ComfyUI_frontend Issuesمشكلات الواجهة الأمامية
مطورو العقد المخصصةمشكلات custom node (رسميًا: تواصل مع مطور العقدة المعنية)
المنتدى الرسمي / Discord / r/comfyuiطلب المساعدة من المجتمع

💡 ثلاثة أمور توصي بها الجهة الرسمية قبل السؤال

ابحث أولًا في GitHub Issues والمنتدى للتأكد من أن المشكلة ليست معروفة؛ اختبر بسير العمل الافتراضي مرة لاستبعاد عامل سير العمل؛ وإذا ثبّت عبر comfy-cli فنفّذ comfy node update all أولًا. لاستكشاف أخطاء مرحلة التوليد (العقد المخصصة، تحميل النماذج، ذاكرة GPU) ادخل من نظرة عامة على استكشاف الأخطاء.

نقطة تفتيش ✅ ​

  • 60 ثانية: نفذت الأوامر الأربعة للفحص السريع وأعرف أيها خاطئ
  • عندما تومض النافذة السوداء وتختفي، أعرف الترتيب: تحديث تعريف كرت الشاشة أولًا → إذا ظهر خطأ c10.dll فثبّت مكتبات VC++ → تحقق من تنزيل الحزمة الصحيحة
  • 127.0.0.1:8188 عند عدم الفتح، أتأكد أولًا من وجود سطر To see the GUI في النافذة السوداء، ثم أفحص جدار الحماية / VPN / تغيير المنفذ
  • عند ظهور شاشة بيضاء أو مشوهة في الواجهة، يكون رد فعلي الأول التحقق من إصدار Chrome (143 فما فوق)
  • عند السؤال سأرفق عناصر معلومات النظام الستة + النص الكامل لرسالة الخطأ + app.log (للنسخة المكتبية)

خلاصة هذا الدرس ​

✅ ComfyUI عند عدم الفتح، فكّك المشكلة طبقة طبقة: هل اكتمل تثبيت الملفات (المجموعة 5) → هل تنطلق الخدمة (المجموعتان 1 و3) → هل يتصل المتصفح (المجموعة 2) → هل النسخة المكتبية نفسها سليمة (المجموعة 4).

✅ حلّان رسميان صالحان لكل شيء: التحقق من متطلبات النظام + تحديث تعريف GPU، نفّذ هذين الأمرين أولًا قبل التدقيق.

✅ أسلوب السؤال الصحيح: عناصر معلومات النظام الستة + نص رسالة الخطأ + السجلات، وتوجه إلى مستودع GitHub الرسمي أو المجتمع المناسب.

مراجعة الإشارات الرئيسية:

الإشارةفي أي طبقةالخطوة الأولى
النافذة السوداء تومض وتختفيالتشغيلتحديث تعريف كرت الشاشة؛c10.dll → تثبيت مكتبات VC++
Torch not compiled with CUDA enabledبيئة PyTorchأزل torch وأعد تثبيته وفقًا لكرت الرسوميات
يوجد To see the GUI سطر لكن لا يمكن الفتحالخدمة ↔ المتصفحجرّب الوصول يدويًا؛ تحقق من الجدار الناري / VPN / غيّر المنفذ
شاشة بيضاء، تشوهات في العرضالمتصفحارفع Chrome إلى 143+
App is damagedأمان macOSاسمح به من الخصوصية والأمان
صفحة Maintenance عالقةالشبكةتحقق من إعدادات المرايا / فعّل مرايا صينية

استعراض الدرس التالي ​

أصبحت البيئة مستقرة، الخطوة التالية هي أين تضع النماذج: شرح تفصيلي لدليل models و extra_model_paths.

ستتعلم:

  • models البنية الكاملة للدليل وما يوضع في كل دليل فرعي
  • كيفية وضع checkpoint وVAE وLoRA في أماكنها الصحيحة
  • استخدام extra_model_paths.yaml لمشاركة النماذج بين عدة تثبيتات

لمن يريد توليد الصور مباشرة، بعد وضع النماذج انتقل إلى أول توليد صورة.

دروس ذات صلة ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.