如何修復 ComfyUI 自定義節點 requirements.txt 未安裝的問題
修復因 requirements.txt 相依性未安裝到正確 Python 環境而導致加載失敗的 ComfyUI 自定義節點。
社群知識
本頁內容基於常見的 ComfyUI 故障排查模式，尚未在所有環境中經過完整測試。在更改軟體包之前，請備份您的環境。
如果 ComfyUI 自定義節點在啟動日誌中顯示 IMPORT FAILED，原因為 ModuleNotFoundError，最常見的原因是該節點的 requirements.txt 從未被安裝過。
將自定義節點克隆或下載到 custom_nodes/ 目錄中只是複製了代碼。該代碼所相依的 Python 包必須單獨安裝。
在截至 2026 年 6 月 29 日的 30 天 Wonderful Launcher 遙測窗口中，節點缺失相依性修復問題反覆出現：用戶存在節點缺失、克隆嘗試、相依性安裝結果以及後續 ModuleNotFoundError 事件。請將這些視為一條修復鏈，而非各自獨立的隨機軟體包問題。
快速解答
適用於 GitHub Windows 免安裝版：
.\python_embeded\python.exe -s -m pip install -r ComfyUI\custom_nodes\<node-name>\requirements.txt
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build安裝前請務必先閱讀 requirements 文件，檢查是否存在有風險的包變更。
錯誤的表現形式
IMPORT FAILED: ComfyUI-ExampleNode
Traceback (most recent call last):
File "...\custom_nodes\ComfyUI-ExampleNode\__init__.py", line 4, in <module>
import somepackage
ModuleNotFoundError: No module named 'somepackage'節點資料夾存在於 custom_nodes/ 中，但匯入失敗，因為 somepackage 未被安裝。
真實修復案例中常見的相依模式
以下模組在近期啟動器遙測數據中出現頻率較高，在重新克隆同一節點之前，建議先逐一排查：
| 缺失模組 | 常見工作流場景 | 首要驗證事項 |
|---|---|---|
triton | 加速、SageAttention、視頻、大模型工作流 | 安裝前先確認該相依性是可選的還是必需的 |
sageattention | Wan/視頻加速及強制 attention 標誌 | 除非工作流確實需要，否則移除強制標誌 |
onnx / onnxruntime | 人臉、姿勢、DWPose、ReActor、IPAdapter、視頻輔助工具 | 優先使用 CPU 版 onnxruntime，除非確實需要 GPU ONNX |
llama_cpp | GGUF 提示輔助工具、本地 LLM/VLM 節點 | 包名通常是 llama-cpp-python，而非 llama_cpp |
nunchaku | 基於 Nunchaku 的 FLUX/Qwen/SANA 工作流 | 不要安裝 PyPI 上無關的 nunchaku 包 |
sox / decord | 音訊和視頻輔助節點 | 先確認節點包來源，不要批量安裝所有視頻相關包 |
groundingdino / segment_anything | 目標檢測、定位、分割、遮罩 | 參考 SAM/GroundingDINO 匯入指南，並確認模型資源 |
dlib / nvvfx | 人臉/視頻特效工作流 | 原生 wheel 包和平台支持至關重要，請先閱讀插件 README |
如果某個模組不在表格中，同樣適用相同規則：先找到導致失敗的插件，再將所需的最小相依性安裝到啟動 ComfyUI 的 Python 環境中。
原因分析
- 手動 git clone 但未執行 pip install：您克隆了節點倉庫，但忘記安裝其相依項目
- ComfyUI Manager 部分安裝：Manager 可能克隆了倉庫，但相依性安裝步驟靜默失敗
- 環境被重建：您重新安裝了 ComfyUI 或更新了免安裝版，導致之前安裝的包被清除
- 安裝時使用了錯誤的 Python：相依性被安裝到了系統 Python，而非 ComfyUI 的嵌入式 Python
- 沒有 requirements.txt：部分節點只在 README 中列出相依項目，而未提供 requirements 文件
分步修復方法
第一步：找到失敗的節點
檢查 ComfyUI 啟動日誌中的 IMPORT FAILED 行。該行會告訴您哪個自定義節點資料夾失敗，以及缺少哪個模組。
第二步：檢查 requirements.txt 是否存在
dir ComfyUI\custom_nodes\<node-name>\requirements.txt如果文件存在，繼續第三步。如果不存在，請在 GitHub 上查看該節點的 README，了解手動安裝相依性的說明。
第三步：安裝前先閱讀 requirements 文件
type ComfyUI\custom_nodes\<node-name>\requirements.txt注意以下風險信號：
| 需要注意的内容 | 風險 |
|---|---|
torch、torchvision、torchaudio | 可能將您啟用 CUDA 的 PyTorch 替換為 CPU 版本 |
未鎖定版本（無 == 或 >=） | 可能安裝不兼容的版本 |
已有 opencv-python-headless 時出現 opencv-python | 可能導致 DLL 衝突 |
| 版本鎖定過舊或過新 | 可能與其他節點衝突 |
如果文件看起來安全，可以繼續。如果文件中包含 torch 或其他核心包，請考慮僅手動安裝實際缺失的包，而不是全部安裝。
第四步：安裝相依項目
適用於 Windows 免安裝版：
.\python_embeded\python.exe -s -m pip install -r ComfyUI\custom_nodes\<node-name>\requirements.txt適用於手動創建的 venv：
python -m pip install -r custom_nodes/<node-name>/requirements.txt第五步：如果 requirements 文件會破壞您的環境
與其安裝所有內容，不如只安裝具體缺失的包：
.\python_embeded\python.exe -s -m pip install somepackage當 requirements 文件包含 torch 等核心包時，這種方式更為安全。
第六步：驗證
重啟 ComfyUI，確認 IMPORT FAILED 行已消失：
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build批量安裝所有自定義節點的相依項目
如果多個節點存在缺失的相依項目，可以批量安裝，但这帶來更高的風險：
for /d %d in (ComfyUI\custom_nodes\*) do if exist "%d\requirements.txt" .\python_embeded\python.exe -s -m pip install -r "%d\requirements.txt"警告：盲目運行此命令可能導致相依性衝突。更安全的做法是逐個節點安裝相依性，每次安裝後檢查是否有錯誤。
不應盲目運行 pip install 的情況
- 運行前始終先閱讀
requirements.txt——部分節點作者會鎖定強制性的 torch 版本 - 如果安裝後
pip check顯示衝突，不要繼續安裝更多相依性，先解決衝突 - 如果 requirements 文件非常陳舊，鎖定的版本可能無法與您當前的 Python 或 PyTorch 兼容
- 如果只需要某個包本身而非其相依性樹，可考慮對單個包使用
--no-deps
Wonderful Launcher 如何提供幫助
Wonderful Launcher 可以幫助檢測具有未安裝相依項目的自定義節點，並協助安全安裝這些相依性。它會在安裝前檢查衝突，並幫助防止 requirements 破壞您的核心 PyTorch 環境。
下載 Wonderful Launcher——免費使用，幫助管理自定義節點相依項目。
相關錯誤
參考來源
先按上面的步驟定位根因。還卡住時，可以下載 Wonderful Launcher 檢查目前機器；啟動器原生修復、任務日誌和執行階段檢查會集中在一起。credits 只用於圖片生成和按量工具。
下載 Wonderful Launcher查看 credits 方案這篇文件解決了你的問題嗎？
你的回饋會幫助我們優先補強真實 ComfyUI 排障文件。