ComfyUI Plugin Import Failed：自定義節點導入失敗怎麼修
修復 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 能啟動，但自定義節點沒有加載出來，通常不是“插件沒下載到”，而是 啟動 ComfyUI 的 Python 進程無法安全導入這個插件。
如果你搜的是 comfyui plugin import failed，先記住這幾個原則：
- 先定位 到底是哪一個插件 和 哪一條 traceback
- 先修 最早的導入失敗，不要先管你後面看到的紅節點
- 任何安裝命令都必須落在 真正啟動 ComfyUI 的那個 Python 環境
- 先把它當作依賴 / 打包 / 環境邊界問題，而不是先認定整個 ComfyUI 都壞了
通常原因會落在四類裡：
- 缺少 Python 包
- 某個插件改壞了共享依賴
- Torch 或其他核心包被降級或替換了
- 插件倉庫過舊、遷移了，或者只裝了一半
最常見的插件導入失敗模式
結合真實支持案例和 launcher 排障，下面這些是最常見的 plugin import failed 路線：
| 導入線索 | 通常意味著什麼 | 最該看的下一頁 |
|---|---|---|
No module named 'insightface' | 人臉/身份類插件依賴缺失 | InsightFace 缺失修復 |
No module named 'onnx' 或 onnxruntime | ONNX 節點依賴缺失 | ONNX / ONNXRuntime 缺失修復 |
No module named 'triton' | 可選加速或編譯後端缺失 | Triton 缺失修復 |
No module named 'llama_cpp' | LLM/VLM 插件依賴缺失 | llama_cpp 缺失修復 |
No module named 'nunchaku' | Nunchaku 工作流/插件後端沒裝對 | Nunchaku 缺失修復 |
指向 ComfyUI 內部 API 的 AttributeError | 插件源碼和你當前 ComfyUI 版本不匹配 | 優先更新插件或補源碼，不要先裝包 |
先分清下面三個常被混在一起的現象：
| 現象 | 通常意味著什麼 |
|---|---|
| 工作流裡紅節點 | 工作流請求的節點類沒有成功註冊 |
啟動日誌裡有 IMPORT FAILED | 插件目錄在，但 Python 導入插件失敗 |
| 只有在執行工作流時才報錯 | 節點註冊成功，但運行時輸入、模型、CUDA 或後端包出問題 |
先修最早失敗的那一層。 如果插件在啟動階段都沒註冊，後面再裝運行時依賴也救不了那個紅節點。
為什麼這類問題會越修越貴
真正耗時間的往往不是“缺一個節點”，而是修復循環：讀日誌、亂試 pip install、重啟、又報新錯、環境越來越漂。
“plugin import failed” 常見長相
你通常會看到這些現象：
- 啟動日誌裡出現
IMPORT FAILED - 插件目錄明明存在，但節點列表裡完全看不到它的節點
- 重啟後工作流出現紅節點
- 某個節點原來能用，裝完另一個插件後突然失效
- ComfyUI Desktop 或 portable 在加完自定義節點後變得不穩定
典型日誌比如：
IMPORT FAILED: ComfyUI-ExampleNode
ModuleNotFoundError: No module named 'somepackage'或者：
IMPORT FAILED: ComfyUI-AnotherNode
ImportError: DLL load failed while importing cv2或者：
IMPORT FAILED: ComfyUI-SomePlugin
AttributeError: module 'torch' has no attribute '...'第 1 步：先確認到底哪個插件失敗了
不要先裝隨機包。
先回答兩個問題：
- 哪個插件導入失敗了？
- 具體是什麼錯誤讓它失敗？
按這個順序看：
啟動日誌
找 IMPORT FAILED，把完整 traceback 複製出來。
這會告訴你是哪個插件壞了，以及 Python 到底卡在什麼對象上。
ComfyUI 的導入失敗 API
如果 ComfyUI 至少能起到打開頁面，可以訪問：
http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk它會返回導入失敗的 JSON 列表。
工作流裡的症狀
如果工作流出現紅節點，再觀察：
- 是不是隻有一個插件家族缺失
- 是不是多個互不相關的插件都缺失
- 是不是某個插件原來能用，後來裝完別的插件後才壞
這能幫助你判斷問題是局部的還是全局環境性的。
第 2 步：先分類，再修
絕大多數插件導入失敗都落在這幾類裡：
缺包
例如：
ModuleNotFoundError: No module named 'onnxruntime'這是最直接的一類：插件想導入的包沒裝。
二進制包損壞或不匹配
例如：
ImportError: DLL load failed while importing cv2包可能已經裝了，但它的 wheel 和當前 Python、CUDA 或 Windows 運行時不匹配。
核心依賴漂移
例如：
AttributeError: module 'torch' has no attribute '...'很多時候表示某次插件安裝把 torch、numpy、pillow 或 opencv-python 改壞了。
倉庫或源碼問題
例如：
- 倉庫搬遷了
- clone 不完整
- Git LFS 只拉到了指針文件
- 插件版本太舊，不兼容當前 ComfyUI
在你運行任何安裝命令之前
先把這三個問題搞清楚：
- 這個插件以前在這臺機器上能不能用？
- 現在是“插件目錄根本不存在”，還是“目錄在但導入失敗”？
- 它開始壞之前，是不是剛裝過別的插件？
這三個時間線問題，往往能快速告訴你：你面對的是缺包、環境漂移，還是源碼兼容性問題。
常見缺包對照
如果 traceback 已經指向這些包，優先走窄文檔，而不是跑整個 requirements：
| 日誌線索 | 常見影響範圍 | 更穩的下一步 |
|---|---|---|
No module named 'insightface' | ReActor、InstantID、IPAdapter FaceID | InsightFace 缺失修復 |
No module named 'onnx' 或 onnxruntime | DWPose、ReActor、ONNX 推理類節點 | ONNX / ONNXRuntime 缺失修復 |
No module named 'gguf' | ComfyUI-GGUF 相關節點 | ComfyUI-GGUF 修復 |
No module named 'triton' | SageAttention、編譯內核、部分視頻流 | Triton 缺失修復 |
No module named 'sageattention' | 可選加速或視頻工作流 | SageAttention 缺失修復 |
No module named 'llama_cpp' | 本地 LLM / VLM / QwenVL / GGUF | llama_cpp 缺失修復 |
No module named 'nunchaku' | Nunchaku FLUX、Qwen-Image、SVDQuant | Nunchaku 缺失修復 |
Torch not compiled with CUDA enabled | GPU 版 PyTorch 被替換或沒激活 | Torch CUDA 修復 |
第 3 步：手工修的時候只做最小動作
確定錯誤類別之後，用 最窄的修法。
如果只是缺包
把缺的包安裝進 啟動 ComfyUI 的同一個 Python 環境：
| 安裝類型 | 更穩的命令 |
|---|---|
| 官方 GitHub Windows portable 包 | 在 portable 根目錄執行：.\python_embeded\python.exe -s -m pip install somepackage |
| 手動 Git + venv 安裝 | 激活 venv 後執行：python -m pip install somepackage |
| ComfyUI Desktop 或受管 Launcher | 使用應用自己的終端或環境工具 |
裝完後重啟，再驗證。
如果這個包本身很重，或者插件作者明確給了固定 wheel，優先按作者文檔來。
如果懷疑依賴漂移
執行：
pip check優先盯這幾個核心包：
torchtorchvisiontorchaudionumpypillowopencv-pythontransformersdiffusers
如果某次插件安裝改壞了這些核心包，先修核心包，再回頭驗證插件。
更完整的處理路徑見 ComfyUI 依賴衝突。
如果插件本身舊了、殘了，或者源碼不完整
去 custom_nodes/ 下檢查：
- 倉庫是不是對的
- 文件是不是源碼，不是 Git LFS 指針
- 插件是否還支持你當前的 ComfyUI 版本
- README 是否要求額外手動安裝包
必要時：
cd custom_nodes/<plugin-name>
git pull然後只在必要時安裝該插件自己的依賴，而且要先看 requirements.txt：
不要盲跑 pip install -r requirements.txt。
- 先確認當前激活的是哪個 Python
- 打開
requirements.txt，看是否會改 torch、numpy、opencv 等核心包 - 能只裝缺的包就只裝缺的包
- 安裝後跑
pip check
官方 Windows portable 包更穩的寫法是：
.\python_embeded\python.exe -s -m pip install -r .\ComfyUI\custom_nodes\<plugin-name>\requirements.txt第 4 步：什麼時候命令行循環已經在傷害你
手工修沒問題，但一旦進入這種循環，就開始變貴了：
- 裝一個包
- 重啟 ComfyUI
- 又冒出一個新的 import failure
- 再裝一個包
- Torch 被帶壞
- 再回頭修 Torch
- 最後已經記不清到底改了什麼
這時繼續命令行亂修，往往比“問題本身”更傷環境。
什麼時候它已經升級成“依賴衝突問題”
如果你為一個插件導入失敗補了一個包，結果變成多個互不相關的插件一起失敗，那通常已經不是單個插件問題了。
這時更應該切到：
Wonderful Launcher 能幫你什麼
Wonderful Launcher 更適合 ComfyUI 已經開始變髒 的階段。
它的價值不是“幫你裝一個插件”，而是：
- 接管現有 Desktop 或 portable 環境
- 在儘量少命令行跳轉的前提下恢復導入失敗
- 降低因為修插件而重裝整個環境的概率
- 在自助恢復不夠時，保留任務日誌和啟動證據，方便支持繼續定位
什麼時候 Launcher 更合適
如果這臺機器上已經有工作流、模型、客戶項目或付費產出，優先目標應該是“低漂移恢復”，而不是“再重裝一次試試”。
什麼時候該交給啟動器和支持
如果出現這些情況，繼續隨機安裝包通常會更亂，應該先用啟動器保留證據，再考慮支持介入：
- 多個互不相關的插件同時失敗
- 修插件之後開始影響啟動
- Torch、CUDA、OpenCV 都被前面的修法帶亂了
- 你已經分不清問題來自倉庫、環境還是工作流
相關文檔
先按上面的步驟定位根因。還卡住時，可以下載 Wonderful Launcher 檢查目前機器；啟動器原生修復、任務日誌和執行階段檢查會集中在一起。credits 只用於圖片生成和按量工具。
下載 Wonderful Launcher查看 credits 方案這篇文件解決了你的問題嗎？
你的回饋會幫助我們優先補強真實 ComfyUI 排障文件。