ComfyUI 插件导入失败：修复自定义节点错误
修复 ComfyUI 插件导入失败错误、损坏的自定义节点导入、工作流红色节点以及依赖漂移问题，无需重新安装环境。
测试环境
- 操作系统： Windows 10 / 11
- 启动器： Wonderful Launcher v1.x
- ComfyUI： 便携版 / 托管安装
- Python： 3.11+
- CUDA / Torch： CUDA 12.x / Torch 2.x
- 最后测试时间： 2026-05-19
如果你搜索了 comfyui plugin import failed，或者启动日志中出现了 IMPORT FAILED，本页面专门针对自定义节点导入报错，而非浏览器保存错误、重连循环或 Manager 注册表获取问题。
如果你看到的唯一提示是 Failed to Save Workflow Draft，请先保护工作图，并使用 ComfyUI 工作流草稿保存失败修复。浏览器草稿保存失败与插件导入报错并非同一回事。
如果 ComfyUI 能够启动但自定义节点未能加载，插件可能已经下载，但启动 ComfyUI 的 Python 进程无法安全导入它。
如果你搜索了 comfyui plugin import failed，简短的答案是：
- 首先确定具体是哪个插件出错以及完整的报错追踪信息
- 修复最早出现的导入失败，而不是你后来注意到的红色节点
- 只在实际启动 ComfyUI 的 Python 环境中安装包
- 优先将此问题视为依赖或打包问题，而非 ComfyUI 整体损坏的证明
如果你看到的错误是 Failed to Save Workflow Draft，请在调试插件之前先使用 ComfyUI 工作流草稿保存失败。如果看到的错误是 failed to fetch server logs，请使用 ComfyUI 无法获取服务器日志。如果 Manager 提示 failed to get custom node list，请使用 ComfyUI 无法获取自定义节点列表。
通常原因是以下四种之一：
- 缺少必要的 Python 包
- 某个插件安装了不兼容的依赖
- Torch 或其他核心包被降级
- 插件仓库已过时、已迁移或仅部分安装完成
最具参考价值的插件导入失败场景
以下是在实际支持和启动器故障排查中最常出现的插件导入模式：
| 导入线索 | 通常含义 | 最佳参考页面 |
|---|---|---|
No module named 'insightface' | 人脸或身份识别插件依赖缺失 | ComfyUI 中 InsightFace 缺失 |
No module named 'onnx' 或 onnxruntime | ONNX 支持的节点依赖缺失 | ComfyUI 中 ONNX / ONNXRuntime 缺失 |
No module named 'triton' | 可选加速或编译后端缺失 | ComfyUI Triton 缺失或不可用 |
No module named 'llama_cpp' | LLM/VLM 插件依赖缺失 | ComfyUI 中 llama_cpp 缺失 |
No module named 'nunchaku' | Nunchaku 工作流/插件后端未正确安装 | ComfyUI 中 Nunchaku 缺失 |
AttributeError 指向 ComfyUI 内部 | 插件源码与你的 ComfyUI 版本不再匹配 | 更新插件或修补源码，而非安装包 |
Failed to Save Workflow Draft | 浏览器工作流状态无法保存 | 先保存工作流 JSON |
将三种经常混淆的症状区分开来很有帮助：
| 症状 | 通常含义 |
|---|---|
| 工作流中出现红色节点 | 工作流请求了一个未注册的节点类 |
启动时出现 IMPORT FAILED | 插件文件夹存在，但 Python 无法导入该插件 |
| 只在队列提示词时出错 | 节点存在，但运行时输入、模型、CUDA 或后端包失败 |
优先修复最早出现故障的层级。如果插件从未注册其节点，为运行时错误安装包也无济于事。
好消息是，插件导入失败并不总意味着你必须重新安装 ComfyUI。大多数情况下，你可以识别故障类型、修复环境，并保留现有的工作流和模型。
为什么这个问题会迅速变得代价高昂
真正的代价很少是缺失的节点本身。昂贵的部分是修复循环：查看日志、尝试随机的 pip install 命令、重启 ComfyUI，并使环境逐渐偏离得更远。
"插件导入失败"通常是什么样子
你通常会看到以下一种或多种症状：
- 启动日志中出现
IMPORT FAILED - 自定义节点文件夹存在，但其节点均未出现在 ComfyUI 中
- 重启后工作流出现红色节点
- 某个节点之前正常工作，在安装另一个插件后停止加载
- 添加自定义节点后，ComfyUI Desktop 或便携版构建变得不稳定
典型的日志行如下所示：
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 '...'第一步：确认哪个插件实际失败
不要一开始就随机安装包。
首先，回答两个问题：
- 哪个插件导入失败？
- 是什么具体的错误类型阻止了导入？
按顺序检查以下位置：
启动日志
查找 IMPORT FAILED 并复制完整的报错追踪信息。这能告诉你哪个插件出错以及哪个 Python 对象无法导入。
ComfyUI 导入失败 API
如果 ComfyUI 仍然能够启动并打开 UI，请访问：
http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk这将返回一个自定义节点导入失败的 JSON 列表。
工作流症状
如果工作流显示红色节点，注意以下情况：
- 是否只有一个插件系列缺失
- 是否多个不相关的插件缺失
- 在另一次安装改变环境之前，同一个插件是否正常工作
这种规律有助于你判断问题是局部的还是全局的。
案例审查验证边界
近期的 Agent 案例审查显示，许多修复步骤提前一步停止了。 磁盘上存在插件文件夹、成功克隆，或离线 Python 导入成功， 并不等同于 ComfyUI 节点正常工作。
在宣告修复完成之前，请使用以下验证阶梯：
| 已验证状态 | 它能证明什么 | 它尚未证明什么 |
|---|---|---|
| 插件文件夹存在 | 文件存在于 custom_nodes/ 下 | 插件导入成功 |
python -c "import package" 正常运行 | 某个 Python 包可以离线导入 | ComfyUI 使用了同一个 Python 或注册了节点 |
启动日志中该插件没有 IMPORT FAILED | 插件导入通过了启动阶段 | 工作流拥有所有模型文件和运行时输入 |
/v2/customnode/import_fail_info_bulk 中该插件记录干净 | ComfyUI 后端没有记录该导入失败 | 工作流执行时不会出现模型/CUDA/输入错误 |
| 重启后红色节点消失 | 节点类已注册 | 模型文件、检查点和运行时后端可能仍然缺失 |
如果节点已注册但工作流需要模型文件，请切换到 模型放置 或 找不到模型。不要继续重新安装插件。
第二步：修复前先对故障分类
大多数插件导入失败属于以下几类之一。
缺少包
示例：
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 等核心包。
仓库或源码问题
示例：
- 仓库已迁移
- 插件仅部分克隆完成
- Git LFS 留下了占位符文件
- 插件对于你当前的 ComfyUI 版本来说过于陈旧
运行任何安装命令之前
先检查以下三件事：
- 这个插件在这台机器上曾经正常工作过吗？
- 插件文件夹是存在但已损坏，还是完全缺失？
- 在这个导入开始失败之前，是否发生了另一个插件安装？
这段简短的时间线通常能告诉你，应该将问题视为缺少包、依赖漂移还是源码兼容性问题。
常见的特定包处理路径
如果报错追踪信息中出现以下某个包名，请在运行宽泛的插件依赖安装之前先使用具体指南：
| 日志线索 | 通常影响 | 更安全的参考指南 |
|---|---|---|
No module named 'insightface' | ReActor、InstantID、IPAdapter FaceID | ComfyUI 中 InsightFace 缺失 |
No module named 'onnx' 或 onnxruntime | DWPose、ReActor、ONNX 模型推理 | ComfyUI 中 ONNX / ONNXRuntime 缺失 |
No module named 'gguf' | ComfyUI-GGUF 加载器节点 | ComfyUI-GGUF：修复 No Module Named 'gguf' |
No module named 'triton' | SageAttention、编译内核、部分视频工作流 | ComfyUI No Module Named 'triton' |
No module named 'sageattention' | 可选加速或视频工作流 | ComfyUI 中 SageAttention 缺失 |
No module named 'llama_cpp' | QwenVL GGUF、本地 LLM、VLM 或提示词增强节点 | ComfyUI 中 llama_cpp 缺失 |
No module named 'nunchaku' | Nunchaku FLUX、Qwen-Image 或 SVDQuant 工作流 | ComfyUI 中 Nunchaku 缺失 |
Torch not compiled with CUDA enabled | GPU PyTorch 构建被替换或未激活 | Torch CUDA 修复指南 |
| Easy Use、Layer Style、rgthree 或 VideoHelperSuite 导入失败 | 流行的自定义节点包已安装但未加载 | 流行自定义节点包指南 |
第三步：手动修复环境
一旦你知道了故障类型，请使用最小范围的修复方案。
如果缺少某个包
安装缺少的包，但要在与启动 ComfyUI 相同的 Python 环境中操作：
| 安装类型 | 更安全的命令 |
|---|---|
| 官方 GitHub Windows 便携版 | 从便携版根目录运行：.\python_embeded\python.exe -s -m pip install somepackage |
| 手动 Git + venv 安装 | 激活 venv，然后运行 python -m pip install somepackage |
| ComfyUI Desktop 或托管启动器 | 使用应用内的环境/终端工具。不要假设便携版的 python_embeded 目录结构存在。 |
然后重启 ComfyUI 并再次测试。
如果已知该包较为敏感或体积较大，优先使用固定版本安装或插件作者推荐的 wheel 文件。
如果怀疑依赖漂移
运行：
pip check重点检查以下包是否存在冲突：
torchtorchvisiontorchaudionumpypillowopencv-pythontransformersdiffusers
如果某次插件安装改变了其中之一，先修复核心包，然后再次测试失败的插件。
更完整的操作流程，请参阅 ComfyUI 依赖冲突。
如果插件本身已过时或部分损坏
进入 custom_nodes/ 下的插件文件夹并验证：
- 仓库是正确的
- 源文件是真实代码，而非 Git LFS 占位符
- 插件仍然支持你的 ComfyUI 版本
- 插件 README 中没有要求额外手动安装的包
如有必要：
cd custom_nodes/<plugin-name>
git pull然后仅重新安装该插件的依赖——但要谨慎操作：
不要盲目运行 pip install -r requirements.txt。
- 确认当前激活的是哪个 Python 环境（
where python或which python） - 检查
requirements.txt——确认它是否固定了 torch、numpy 或 opencv 的版本 - 尽可能只安装缺失的包：
pip install <package-name> - 安装后运行
pip check验证未引入新的冲突
对于官方 Windows 便携版，建议从便携版根目录使用 .\python_embeded\python.exe -s -m pip install -r .\ComfyUI\custom_nodes\<plugin-name>\requirements.txt 运行。
第四步：知道何时命令行循环让情况变得更糟
手动修复是有效的，但如果你反复执行以下操作，代价会变得高昂：
- 安装一个包
- 重启 ComfyUI
- 遇到新的导入失败
- 再安装一个包
- 导致 Torch 损坏
- 修复 Torch
- 失去对改动的追踪
许多用户正是在这种情况下最终选择重新安装，即使环境从技术上来说本可以恢复。
当问题实际上是依赖冲突时
如果一个插件导入失败在安装包之后演变为多个不相关插件失败，你通常已经不再面对单一的插件 bug 了。
这时应该切换到：
Wonderful Launcher 如何提供帮助
Wonderful Launcher 可以帮助你检查实际出现故障的 ComfyUI 环境，让启动日志与修复流程紧密关联，并在单个插件导入是真正瓶颈时避免大范围的包变更。它可以引导你进行更安全的恢复步骤，但复杂的插件组合可能仍然需要手动确认。
下载 Wonderful Launcher — 免费开始使用。
使用 Wonderful Launcher 的更安全恢复路径
Wonderful Launcher 专为 ComfyUI 已经变得混乱的阶段而设计。
它不是将问题视为"安装一个插件然后祈祷成功"，而是旨在帮助你：
- 接管现有的 Desktop 或便携版安装
- 以更少的命令行操作从插件导入失败中恢复
- 在工作流、模型和自定义节点已存在的情况下降低重装风险
- 在不更换工具的情况下从自我修复过渡到专家帮助
何时 Launcher 是更好的选择
如果你在这台机器上已经有工作流、已下载的模型或付费工作，目标应该是以最小漂移进行恢复，而不是再次完整重装。
何时寻求专家帮助
在以下情况下请寻求专家帮助：
- 多个不相关的插件同时失败
- 插件修复尝试后出现启动失败
- Torch、CUDA 或 OpenCV 已被之前的修复操作改变
- 你无法判断问题出在仓库、环境还是工作流
在这种情况下，实时恢复通常比又一个晚上的反复试错要快得多。
相关指南
- ComfyUI 启动失败？如何更快地诊断和恢复
- ComfyUI 依赖冲突
- ComfyUI No Module Named 错误：何时可以安全忽略
- ComfyUI No Module Named 'llama_cpp'
- ComfyUI 插件管理
- 流行的 ComfyUI 自定义节点包
- 故障排查决策树
需要最快捷的解决路径？
如果环境已经不稳定，请先把完整 traceback、当前 Python 路径、插件 requirements 和最近一次安装命令保存下来，再按本页步骤做最小化修复。
参考资料
先按上面的步驟定位根因。还卡住时，可以下载 Wonderful Launcher 检查目前机器；启动器原生修复、任务日誌和執行階段检查会集中在一起。credits 只用於图片生成和按量工具。
下载 Wonderful Launcher查看 credits 方案这篇文件解決了你的問题嗎？
你的回饋会帮助我们優先補強真實 ComfyUI 排障文件。