Custom nodes import failed 解决：自定义节点加载失败
排查 ComfyUI custom nodes import failed 自定义节点加载失败，按控制台日志、依赖缺失、Python 环境、版本兼容和路径错误逐项处理。
一句话结论
能从控制台日志定位具体插件和具体错误。
这篇解决什么问题
Custom nodes import failed 是自定义节点加载失败的总提示。根因可能是依赖缺失、插件版本不兼容、目录错误或 Python 版本问题。它不是一个“单点故障”，而是一个总入口。
如果你看到的是 No module named xxx，直接跳到依赖缺失；如果是 cannot import name、type object has no attribute、failed to import，更像版本冲突或 API 变化。Impact Pack、AnimateDiff 这类大插件尤其常见。
适合谁
- 刚开始使用 ComfyUI，需要一篇可以照着做的教程。
- 已经遇到相关报错，但不知道该先检查哪一步。
- 想把安装、模型、插件、工作流整理成可复查流程的用户。
准备条件
- 打开启动控制台。
- 知道 custom_nodes 目录位置。
这张图模拟真实启动控制台里的 Traceback 位置：先找 custom_nodes/<插件名>，再看最后一行是缺依赖、版本不兼容，还是目录层级放错。网页提示只是结果，控制台日志才是根因。
这张流程图补充排查顺序。自定义节点加载失败时，真正有用的信息通常在启动窗口的 Traceback 里。
先分清是哪一层出问题
- 网页弹窗只告诉你“坏了”，不告诉你根因。
- 控制台最后几行告诉你是哪个插件、哪个模块、哪个 Python 环境。
- 先找
custom_nodes/<插件名>，再找No module named或cannot import name。
上图把最常见的排查顺序压缩成了 4 步：先记录缺失模块，再定位插件目录，再装依赖，最后重启验证。不要一上来就删整套 ComfyUI。
这张图把常见根因分成三类：缺依赖、版本冲突、路径错误。先分流，再动手，不要把所有插件一起更新。
操作步骤
- 不要只看网页弹窗，回到控制台查看完整 Traceback。
- 定位报错路径，确认是哪个插件目录。
- 如果是 No module named，按依赖缺失处理。
- 如果是 cannot import name，多半是插件或 ComfyUI 版本不兼容，先更新插件和 ComfyUI。
- 如果是路径错误，检查目录是否多套一层。
- 暂时不用的故障插件可以移出 custom_nodes，先恢复主程序启动。
- 如果是便携版，优先在 ComfyUI 自带 Python 里装依赖，而不是系统 Python。
便携版怎么装依赖
- 便携版通常用
python_embeded/python.exe。 - 先进入出错插件目录，再执行
python -m pip install -r requirements.txt。 - 如果插件没有 requirements.txt，就看 README 里列的额外依赖。
- 装完一定要重启 ComfyUI。
判断问题属于哪一类
- 如果页面打不开，先看启动窗口是否还在运行，以及端口是否正确。
- 如果节点是红色，优先处理缺失自定义节点或插件加载失败。
- 如果模型下拉框为空，优先检查模型类型和放置目录。
- 如果开始生成后失败，优先看显存、模型版本和具体报错节点。
- 如果更新后才坏，优先考虑插件版本不兼容，必要时回退或临时移除插件。
常见错误
- 一次性安装很多插件，出错后不知道是谁导致。
- 删除 ComfyUI 本体而不是移除故障插件。
- 忽略插件 README 的版本要求。
- 只在系统 Python 里装包，ComfyUI 便携版还是找不到。
- 只装缺失的那个包，漏掉 requirements.txt 里的其他依赖。
如果还是失败
先判断是不是版本冲突：插件更新了，但 ComfyUI 本体没更新；或者 ComfyUI 更新了，旧插件还在。遇到 cannot import name、type object has no attribute 之类的错误，先更新插件和 ComfyUI，再试一次。
验证是否成功
- 控制台不再显示 import failed。
- 节点搜索能找到该插件节点。
如果仍然失败
请把控制台里从 Traceback 开始到最后一行的完整报错保存下来，同时记录：ComfyUI 版本、启动方式、显卡型号、显存容量、使用的模型文件名、刚安装过哪些插件。不要只截网页上的红色提示，因为真正有用的信息通常在启动窗口里。
如果你在本站提交反馈，登录状态下会自动附带 user_id，方便后续追踪同一个用户遇到的连续问题；未登录也可以匿名提交。
下一步推荐
- 新手路线：/topics/comfyui-beginner/
- 报错排查：/topics/comfyui-errors/
- 模型基础：/topics/model-basics/
- 插件安装：/topics/must-have-plugins/
更新记录
- 2026-05-12：扩写为正式教程，补充操作步骤、常见错误和验证清单。