ComfyUI 启动失败?更快定位和恢复的方法
修复由插件损坏、依赖漂移、缺包和脆弱环境引起的 ComfyUI 启动失败。
如果这个问题已经碰到你真实在用的 ComfyUI 环境,先用 Wonderful Launcher 接管和检查当前机器,再配合文档决定怎么修。
下载 Wonderful Launcher测试环境
- 操作系统: 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 根本起不来,不要把它当成一个普通“安装失败”问题。
大多数启动失败,真正原因都出在 原本能跑的环境后来发生了变化:
- 某个插件改了关键包
- 某个二进制 wheel 不再匹配当前运行时
- Torch 或 CUDA 漂了
- 某个 helper 文件、bootstrap 步骤被删了、被拦了,或者被杀毒软件隔离了
所以真正该问的不是:
“ComfyUI 怎么启动?”
而是:
“上一次还能用,到现在不能用,中间到底变了什么?”
当前最常见的启动失败类型
结合 launcher 遥测和真实 ComfyUI 排障,下面这些启动失败模式最值得优先覆盖:
| 模式 | 通常意味着什么 | 最该看的下一页 |
|---|---|---|
No module named 'triton' | 核心或加速依赖漂移 | 修 triton |
No module named 'sageattention' | 可选加速包不匹配 | 修 sageattention |
No module named 'llama_cpp' | 自定义节点依赖缺失 | 修 llama_cpp |
No module named 'insightface' | 人脸/身份类工作流依赖缺失 | 修 insightface |
No module named 'onnx' 或 onnxruntime | ONNX 节点依赖缺失 | 修 onnx / onnxruntime |
CUDA out of memory | 显存不足或工作流过大 | 修 CUDA OOM |
| 下载资源包失败 | 安装/部署链路在完整启动前就失败 | 修资源包下载失败 |
| 安装 ComfyUI-Manager 失败 | 首次部署卡在插件管理器安装阶段 | 修 ComfyUI-Manager 部署失败 |
如果你的报错和这里某一条几乎完全一致,优先先跳到对应窄页,不要一上来就做整套重装。
“启动失败” 通常表现成什么
常见表现包括:
- 程序窗口一闪而过或打开后马上关闭
- ComfyUI 永远起不到 UI
- 终端在服务启动前就出现 import error
- ComfyUI Desktop 卡在 bootstrap 阶段
- 启动器提示缺少某个 helper 文件
第 1 步:先把启动失败归类
动手前,先把问题放进下面某一类。
A 类:启动阶段的 Python 导入失败
例如:
ModuleNotFoundError: No module named 'sqlalchemy'
comfyui-frontend-package is not installed
ModuleNotFoundError: No module named 'cv2'
ModuleNotFoundError: No module named 'onnxruntime'这通常表示包缺失或包已损坏。 如果缺的是 ComfyUI 核心启动路径里的包,就不要把它当成“单个插件问题”,直接看 逐个修复 ComfyUI Portable 依赖损坏。
B 类:核心运行时漂移
例如:
Torch not compiled with CUDA
CUDA is not available
AttributeError: module 'torch' has no attribute '...'这通常意味着 Torch、CUDA 或其他关键依赖被改坏了。
C 类:插件导入链把启动卡死
例如:
- 一个插件失败后,启动开始变得不稳定
- 装完一个插件后,很多插件同时开始报错
- 环境之前能跑,后来才坏
D 类:bootstrap 或 launcher helper 文件异常
例如:
- 某个 helper 可执行文件缺失
- 杀毒软件把文件隔离了
- ComfyUI Desktop 或其他 Launcher 无法完成启动链
如果你看到的是 bootstrapper 或 helper 文件缺失,先查杀毒软件和安装目录完整性,不要先重装。
一个更省时间的排查顺序
当环境是“原来能跑,现在不能跑”时,最稳的顺序通常是:
- 找到第一条真实启动错误
- 判断它属于 核心运行时、插件依赖 还是 部署/启动链
- 只修最窄的第一阻塞
- 重启,再看新的第一条错误
- 只有当环境已经没有稳定第一阻塞时,才考虑重装
这样可以避免把一个依赖损坏问题直接扩大成整套环境重建。
第 2 步:找“第一条真实错误”,不是最后一个表面症状
很多人只会复制最后看到的一行,但最后一行不一定是根因。
你应该在启动日志里往前找:
- 第一条
IMPORT FAILED - 第一条
ModuleNotFoundError - 第一条 Torch / CUDA / DLL load 错误
- 第一条 helper / bootstrap 文件缺失
后面的报错很可能只是连锁反应。
第 3 步:按类别做最小恢复动作
如果是缺包
只安装缺失的那个包,或者安装引入该问题的插件依赖。
不要上来就做大范围升级,例如:
pip install -U everything这种操作经常会把一个启动失败扩成三个。
如果第一条错误是 No module named 'sqlalchemy',先看 SQLAlchemy 启动修复。
如果修完一个包后,马上暴露出下一个核心缺包,就切到 portable 依赖修复 runbook。
如果是 Torch 或 CUDA 漂移
把它当成 核心运行时问题,不要先当成插件问题。
先把核心运行时修稳,再回头验证插件。
常见迹象:
- ComfyUI 突然退回 CPU 路线
- CUDA 原来能用,装完节点后突然不能用
xformers、onnxruntime或其他包拉进了不匹配的版本
如果是 helper 或 bootstrap 文件缺失
优先检查:
- 杀毒软件隔离记录
- 安装目录是否完整
- 启动器依赖文件是否还在
具体示例可以看 Bootstrapper Missing (watchdog_bootstrapper_missing)。
第 4 步:别太早掉进“重装陷阱”
重装看起来干净,但如果你机器上已经有这些资产,它往往是最贵的方案:
- 已下载的模型
- 现成工作流
- 仍然需要的自定义节点
- 你过去已经摸索好的环境修法
只有在下面这些情况,重装才开始变得合理:
- 核心运行时已经坏到没法推理
- helper 文件缺失且无法安全恢复
- 反复修包已经让环境继续漂移
只要环境还有恢复空间,优先先保住现有资产。
为什么启动失败经常发生在装插件之后
很多人忽略的是这个模式:
- ComfyUI 原本正常
- 装了一个插件,或者更新了插件
- 某个 requirements 改了核心包
- 下一次启动直接失败
所以“启动问题”和“插件问题”很多时候其实是同一件事,只是你从两个不同阶段看到了它。
有些“启动失败”其实是“部署失败”
很多用户会把首次安装阶段的问题也描述成“ComfyUI 启动失败”,但实际上 ComfyUI 可能还没有进入稳定可运行状态。
这类情况往往更早:
- 资源包还没下载完就失败
- ComfyUI-Manager 没 clone 成功
- helper 文件或 bootstrap 可执行文件被拦了
如果你连第一次稳定启动都还没做到,先看这些页面,再决定要不要修 Python 包:
比散装 shell 命令更好的恢复路径
真正烦人的往往不是启动失败本身,而是修复路径:
- 读 traceback
- 试一个
pip install - 重启
- 再遇到另一个新错误
- 又改一个包
- 开始怀疑是不是该重装
Wonderful Launcher 就是为这种阶段设计的。
它更适合这些场景:
- ComfyUI Desktop 因插件变脆
- portable 环境随着时间越来越漂
- 你想保留现有模型、工作流和设置,而不是从零开始
一个实用判断
如果这台机器上已经有工作流、模型或付费产出要保,优先优化“恢复质量”,把重装放到最后。
什么时候该从自救切到专家协助
如果出现下面这些情况,直接升级处理通常更省时间:
- 启动失败发生在多轮插件修复之后
- Torch、CUDA、插件导入一起坏
- 你已经搞不清到底是哪次改动导致的
- 这是工作机、工作室机器,停机成本很高
Wonderful Launcher 能帮你什么
Wonderful Launcher 更适合 环境已经开始脆弱 的阶段: 它强调恢复、隔离和减少漂移,而不是单纯再跑一串安装命令。
相关文档
- 逐个修复 ComfyUI Portable 依赖损坏
- ComfyUI 提示 No module named 'sqlalchemy'
- ComfyUI Plugin Import Failed 怎么修
- ComfyUI 依赖冲突
- ComfyUI Reconnecting Error
- ComfyUI 常见问题
- 故障排查决策树
想走更短路径?
如果你想走更引导式、更偏恢复的路径,先从 Wonderful Launcher 开始。 如果环境仍然卡住,再直接走 专家协助。
参考来源
如果这个问题已经碰到你真实在用的 ComfyUI 环境,先用 Wonderful Launcher 接管和检查当前机器,再配合文档决定怎么修。
下载 Wonderful Launcher如果这个问题已经碰到你真实在用的 ComfyUI 环境,先用 Wonderful Launcher 接管和检查当前机器,再配合文档决定怎么修。
下载 Wonderful LauncherDid this fix your issue?
Your answer helps prioritize verified ComfyUI repairs.