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

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:\AI\ComfyUI，避免放在桌面、系统保护目录或包含特殊符号的路径中。模型文件通常较大，最好提前规划models目录，避免后期迁移导致路径失效。

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

推荐的手动安装流程

第一步，安装Python时勾选“Add Python to PATH”，安装完成后在命令行输入python --version确认版本。第二步，安装Git，并用git --version检查是否可用。第三步，进入准备好的目录，使用Git获取ComfyUI项目。如果无法顺利获取，可以稍后重试，或使用项目页面提供的压缩包方式，但压缩包不利于后续更新和回滚。

第四步，进入ComfyUI目录后创建独立环境，例如使用python -m venv venv，再执行venv\Scripts\activate。独立环境的好处是不会污染系统Python，也能降低不同AI工具之间的依赖冲突。第五步，根据显卡类型安装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文件离线安装。

第二类问题是模型下载慢或文件不完整。模型文件应放在对应目录，例如大模型放入models\checkpoints，VAE放入models\vae，LoRA放入models\loras，ControlNet模型放入models\controlnet。下载完成后如果加载报错，要检查文件大小是否异常、扩展名是否正确、是否被重复改名。不要把模型随意放进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的维护成本会低很多，也更适合长期稳定使用。