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 出现问题时，最常见的错误做法是凭感觉猜测。本指南基于对数百个实际环境的经验，提供一套结构化的决策树来系统诊断问题。
本页适用场景
当你尚不清楚自己属于哪类故障时，使用本页：
- 启动失败
- 插件导入失败
- 依赖冲突
- 节点缺失
- 模型路径/运行时问题
如果你已经知道具体的报错字符串，对应的专项页面通常更快。本页是在故障类别本身尚不明确时的总入口。
决策 1：ComfyUI 能否启动？
检查 http://127.0.0.1:8188/system_stats 是否能返回数据。
- 能 → ComfyUI 核心正常运行。进入决策 2。
- 不能 → 先修复基础环境，暂时不要安装插件。
决策 2：工作流显示节点缺失
导入工作流后，部分节点显示为红色或缺失。
第一步： 是否是纯前端节点？
以下节点无需后端注册，应忽略：
Note、Reroute、MarkdownNoteFast Groups Muter (rgthree)、Fast Groups Bypasser (rgthree)PrimitiveNode、GetNode、SetNode- 任何以
workflow>开头的节点（工作流本地包装器）
如果是上述节点 → 不是真正的问题，忽略即可。
第二步： 插件是否已安装？
检查 custom_nodes/ 目录中是否存在对应的插件文件夹。
- 插件文件夹不存在 → 安装正确的插件。参见 自定义节点。
- 插件文件夹存在但节点仍缺失 → 进入决策 3。
如果节点缺失是主要症状，还可参考：
决策 3：插件存在但节点无法使用
插件目录存在，但节点仍未出现在 ComfyUI 中。
检查启动日志中是否有 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、内部 API 的 ImportError） → 这是源码兼容性问题。
- 插件代码与当前 ComfyUI 版本不兼容
- 更新插件（
git pull）或应用最小化补丁 - 这不是依赖问题——不要继续安装包
-
没有导入失败，但节点名称不匹配 → 这是节点名称迁移问题。
- 插件更新后重命名了节点
- 示例：
InpaintCrop→InpaintCropImproved - 解决方案：更新工作流以使用新节点名称，或在插件的
__init__.py中添加别名。参见 插件管理——处理节点名称变更
如果主要问题是反复出现 IMPORT FAILED，参考：
决策 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 |
验证步骤：
- 能否直接访问
http://127.0.0.1:8188/system_stats？如果可以 → 核心正常，问题在前端或启动后的插件 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 显存不足 | 使用 --lowvram、更小的模型或降低分辨率。参见 GPU 兼容性 |
| 浏览器空白 / 启动画面卡住 | 启动后阻塞 | 检查网络类插件，设置离线模式 |
torch.cuda.is_available() 返回 False | PyTorch CUDA 版本不匹配 | 使用 Torch Missing 选择正确 wheel |
相关指南
- 工作流环境搭建 — 复杂环境的完整 7 阶段标准操作流程
- 插件管理 — 节点映射、仓库迁移、Git LFS 陷阱
- 依赖冲突 — Python 依赖解析深度解析
- 常见问题 — 高频问题快速修复
- GPU 兼容性 — 完整的驱动、CUDA 和 PyTorch 版本矩阵
仍然卡住了？
如果你已经按照这棵决策树排查仍无法解决问题，可以先尝试 Wonderful Launcher。它免费，并且能自动恢复环境。
参考资料来源
先按上面的步驟定位根因。还卡住时，可以下载 Wonderful Launcher 检查目前机器；启动器原生修复、任务日誌和執行階段检查会集中在一起。credits 只用於图片生成和按量工具。
下载 Wonderful Launcher查看 credits 方案这篇文件解決了你的問题嗎？
你的回饋会帮助我们優先補強真實 ComfyUI 排障文件。