先判断失败发生在哪个环节

ComfyUI本身并不复杂。真正容易出问题的是运行环境：Python版本、Git拉取、PyTorch安装、显卡驱动、依赖包下载、自定义节点。

遇到安装失败，不要反复双击启动脚本。先看报错出现在什么位置。

• 如果提示“python不是内部命令”，说明Python没有正确安装或没有加入环境变量。
• 如果提示“torch not compiled with CUDA enabled”，多半是PyTorch版本与显卡环境不匹配。
• 如果卡在requirements安装，通常是依赖下载不稳定或某个包编译失败。
• 如果主程序能开但加载节点报错，则重点检查custom_nodes目录。

建议新手采用“最小可运行”思路：先不安装任何第三方节点，只让ComfyUI原版启动成功。确认浏览器能打开本地界面、基础工作流能跑通后，再逐个添加模型和节点。这样定位问题最清晰，也能避免把主程序、模型、插件三类问题混在一起。

安装前准备：版本不要随意混用

Windows用户建议准备64位Python 3.10或3.11、Git、较新的显卡驱动，以及足够的磁盘空间。ComfyUI目录路径尽量使用英文和数字，例如D:AIComfyUI。避免放在桌面、系统保护目录或包含特殊符号的路径中。模型文件通常较大，最好提前规划models目录，避免后期迁移导致路径失效。

如果使用NVIDIA显卡，需要确认驱动支持当前CUDA运行包。普通用户不必单独安装完整CUDA开发套件，更多情况下只要安装匹配CUDA版本的PyTorch即可。CPU也能运行，但速度很慢，只适合测试环境是否正常。AMD或苹果芯片用户需要查阅对应平台说明，不建议直接套用NVIDIA安装命令。

推荐的手动安装流程

第一步：安装Python

安装Python时勾选“Add Python to PATH”。安装完成后在命令行输入python --version确认版本。

第二步：安装Git

安装Git，并用git --version检查是否可用。

第三步：获取ComfyUI项目

进入准备好的目录，使用Git获取ComfyUI项目。如果无法顺利获取，可以稍后重试，或使用项目页面提供的压缩包方式。但压缩包不利于后续更新和回滚。

第四步：创建独立环境

进入ComfyUI目录后创建独立环境，例如使用python -m venv venv，再执行venvScriptsactivate。独立环境的好处是不会污染系统Python，也能降低不同AI工具之间的依赖冲突。

第五步：安装PyTorch

根据显卡类型安装PyTorch。NVIDIA用户应在PyTorch官网选择对应CUDA版本的命令，不要从旧教程中复制来路不明的安装指令。

第六步：安装项目依赖

执行命令：python -m pip install -r requirements.txt。国内网络环境下，如果下载经常中断，可临时指定可信的软件源，例如在命令末尾添加 -i https://pypi.tuna.tsinghua.edu.cn/simple。但不要随意使用来源不明的包站。

第七步：运行并测试

运行python main.py。若看到类似“Starting server”并提示本地地址，说明主程序已启动。打开浏览器访问127.0.0.1:8188即可进入界面。首次测试建议使用简单工作流和小模型，先确认采样、预览、保存输出都正常，再添加复杂节点。

国内网络环境常见卡点与避坑

问题一：依赖包下载失败

最常见的问题是依赖包下载一半失败。处理方法不是不断重装，而是升级pip：python -m pip install -U pip setuptools wheel，然后重新安装requirements。若某个包单独失败，可以复制包名单独安装，观察完整错误信息。遇到“Read timed out”或连接重置，优先更换稳定时段、使用可信镜像源，或提前下载whl文件离线安装。

问题二：模型下载慢或文件不完整

模型文件应放在对应目录。例如：大模型放入modelscheckpoints，VAE放入modelsvae，LoRA放入modelsloras，ControlNet模型放入modelscontrolnet。下载完成后如果加载报错，要检查文件大小是否异常、扩展名是否正确、是否被重复改名。不要把模型随意放进custom_nodes，也不要把压缩包当模型直接使用。

问题三：自定义节点依赖复杂

很多节点需要单独执行安装脚本或安装额外requirements。建议一次只添加一个节点，添加后立即启动测试。若出现报错，先把该节点文件夹移出custom_nodes，再确认主程序能否恢复。不要一次性安装几十个节点，否则后续很难判断是谁引发冲突。

更新升级前必须做的备份

ComfyUI更新速度快，升级能获得新功能和兼容性修复，但也可能造成旧工作流失效。升级前至少备份以下五类内容：

• workflows或自己保存的json工作流
• custom_nodes第三方节点
• models目录索引和额外路径配置
• extra_model_paths.yaml
• 当前Python依赖清单。依赖清单可以用pip freeze > requirements-lock.txt保存，出问题时便于还原。

如果项目是通过Git获取的，升级前先查看当前状态：git status。确认没有自己改动过核心文件后，再执行git pull。拉取完成后重新安装依赖：python -m pip install -r requirements.txt。不要只更新主程序而忽略依赖，也不要只更新节点而长期不更新主程序。两者版本差距过大时，最容易出现类名缺失、接口变化、节点无法导入等问题。

升级失败后的回滚方案

最稳妥的回滚方式是使用Git提交点。升级前先记录当前版本：git rev-parse --short HEAD。升级后如果启动失败，进入ComfyUI目录执行git log --oneline查看历史提交，找到升级前的提交号，再执行git reset --hard 提交号。随后根据备份的requirements-lock.txt还原依赖：python -m pip install -r requirements-lock.txt。这样可以把主程序和依赖尽量恢复到升级前状态。

如果使用的是压缩包安装，没有Git历史，就只能依靠手动备份。建议保留一个“可运行版本”文件夹，新版本单独解压测试，确认工作流和节点都正常后再切换。不要直接覆盖旧目录，尤其不要覆盖custom_nodes和配置文件。模型目录可以通过extra_model_paths.yaml复用，减少重复占用空间。

自定义节点也需要单独回滚。很多节点本身也是Git项目，可以进入对应节点目录执行git log --oneline和git reset --hard 提交号。如果节点不是通过Git获取的，只能恢复升级前备份。排查时可先移走最近更新的节点，确认ComfyUI能启动后，再逐个放回。

常见问题快速定位

启动后页面打不开：先看命令行是否仍在运行，确认端口是否为8188。如果端口被占用，可用python main.py --port 端口号更换。

页面能开但不能生成：检查模型是否正确加载，显存是否不足，工作流节点是否缺失。显存不足时可降低分辨率、批量数和采样复杂度，或使用更小的模型。

提示缺少某个模块：通常是依赖没装全，先激活虚拟环境，再安装对应包或重新执行requirements。

提示CUDA相关错误：不要盲目重装ComfyUI，应先确认显卡驱动、PyTorch版本和Python环境是否一致。

提示某个节点导入失败：把报错节点移出custom_nodes，主程序能恢复就说明问题在该节点或其依赖。

工作流打开后全是红色节点：说明缺少对应自定义节点。可以根据节点名称查找来源，但安装前要确认维护状态、适配版本和用户反馈。旧工作流不一定适配新版本，重要项目应保留生成时的环境记录。

安全边界与实用建议

ComfyUI会执行本地Python代码，第三方节点本质上也是代码包。因此，只应从官方项目页、知名维护者仓库或可信社区获取。不要运行来历不明的启动脚本，不要把含有私密信息的图片、配置和路径上传到陌生服务。团队环境中建议把模型、节点、工作流分目录管理，并记录版本号，避免多人同时改动导致环境不可复现。

对普通用户来说，最省心的原则是：

• 主程序用Git管理
• Python用虚拟环境隔离
• 模型目录单独存放
• 升级前做备份
• 节点逐个添加

遇到失败时，先读最后20行报错，不要凭感觉重装系统或清空目录。只要把安装、更新、回滚拆成可验证的小步骤，ComfyUI的维护成本会低很多，也更适合长期稳定使用。