ComfyUI 升级与排障¶
一、这页讲什么¶
ComfyUI 迭代快，升级能拿到新模型支持，也可能把现有环境搞坏。这一页给出固定流程：升级前记什么、怎么升、升完怎么验、坏了怎么退；以及启动失败时的排查顺序。
读完能做到：在不丢工作流的前提下升级；判断一次启动失败是环境、节点还是端口的问题；把环境退回上一个可用版本。
二、开始之前¶
| 项 | 内容 |
|---|---|
| 版本与日期 | ComfyUI 2026-10 最新版；2026-10-21 核实 |
| 预计耗时 | 30 分钟，含验证 |
| 前置 | 01-部署已完成；能接受停机十几分钟 |
| 风险级别 | 中：升级可能让现有工作流与节点失效 |
三、动手做¶
1. 升级前记录三件事¶
| 记什么 | 怎么记 |
|---|---|
| 当前版本 | 启动日志开头有版本号与提交号；或用 git log -1 --oneline 看安装目录 |
| 已装节点 | Manager 的已装列表截图，或 $ ls custom_nodes/ |
| 关键工作流 | 导出成文件另存一份，别只留在界面里 |
看到这个就算成：三样东西都有备份，出问题能照着恢复。
2. 便携版升级¶
解压目录下的 update/ 里有三个脚本：
| 脚本 | 做什么 | 什么时候用 |
|---|---|---|
update_comfyui.bat |
拉取最新提交 | 日常升级，首选 |
update_comfyui_and_python_dependencies.bat |
连 Python 依赖一起重装 | 只有环境坏了才用 |
update_comfyui_stable.bat |
切到最新稳定版 | 想要稳不要新 |
看到这个就算成：脚本跑完打印成功，没有大段红色报错。
3. 源码安装升级¶
$ cd ComfyUI
Already up to date.
$ git pull
Already up to date.
$ pip install -r requirements.txt
Successfully installed（已满足时输出 Requirement already satisfied）
$ pip install -r manager_requirements.txt
Successfully installed（同上）
看到这个就算成：三条命令都成功退出，git log -1 --oneline 的提交变了。依赖要装进启动 ComfyUI 的那个环境。
4. 升级后逐层验证¶
- 启动服务，看控制台有没有报错；
- 用官方模板跑一张图，确认核心链路正常；
- 载入自己常用的工作流，确认节点与模型都在；
- 检查自定义节点是否有更新（节点包与核心版本常常要一起动）。
看到这个就算成：四步都过。任何一步不过就先停在这里，别继续加工作流。
5. 坏了怎么退¶
$ git log --oneline -5
f1a2b3c (HEAD) 更新到最新提交
9d4e5f6 上一个可用版本
$ git reset --hard 9d4e5f6
HEAD is now at 9d4e5f6 上一个可用版本
$ pip install -r requirements.txt
Successfully installed（依赖已满足时大部分是 Requirement already satisfied）
看到这个就算成：退回旧提交、重装依赖后能正常启动，原来工作流能跑。
6. 启动失败的排查顺序¶
- 看控制台最上面那段报错，不要看末尾的连带输出；
- 加
--disable-all-custom-nodes启动，排除所有第三方节点； - 换官方模板跑一次，排除工作流本身；
- 换端口启动（
--port 8189），排除端口被占； - 加
--verbose DEBUG拿到更细的加载日志。
看到这个就算成：能定位到「节点 / 工作流 / 端口 / 依赖」中的一类，而不是笼统地说起不来。
四、做完怎么确认¶
- 版本号已更新，启动无报错。
- 官方模板能出图。
- 自己的常用工作流能跑通。
- 已准备可回退的提交与依赖清单。
五、卡住了怎么排查¶
| 症状 | 多半是 | 先验证 | 处理 |
|---|---|---|---|
启动报 ModuleNotFoundError |
依赖没装，或装错了 Python 环境 | 看报错模块名、确认装依赖用的解释器 | 用启动 ComfyUI 的解释器重装；节点依赖也补齐 |
| 起不来但没明显报错 | 端口被占，或启动参数写错 | $ sudo ss -tlnp \| grep 8188、看 bat 内容 |
换端口；核对参数拼写 |
| 浏览器打不开 | 服务只监听 127.0.0.1 |
启动日志里那句 To see the GUI go to |
本机访问；别的机器访问要加 --listen |
| 升级后某个节点报错 | 节点包与核心版本不兼容 | 关掉全部节点能否启动 | 更新节点包；不行就回退版本 |
| 界面空白或样式错乱 | 前端缓存与版本不匹配 | 强制刷新、换浏览器 | 清缓存；确认版本已升级 |
| 升级后磁盘满了 | 旧版本留下了多个环境或备份 | $ df -h、$ du -sh * |
清旧备份；模型盘单独放 |
| 回退后还报错 | 依赖没跟着退回 | $ pip install -r requirements.txt |
依赖一起退回；必要时重建虚拟环境 |
六、为什么这样能成¶
ComfyUI 是 git 仓库加一个 Python 环境。 代码靠提交回退，依赖靠 requirements.txt 重装，两者要一起退；只退代码会留下不匹配的包。
便携版把 Python 一起打包了。 python_embeded 就是那套环境，所以装依赖必须用 python_embeded 里的解释器，普通 pip 装到别处等于没装。
节点是外部依赖最大的变量。 升级核心后，第三方节点最容易失效。先用 --disable-all-custom-nodes 排除，能避免在几十个节点里瞎找。
七、边界与替代¶
- 不管驱动升级：显卡驱动与 CUDA 的问题看 GPU 与 CUDA 环境。
- 不提供模型来源：升级只动代码与环境，模型另外管理，见模型与目录。
- 别在生产实例上试新版：多人共用的实例升级前先在群里约时间，或另起一份试。
- 稳定优先时用 stable 脚本：新提交带着新问题很常见，稳定版更省事。
八、官方资料¶
- 更新 ComfyUI：https://docs.comfy.org/installation/update_comfyui
- 便携版说明（含更新脚本）：https://docs.comfy.org/installation/comfyui_portable_windows
- 启动参数：https://docs.comfy.org/development/comfyui-server/startup-flags
- 排查手册：https://docs.comfy.org/troubleshooting
核实日期：2026-10-21。