故障排除决策树

当 ComfyUI 出问题时，最常见的错误就是靠猜。本指南提供了一个结构化的决策树，基于数百个环境的实际经验来诊断问题。

判断 1：ComfyUI 能否启动？

检查 http://127.0.0.1:8188/system_stats 是否返回数据。

• 是 → ComfyUI 核心正常工作。前往判断 2。
• 否 → 先修复基础环境。不要安装插件。
  • 检查：Python 是否可用？PyTorch 是否安装了 CUDA 支持？是否使用了正确的 run_nvidia_gpu.bat？
  • 参见常见问题获取具体错误修复方案
  • 查看 GPU 兼容性了解驱动和 CUDA 版本匹配
  • 查阅安装指南：桌面应用、便携版、手动安装

判断 2：工作流显示缺失节点

导入工作流后，部分节点显示为红色或缺失。

步骤 1： 是否为纯前端节点？

以下节点不需要后端注册，应该忽略：

• Note、Reroute、MarkdownNote
• Fast Groups Muter (rgthree)、Fast Groups Bypasser (rgthree)
• PrimitiveNode、GetNode、SetNode
• 以 workflow> 开头的节点（工作流内部包装器）

如果是以上节点 → 不是真正的问题。 忽略即可。

步骤 2： 插件是否已安装？

检查 custom_nodes/ 中是否存在对应的插件文件夹。

• 插件文件夹不存在 → 安装正确的插件。参见自定义节点。
• 插件文件夹存在但节点仍然缺失 → 前往判断 3。

判断 3：插件存在但节点不工作

插件目录在那里，但节点仍然没有出现在 ComfyUI 中。

检查启动日志中的 IMPORT FAILED。

• 因缺少 Python 包导致导入失败 → 这是依赖问题。

  • 在插件文件夹中运行 pip install -r requirements.txt
  • 使用 pip check 检查版本冲突
  • 参见依赖冲突了解高级解决方案

• 因代码错误导致导入失败（AttributeError、内部 API 的 ImportError） → 这是源码兼容性问题。

  • 插件代码与你的 ComfyUI 版本不兼容
  • 更新插件（git pull）或应用最小化补丁
  • 这不是依赖问题 — 不要继续安装包

• 没有导入失败，但节点名称不匹配 → 这是节点名称迁移。

  • 插件更新并重命名了节点
  • 例如：InpaintCrop → InpaintCropImproved
  • 解决方案：更新工作流以使用新的节点名称，或在插件的 __init__.py 中添加别名。参见插件管理 — 处理节点名称变更

判断 4：节点存在但执行时报错

节点正常显示（不是红色），但运行工作流时抛出错误。

检查错误信息：

• 错误提到模型文件路径（checkpoint、LoRA、ControlNet、SAM、ONNX 等） → 这是模型问题，不是插件问题。

  • 下载所需模型并放置在正确的文件夹中
  • 参见下载模型
  • 不要因此修改插件或依赖

• 错误提到 Python 模块或函数 → 可能仍然是依赖或兼容性问题。

  • 检查所需包是否已安装：pip show <package_name>
  • 检查版本兼容性

判断 5：ComfyUI 日志显示 "Starting server" 但界面无法加载

控制台显示 Starting server 和 To see the GUI go to: http://127.0.0.1:8188，但浏览器一直停在加载界面。

这并不意味着 ComfyUI 启动失败。 核心已经启动，但启动后的某些操作阻塞了界面。

常见原因：

原因	症状	修复方法
ComfyUI-Manager 拉取远程数据	日志显示反复尝试连接 raw.githubusercontent.com	在 config.ini 中设置 Manager 为离线模式：network_mode = offline
BizyAir API 重试循环	日志显示反复出现 Failed to cache trd models 和 Invalid API key	在启动脚本中设置 BIZYAIR_SKIP_TRD_MODEL_CACHE=1
大型工作流 + Node 2.0 渲染	CPU 使用率飙升，浏览器变得无响应	在 rgthree 设置中禁用 Node 2.0 渲染
编码错误	日志中出现 UnicodeDecodeError	在环境变量中添加 PYTHONUTF8=1 和 PYTHONIOENCODING=utf-8

验证步骤：

1. 能否直接访问 http://127.0.0.1:8188/system_stats？如果可以 → 核心正常，问题出在前端或启动后的插件
2. python.exe 进程是否还活着？如果已终止 → 检查崩溃前日志中的最后一条错误

判断 6：一切正常但环境感觉不稳定

ComfyUI 运行正常，工作流能加载，但会出现随机崩溃或包冲突。

运行 pip check 查找依赖冲突。

重要提示： 在安装了大量插件的 ComfyUI 环境中，pip check 通常会显示警告。并非所有警告都是真正的问题：

类型	含义	处理方式
硬性阻塞	核心包不兼容（如 torch 版本不匹配）	立即修复
软性偏移	插件声明需要 numpy>=2 但你为保持稳定使用 numpy 1.26.4	记录下来，如果运行正常则不修复
可选依赖	插件需要一个你的工作流不使用的包	不要安装 — 可能会破坏环境稳定性

快速参考：错误 → 分类

错误类型	分类	处理方法
红色/缺失节点	插件未安装或导入失败	安装插件，检查导入日志
日志中出现 IMPORT FAILED	依赖或兼容性问题	检查 pip install、版本冲突
ModuleNotFoundError	缺少 Python 包	pip install <package>
ComfyUI 内部 API 的 AttributeError	插件与 ComfyUI 版本不兼容	更新插件或打补丁
模型路径的 FileNotFoundError	缺少模型文件	下载模型
CUDA out of memory	GPU VRAM 不足	使用 --lowvram、更小的模型或更低的分辨率。参见 GPU 兼容性
空白浏览器 / 卡在启动画面	启动后阻塞	检查网络插件，设置离线模式
torch.cuda.is_available() 返回 False	PyTorch CUDA 不匹配	重新安装正确 CUDA 版本的 PyTorch

相关指南

• 工作流环境搭建 — 复杂环境的完整七阶段 SOP
• 插件管理 — 节点映射、仓库迁移、Git LFS 陷阱
• 依赖冲突 — 深入了解 Python 依赖解析
• 常见问题 — 常见问题的快速修复
• GPU 兼容性 — 完整的驱动、CUDA 和 PyTorch 版本对照表

仍然无法解决？

如果你按照这个决策树操作后仍无法解决问题，预约远程修复服务。我们的专家每天都在处理这些诊断流程。