Custom nodes import failed 解决：自定义节点加载失败

先看控制台日志，再区分依赖缺失、版本不兼容和路径问题。

一句话结论

能从控制台日志定位具体插件和具体错误。

这篇解决什么问题

Custom nodes import failed 是自定义节点加载失败的总提示。根因可能是依赖缺失、插件版本不兼容、目录错误或 Python 版本问题。

如果你是第一次接触 ComfyUI，建议不要跳步。先把最小流程跑通，再安装插件、导入复杂工作流或追求高分辨率。ComfyUI 的大多数问题都可以通过“看控制台日志、确认目录、确认版本、降低参数”这四件事定位。

适合谁

• 刚开始使用 ComfyUI，需要一篇可以照着做的教程。
• 已经遇到相关报错，但不知道该先检查哪一步。
• 想把安装、模型、插件、工作流整理成可复查流程的用户。

准备条件

• 打开启动控制台。
• 知道 custom_nodes 目录位置。

自定义节点加载失败时，真正有用的信息通常在启动窗口的 Traceback 里。先找插件目录，再看是缺依赖、版本不兼容，还是目录层级放错。

操作步骤

1. 不要只看网页弹窗，回到控制台查看完整 Traceback。
2. 定位报错路径，确认是哪个插件目录。
3. 如果是 No module named，按依赖缺失处理。
4. 如果是 cannot import name，多半是插件或 ComfyUI 版本不兼容，先更新插件和 ComfyUI。
5. 如果是路径错误，检查目录是否多套一层。
6. 暂时不用的故障插件可以移出 custom_nodes，先恢复主程序启动。

判断问题属于哪一类

• 如果页面打不开，先看启动窗口是否还在运行，以及端口是否正确。
• 如果节点是红色，优先处理缺失自定义节点或插件加载失败。
• 如果模型下拉框为空，优先检查模型类型和放置目录。
• 如果开始生成后失败，优先看显存、模型版本和具体报错节点。
• 如果更新后才坏，优先考虑插件版本不兼容，必要时回退或临时移除插件。

常见错误

• 一次性安装很多插件，出错后不知道是谁导致。
• 删除 ComfyUI 本体而不是移除故障插件。
• 忽略插件 README 的版本要求。

验证是否成功

• 控制台不再显示 import failed。
• 节点搜索能找到该插件节点。

如果仍然失败

请把控制台里从 Traceback 开始到最后一行的完整报错保存下来，同时记录：ComfyUI 版本、启动方式、显卡型号、显存容量、使用的模型文件名、刚安装过哪些插件。不要只截网页上的红色提示，因为真正有用的信息通常在启动窗口里。

如果你在本站提交反馈，登录状态下会自动附带 user_id，方便后续追踪同一个用户遇到的连续问题；未登录也可以匿名提交。

下一步推荐

• 新手路线：/topics/comfyui-beginner/
• 报错排查：/topics/comfyui-errors/
• 模型基础：/topics/model-basics/
• 插件安装：/topics/must-have-plugins/

更新记录

• 2026-05-12：扩写为正式教程，补充操作步骤、常见错误和验证清单。