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 startup failed、ComfyUI won't start 或 ComfyUI fails before Starting server，请不要将其当作普通安装问题来处理。首先找到第一个真正的启动错误，然后跳转到对应的专项修复页面。
大多数启动失败发生在原始安装后环境发生了变化：
- 某个插件修改了关键包
- 二进制包与运行时不再匹配
- Torch 或 CUDA 版本发生漂移
- 某个辅助文件或引导步骤被删除、阻止或隔离
这意味着真正的问题不仅仅是 "我该如何启动 ComfyUI？"
真正的问题是：
"在最后一次正常运行状态和当前损坏状态之间，发生了什么变化？"
快速答案
在终端或启动器日志中读取第一条错误追溯信息。如果它指向某个缺失的模块，请使用对应的缺失包页面。如果涉及 Torch/CUDA，请先修复运行时。如果在 ComfyUI 安装之前就已失败，请将其视为部署/引导问题，而非 Python 包问题。
搜索意图分流
| 用户搜索或看到的内容 | 更合适的下一个页面 |
|---|---|
ComfyUI startup failed 但尚无具体错误追溯 | 留在本页，对第一个错误进行分类 |
ModuleNotFoundError: No module named ... | ComfyUI 中的 No module named 错误 |
Torch not compiled with CUDA enabled | Torch CUDA 修复指南 |
页面打开后出现 failed to fetch server logs | 无法获取服务器日志 |
页面卡在 Reconnecting... | ComfyUI 重连错误 |
| 首次运行部署失败 | 资源包下载失败 |
最具参考价值的启动失败模式
根据真实的启动器遥测数据和 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 始终无法进入界面
- 终端在服务器启动前就显示导入错误
- ComfyUI Desktop 在引导过程中卡住
- 启动器提示某个必需的辅助文件缺失
第一步：对启动失败进行分类
在修复任何问题之前，将失败归入以下类别之一。
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 便携版依赖而不重装 Torch，而非将其当作单个自定义节点问题来处理。
B 类：核心运行时漂移
示例：
Torch not compiled with CUDA
CUDA is not available
AttributeError: module 'torch' has no attribute '...'这通常意味着 Torch、CUDA 或其他关键依赖发生了变化。
C 类：插件导入链阻塞启动
示例：
- 某个自定义节点失败，导致启动变得不稳定
- 安装某个插件或更新后，许多插件相继失败
- 环境在安装插件或执行更新之前是正常运行的
D 类：引导程序或启动器辅助文件失败
示例：
- 某个辅助可执行文件缺失
- 杀毒软件隔离了某个文件
- ComfyUI Desktop 或其他启动器无法完成启动序列
如果你看到引导程序或辅助文件缺失的提示，请在重新安装任何内容之前，先检查杀毒软件是否将其删除。
最节省时间的快速排查顺序
当机器之前可以正常运行但现在无法运行时，以下顺序通常是最安全的：
- 读取第一个真实的启动错误
- 判断它属于核心运行时、插件依赖还是部署/引导问题
- 优先修复最小范围的阻塞因素
- 重启并重新检查新的第一个错误
- 仅在环境不再有稳定的第一个阻塞因素时才考虑重装
这样可以避免将一个损坏的依赖演变成完整的环境重置。
第二步：找到第一个真实错误，而非最后可见的症状
用户通常会复制他们看到的最后一行。但那未必是真正的原因。
正确做法是扫描启动日志，找到最早的失败：
- 第一个
IMPORT FAILED - 第一个
ModuleNotFoundError - 第一个 Torch、CUDA 或 DLL 加载错误
- 第一个缺失的辅助文件或引导文件
其后的所有内容可能只是连带影响。
第三步：使用与类别匹配的最小恢复操作
如果某个包缺失
仅安装缺失的包或引入该包的插件所需的依赖项。
不要一开始就执行大范围升级。先安装第一个真实阻断项对应的包，或者安装引入该依赖的插件 requirements；广谱升级往往会把一个启动失败变成三个。
如果第一个错误是 ModuleNotFoundError: No module named 'sqlalchemy'，请阅读 SQLAlchemy 启动修复指南。如果修复一个包后又暴露出另一个核心缺失包，请切换到便携版依赖修复手册。
如果 Torch 或 CUDA 发生漂移
将其视为核心运行时问题，而非插件问题。
先修复核心运行时，再重新测试插件导入。
常见迹象：
- ComfyUI 意外回退到 CPU 模式
- CUDA 之前正常，在安装某个自定义节点后停止工作
xformers、onnxruntime或其他包拉取了不匹配的构建版本
如果辅助文件或引导文件缺失
请检查：
- 杀毒软件隔离历史记录
- 安装目录完整性
- 启动器的辅助文件是否仍然存在
具体示例请参见引导程序缺失 (watchdog_bootstrapper_missing)。
第四步：避免陷入重装陷阱
重装看起来很干净，但如果你已经拥有以下内容，重装往往是代价最高的选择：
- 已下载的模型
- 可用的工作流
- 仍然需要的自定义节点
- 特定于环境的修复（重装后需要重新发现）
仅在以下情况下才考虑重装：
- 核心运行时损坏程度已无法分析
- 辅助文件缺失且无法安全恢复
- 多次包修复尝试导致了更大范围的漂移
如果环境仍可恢复，请优先尝试保留它。
为什么启动失败往往发生在插件操作之后
这是许多用户忽视的规律：
- ComfyUI 正常启动
- 安装或更新了某个插件
- 某个依赖项修改了核心包
- 下次启动时失败
这就是为什么启动调试和插件调试往往是从两个不同角度看到的同一个问题。
当启动失败实际上是部署失败时
有些用户将首次安装问题描述为"ComfyUI 启动失败"，即使 ComfyUI 从未达到稳定的安装状态。
这通常意味着失败发生得更早：
- 资源包未完成下载
- ComfyUI-Manager 未成功克隆
- 某个辅助文件或引导可执行文件被阻止
如果启动器在你首次成功启动之前就已失败，请先检查以下页面，再去修复 Python 包：
比零散 shell 命令更好的恢复路径
令人沮丧的不只是启动失败本身，还有修复过程：
- 读取一条错误追溯
- 尝试
pip install - 重启
- 遇到另一个不同的失败
- 修补另一个包
- 开始怀疑是否应该直接重装
Wonderful Launcher 正是为这个阶段而设计的。
当出现以下情况时，它为用户提供更注重恢复的路径：
- ComfyUI Desktop 在安装插件后变得脆弱
- 便携版环境随时间发生漂移
- 你希望保留现有资产，而不是从零重建
一条实用原则
如果机器上已经有你关心的工作流、模型或付费产出，请优先追求恢复质量，仅将重装作为最后手段。
何时停止盲目尝试
在以下情况下，请先停下来保存证据，不要继续盲目安装包：
- 启动失败发生在多次插件修复尝试之后
- Torch、CUDA 和插件导入同时失败
- 你不再确定是哪个包或哪次变更导致了问题
- 环境属于工作室或工作机器，停机成本很高
Wonderful Launcher 如何提供帮助
Wonderful Launcher 能够自动检测并修复此问题。它安全地管理你的 ComfyUI 环境——隔离依赖项、恢复损坏的安装，并防止冲突。
下载 Wonderful Launcher — 免费使用。
相关指南
- 修复损坏的 ComfyUI 便携版依赖而不重装 Torch
- ModuleNotFoundError: ComfyUI 中缺少 'sqlalchemy' 模块
- 如何修复 ComfyUI 插件导入失败错误
- ComfyUI 依赖冲突
- ComfyUI 重连错误
- 常见问题
- 故障排查决策树
想要更快捷的方式？
如果环境仍然无法恢复，请围绕第一条真实错误、当前 Python 路径、最近一次安装命令和 pip check 输出继续排查，而不是继续花时间盲目重试。
参考来源
先按上面的步驟定位根因。还卡住时，可以下载 Wonderful Launcher 检查目前机器；启动器原生修复、任务日誌和執行階段检查会集中在一起。credits 只用於图片生成和按量工具。
下载 Wonderful Launcher查看 credits 方案这篇文件解決了你的問题嗎？
你的回饋会帮助我们優先補強真實 ComfyUI 排障文件。