ComfyUI 故障排查決策樹
按順序判斷 ComfyUI 故障屬於啟動崩潰、插件衝突、依賴錯誤還是模型問題。
測試環境
- 操作系統： Windows 10 / 11
- Launcher： Wonderful Launcher v1.x
- ComfyUI： Portable / Managed install
- Python： 3.11+
- CUDA / Torch： CUDA 12.x / Torch 2.x
- 最後驗證： 2026-05-19
ComfyUI 出問題時，最常見的誤區是靠猜。 這篇給你一個順序明確的判斷樹，先分清是基礎環境壞了、插件沒裝好、依賴衝突，還是模型文件本身有問題。
這頁最適合什麼時候用
當你還不知道自己到底屬於哪一類故障時，用這頁最合適：
- 啟動失敗
- 插件導入失敗
- 依賴衝突
- 缺失節點
- 模型放置或運行時報錯
如果你已經知道精確報錯字符串，直接去對應窄頁通常更快；這頁更像總入口。
判斷 1：ComfyUI 能不能啟動？
先檢查 http://127.0.0.1:8188/system_stats 是否能返回數據。
- 能返回：說明 ComfyUI 核心基本已啟動，繼續看判斷 2。
- 不能返回：先修基礎環境，不要急著裝插件。
判斷 2：工作流裡是不是出現了紅節點或缺失節點？
導入工作流後，如果有節點變紅或直接缺失，先別急著裝一堆包。
第 1 步：它是不是前端節點？
下面這些通常不需要後端註冊，出現缺失也不一定是真問題：
NoteRerouteMarkdownNoteFast Groups Muter (rgthree)Fast Groups Bypasser (rgthree)PrimitiveNodeGetNodeSetNode- 任何以
workflow>開頭的本地封裝節點
如果就是這些，通常可以先忽略。
第 2 步：插件裝了嗎？
檢查對應插件目錄是否真的存在於 custom_nodes/。
- 目錄不存在：先安裝正確插件，見 安裝自定義節點
- 目錄存在但節點還是沒出現：繼續看判斷 3
如果“缺失節點”本身就是你的主症狀，再結合這頁一起看：
判斷 3：插件目錄在，但節點還是不工作
這時重點不是“繼續安裝依賴”，而是先看啟動日誌裡有沒有 IMPORT FAILED。
-
缺少 Python 包導致導入失敗：這是依賴問題
不要直接無腦執行
pip install -r requirements.txt。- 先確認當前激活的是哪個 Python 環境：
where python或which python - 打開
requirements.txt，看它有沒有釘死 torch、numpy、opencv 等關鍵版本 - 能只裝缺的包就只裝缺的包：
pip install <package-name> - 安裝後運行
pip check，確認沒有引入新的衝突
更復雜的情況看 依賴衝突。
- 先確認當前激活的是哪個 Python 環境：
-
是代碼層錯誤，例如
AttributeError，或者導入 ComfyUI 內部 API 時報錯：這是源碼兼容性問題- 說明插件版本和你當前的 ComfyUI 版本不兼容
- 應優先更新插件，或者做最小補丁
- 這不是單純缺依賴，不要繼續盲目裝包
-
沒有導入失敗，但節點名稱對不上：這是節點改名問題
- 可能插件更新後把舊節點名換掉了
- 例如
InpaintCrop改成InpaintCropImproved - 解決方式是更新工作流節點名，或者在插件
__init__.py里加兼容別名
如果主要症狀是反覆出現 IMPORT FAILED，更應該直接看：
判斷 4：節點存在，但執行時報錯
節點不是紅的，也能加載出來，但一運行工作流就報錯。
先看錯誤信息屬於哪一類：
-
報錯指向模型文件路徑，例如 checkpoint、LoRA、ControlNet、SAM、ONNX 這是模型問題，不是插件問題。
- 下載對應模型，並放到正確目錄
- 參考 下載模型
- 不要為了這類錯誤去改插件或重裝依賴
-
報錯提到 Python 模塊或函數 這通常還是依賴或兼容性問題。
- 先查包是否真的裝了：
pip show <package_name> - 再看版本是否匹配
- 先查包是否真的裝了：
判斷 5：日誌裡出現 “Starting server”，但界面還是打不開
如果控制台已經打印：
Starting serverTo see the GUI go to: http://127.0.0.1:8188
但瀏覽器一直卡在加載界面，這 不等於 ComfyUI 沒啟動。 更常見的是：核心已經起來了，但啟動後的某個環節把前端卡住了。
常見原因：
| 原因 | 現象 | 處理方式 |
|---|---|---|
| ComfyUI-Manager 拉遠程數據 | 日誌反覆訪問 raw.githubusercontent.com | 把 Manager 切到離線模式，在 config.ini 裡設 network_mode = offline |
| BizyAir API 重試循環 | 日誌裡反覆出現 Failed to cache trd models、Invalid API key | 在啟動腳本里設 BIZYAIR_SKIP_TRD_MODEL_CACHE=1 |
| 大工作流 + Node 2.0 渲染 | CPU 佔用飆升，瀏覽器無響應 | 在 rgthree 設置裡關閉 Node 2.0 渲染 |
| 編碼問題 | 日誌中出現 UnicodeDecodeError | 在環境變量里加入 PYTHONUTF8=1 和 PYTHONIOENCODING=utf-8 |
驗證方式：
- 直接訪問
http://127.0.0.1:8188/system_stats如果能打開，說明核心服務沒問題，問題更可能在前端或啟動後插件。 - 看
python.exe進程是不是還活著 如果已經退出，就回到最後一條報錯日誌看真正的崩點。
判斷 6：看起來能用，但環境越來越不穩定
ComfyUI 能啟動，工作流也能跑，但總是隨機崩、包衝突、插件互相汙染。
先運行：
pip check但注意，pip check 看到報錯並不等於每條都必須修。
| 類型 | 含義 | 應對方式 |
|---|---|---|
| 硬阻塞 | 核心包彼此不兼容，例如 torch 版本錯位 | 必須優先修 |
| 軟漂移 | 例如某插件要求 numpy>=2，但你為了穩定停在 numpy 1.26.4 | 記錄下來，只要運行穩定可以先不動 |
| 可選依賴 | 某插件聲明瞭你當前工作流根本沒用到的包 | 不要急著安裝，可能會把環境越修越壞 |
如果這種“不穩定”是多輪補包之後才出現的，再加看：
快速對照：錯誤類型 -> 問題類別
| 錯誤表現 | 問題類別 | 應該怎麼做 |
|---|---|---|
| 紅節點 / 缺失節點 | 插件沒裝好，或導入失敗 | 安裝插件，檢查導入日誌 |
日誌出現 IMPORT FAILED | 依賴或兼容性問題 | 檢查 pip install、版本衝突 |
ModuleNotFoundError | 缺少 Python 包 | 安裝對應包 |
AttributeError 指向 ComfyUI 內部 API | 插件和當前 ComfyUI 版本不兼容 | 更新插件或打補丁 |
FileNotFoundError 指向模型路徑 | 模型文件缺失 | 下載並放到正確目錄 |
CUDA out of memory | 顯存不夠 | 用 --lowvram、更小模型或更低分辨率 |
| 瀏覽器空白 / 啟動畫面卡住 | 啟動後階段被阻塞 | 檢查聯網插件、切離線模式 |
torch.cuda.is_available() 為 False | PyTorch 和 CUDA 不匹配 | 使用 Torch Missing 選擇正確 wheel |
相關文檔
還卡住？
如果你按這棵樹查過一遍還是沒修好，先試試 Wonderful Launcher。它可以先幫你恢復環境，再繼續細查根因。
參考來源
先按上面的步驟定位根因。還卡住時，可以下載 Wonderful Launcher 檢查目前機器；啟動器原生修復、任務日誌和執行階段檢查會集中在一起。credits 只用於圖片生成和按量工具。
下載 Wonderful Launcher查看 credits 方案這篇文件解決了你的問題嗎？
你的回饋會幫助我們優先補強真實 ComfyUI 排障文件。