ComfyUI 故障排查决策树
按顺序判断 ComfyUI 故障属于启动崩溃、插件冲突、依赖错误还是模型问题。
测试环境
- 操作系统： Windows 10 / 11
- Launcher： Wonderful Launcher v1.x
- ComfyUI： Portable / Managed install
- Python： 3.11+
- CUDA / Torch： CUDA 12.x / Torch 2.x
- 最后验证： 2026-05-19
ComfyUI 出问题时，最常见的误区是靠猜。 这篇给你一个顺序明确的判断树，先分清是基础环境坏了、插件没装好、依赖冲突，还是模型文件本身有问题。
判断 1：ComfyUI 能不能启动？
先检查 http://127.0.0.1:8188/system_stats 是否能返回数据。
- 能返回：说明 ComfyUI 核心基本已启动，继续看判断 2。
- 不能返回：先修基础环境，不要急着装插件。
判断 2：工作流里是不是出现了红节点或缺失节点？
导入工作流后，如果有节点变红或直接缺失，先别急着装一堆包。
第 1 步：它是不是前端节点？
下面这些通常不需要后端注册，出现缺失也不一定是真问题：
NoteRerouteMarkdownNoteFast Groups Muter (rgthree)Fast Groups Bypasser (rgthree)PrimitiveNodeGetNodeSetNode- 任何以
workflow>开头的本地封装节点
如果就是这些，通常可以先忽略。
第 2 步：插件装了吗？
检查对应插件目录是否真的存在于 custom_nodes/。
- 目录不存在：先安装正确插件，见 安装自定义节点
- 目录存在但节点还是没出现：继续看判断 3
判断 3：插件目录在，但节点还是不工作
这时重点不是“继续安装依赖”，而是先看启动日志里有没有 IMPORT FAILED。
-
缺少 Python 包导致导入失败：这是依赖问题
不要直接无脑执行
pip install -r requirements.txt。- 先确认当前激活的是哪个 Python 环境：
where python或which python - 打开
requirements.txt，看它有没有钉死 torch、numpy、opencv 等关键版本 - 能只装缺的包就只装缺的包：
pip install <package-name> - 安装后运行
pip check，确认没有引入新的冲突
更复杂的情况看 依赖冲突。
- 先确认当前激活的是哪个 Python 环境：
-
是代码层错误，例如
AttributeError，或者导入 ComfyUI 内部 API 时报错：这是源码兼容性问题- 说明插件版本和你当前的 ComfyUI 版本不兼容
- 应优先更新插件，或者做最小补丁
- 这不是单纯缺依赖，不要继续盲目装包
-
没有导入失败，但节点名称对不上：这是节点改名问题
- 可能插件更新后把旧节点名换掉了
- 例如
InpaintCrop改成InpaintCropImproved - 解决方式是更新工作流节点名，或者在插件
__init__.py里加兼容别名
判断 4：节点存在，但执行时报错
节点不是红的，也能加载出来，但一运行工作流就报错。
先看错误信息属于哪一类：
-
报错指向模型文件路径，例如 checkpoint、LoRA、ControlNet、SAM、ONNX 这是模型问题，不是插件问题。
- 下载对应模型，并放到正确目录
- 参考 下载模型
- 不要为了这类错误去改插件或重装依赖
-
报错提到 Python 模块或函数 这通常还是依赖或兼容性问题。
- 先查包是否真的装了：
pip show <package_name> - 再看版本是否匹配
- 先查包是否真的装了：
判断 5：日志里出现 “Starting server”，但界面还是打不开
如果控制台已经打印：
Starting serverTo see the GUI go to: http://127.0.0.1:8188
但浏览器一直卡在加载界面，这 不等于 ComfyUI 没启动。 更常见的是：核心已经起来了，但启动后的某个环节把前端卡住了。
常见原因：
| 原因 | 现象 | 处理方式 |
|---|---|---|
| ComfyUI-Manager 拉远程数据 | 日志反复访问 raw.githubusercontent.com | 把 Manager 切到离线模式，在 config.ini 里设 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 |
验证方式：
- 直接访问
http://127.0.0.1:8188/system_stats如果能打开，说明核心服务没问题，问题更可能在前端或启动后插件。 - 看
python.exe进程是不是还活着 如果已经退出，就回到最后一条报错日志看真正的崩点。
判断 6：看起来能用，但环境越来越不稳定
ComfyUI 能启动，工作流也能跑，但总是随机崩、包冲突、插件互相污染。
先运行：
pip check但注意，pip check 看到报错并不等于每条都必须修。
| 类型 | 含义 | 应对方式 |
|---|---|---|
| 硬阻塞 | 核心包彼此不兼容，例如 torch 版本错位 | 必须优先修 |
| 软漂移 | 例如某插件要求 numpy>=2，但你为了稳定停在 numpy 1.26.4 | 记录下来，只要运行稳定可以先不动 |
| 可选依赖 | 某插件声明了你当前工作流根本没用到的包 | 不要急着安装，可能会把环境越修越坏 |
快速对照：错误类型 -> 问题类别
| 错误表现 | 问题类别 | 应该怎么做 |
|---|---|---|
| 红节点 / 缺失节点 | 插件没装好，或导入失败 | 安装插件，检查导入日志 |
日志出现 IMPORT FAILED | 依赖或兼容性问题 | 检查 pip install、版本冲突 |
ModuleNotFoundError | 缺少 Python 包 | 安装对应包 |
AttributeError 指向 ComfyUI 内部 API | 插件和当前 ComfyUI 版本不兼容 | 更新插件或打补丁 |
FileNotFoundError 指向模型路径 | 模型文件缺失 | 下载并放到正确目录 |
CUDA out of memory | 显存不够 | 用 --lowvram、更小模型或更低分辨率 |
| 浏览器空白 / 启动画面卡住 | 启动后阶段被阻塞 | 检查联网插件、切离线模式 |
torch.cuda.is_available() 为 False | PyTorch 和 CUDA 不匹配 | 重装正确的 PyTorch CUDA 版本 |
相关文档
还卡住？
如果你按这棵树查过一遍还是没修好，先试试 Wonderful Launcher。它可以先帮你恢复环境，再继续细查根因。
参考来源
如果这个问题已经碰到你真实在用的 ComfyUI 环境，先用 Wonderful Launcher 接管和检查当前机器，再配合文档决定怎么修。
下载 Wonderful LauncherDid this fix your issue?
Your answer helps prioritize verified ComfyUI repairs.