升级后坏了：ComfyUI 的版本回退策略

2026-08-09

一、现象：昨天还好好的，今天拉了一次更新就废了

这一类现象的共同点是「我什么都没改，只是更新了一下」：

起不来，或者能起来但前端界面跟昨天不一样；
自定义节点集体报错、面板里出现红框；
打开保存好的工作流，节点上的数值跟你记忆里的对不上；
功能都在，但显存、内存的表现变了。

官方仓库里也确实有对应的讨论。官方仓库 issue #15100 反映了「Mess with stable versions」这一现象，该 issue 创建于 2026-07-27，标签为 User Support，截至 2026-08-09 仍为 open。另一条 issue #13017 反映了「工作流加载时改写节点数值（ckpt/lora 及其它），有时重置为 0，破坏 JSON 完整性」这一现象，该 issue 创建于 2026-03-17，没有打标签，截至 2026-08-09 仍为 open。

需要说明两点：我们只取到了这两条 issue 的编号、标题、创建日期、标签与状态，没有读过它们的正文与评论，所以下面不会出现「这条 issue 的根因是什么」「社区给了什么 workaround」。另外，标签只是仓库侧的分类，User Support 不等于官方确认了这是一个 bug；哪怕标签是 Potential Bug，字面含义也只是「疑似 bug」，同样不等于官方已确认。仍为 open 也不代表官方在修或者不修。它们在这篇文章里的作用只有一个：说明「升级后行为变化」不是你一个人的错觉，值得按流程排查，而不是先怀疑自己的机器。

二、怎么确认是「升级引起的」

排查顺序不要跳。下面每一步都是可执行动作。

第 1 步：确认你现在到底在哪个版本上。 这一步之所以排第一，是因为「更新」在 ComfyUI 生态里有好几种含义，而它们对应的回退方式完全不同。官方 README 的 Release Process 章节写得很清楚，一共三个互相关联的仓库：

ComfyUI Core（comfyanonymous/ComfyUI）：大约每 2 周发一个新的 major stable 版本；从 v0.4.0 起，patch 版本用于把修复 backport 到当前 stable release，minor 版本用于 master 分支上的发布，在 backport 没有意义的情况下 master 分支上的发布也可能用 patch 版本；stable release tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点；它是 desktop 发布的基础。
Comfy Desktop（github.com/Comfy-Org/Comfy-Desktop）：用最新 stable core 版本构建发布。
ComfyUI Frontend（github.com/Comfy-Org/ComfyUI_frontend）：每 2 周以上把前端更新合并进 core 仓库；特性在即将发布的 core release 之前冻结；前端开发继续进入下一个周期。

README 另外说明，ComfyUI 遵循以周一为目标的每周发布周期，但会因为模型发布或代码库大改而经常变动。

所以先分清：你是用 Desktop 应用点了更新，还是在 manual 安装目录里拉了 git，还是换了 portable 包。Desktop 走的是「最新 stable core」，manual 安装如果你跟的是 master 分支，那你拿到的很可能就是上面那句原话里说的、tag 之外的 commit。

第 2 步：确认前端是不是跟着换了。 这一步最容易被忽略。v0.31.0 时点的 requirements.txt 里，三个 comfy 官方包是被精确 pin 的：comfyui-frontend-package==1.48.7、comfyui-workflow-templates==0.11.37、comfyui-embedded-docs==0.5.9；另有两个被 pin 的自研包 comfy-kitchen==0.2.28 和 comfy-aimdo==0.4.13。== 意味着升级 core 会连带换前端、模板与内置文档的版本。很多「升级后界面出问题」的现象，看的其实不是 core 的代码，而是这次跟着换掉的前端包。

对应的判定动作：comfy/cli_args.py（v0.31.0）里有 --front-end-version，默认值是字符串 comfyanonymous/ComfyUI@latest，格式为 [repoOwner]/[repoName]@[version]，help 注明该命令需要联网去 GitHub releases 查询和下载可用的前端实现；另有 --front-end-root PATH 指定本地前端目录，help 注明它 Overrides --front-end-version。也就是说，前端版本是可以跟 core 分开定的——先把这个变量单独固定住，才能判断问题出在哪一层。

第 3 步：把自定义节点这个变量摘掉。 同一份 cli_args.py 里有 --disable-all-custom-nodes（不加载任何自定义节点），以及 --whitelist-custom-nodes NAME [NAME ...]（在开启上一条时仍然加载指定的自定义节点目录）。先用 --disable-all-custom-nodes 干净启动一次：

问题消失 → 大概率是某个自定义节点跟新版本不兼容，用 --whitelist-custom-nodes 逐个放行做二分；
问题还在 → 才轮到考虑回退 core。

顺带一提，判断当前 git HEAD 落在哪个 tag 上、以及查看已安装的 comfyui-frontend-package 版本，用的是通用的 git 与 pip 命令，这属于常规运维做法，不是 ComfyUI 官方文档里的内容，这里就不展开写具体命令了。

三、处置：回退要退到 tag，不要退到「昨天那个 commit」

官方规则里最该被当成硬依据的就是那句话——stable release tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点。很多人回退时习惯往回数几个 commit，「退到出问题之前那次提交」，这恰恰踩在这句话的枪口上：你退到的是一个没有经过 stable 发布流程的中间状态，自定义节点生态并不是按这个状态测的。正确的做法是退到某个 stable release tag。

第二条同样重要：回退 core 的同时要把 requirements.txt 一起回退，并重新安装依赖。原因就是上面那三个 == pin——只回退代码不重装依赖，前端包、模板包、内置文档包还停在新版本上，等于只退了一半，这时候「退了还是坏」根本不能当证据用。

那退到哪一版？按下面这张官方 Releases 时间线（2026-08-09 取回）找「最后一个还正常的日期」，再挑那个日期之前的 stable 版本：

版本	发布日期	该版本值得记住的变更
v0.31.0	2026-08-08	修复 MiniMax H3 VAE 的 raw parameters 设备转换（PR #15268）；Linux 无 swap 分区时不再固定过多内存（PR #15266）；恢复 SDPA 非 cudnn 的小注意力旁路（PR #15296）
v0.30.0	2026-08-03	支持 int8 convrot embedding lookup；用 pinning 基础设施以 MRU 策略把权重加载到进程 RAM；新增可配置 DETAIL 日志侧通道；新增 dataset 目录以避免任意目录访问
v0.29.2	2026-07-31	前端修复与新的 api / partner 节点
v0.29.0	2026-07-29	视频转码改为流式，不再把每一帧都缓存在 RAM
v0.28.0	2026-07-15	修复四个安全漏洞；新增 AGENTS.md；移除 StabilityAI 节点与 Ideogram V1/V2 节点
v0.27.0	2026-06-30	新增 int8 convrot 模型支持
v0.26.0	2026-06-23	使用 `--base-directory` 时把 base 目录打进启动日志（PR #13370）
v0.25.1	2026-06-18	新增 Kling V3-Turbo 支持
v0.25.0	2026-06-16	音频节点合并进 SaveAudioAdvanced
v0.24.0	2026-06-03	多个 dtype / cast 修复；MultiGPU CFG Split 手动中止时的冻结修复
v0.23.0	2026-06-01	多线程从磁盘加载模型（大幅加速加载并支持 offload 到磁盘）
v0.22.0	2026-05-20	新增 SECURITY.md；把前端版本警告推广到所有 `comfy*` requirements.txt 条目

这张表的正确读法不是「挑最新的」，而是按你的现象类别去找分水岭：

现象是内存/显存表现变了 → 注意 v0.23.0（2026-06-01）的多线程磁盘加载与 v0.30.0（2026-08-03）的 pinning MRU 权重加载，这两版都动了加载与内存策略；
现象跟视频转码期间的内存占用有关 → v0.29.0（2026-07-29）把转码改成了流式；
现象只在 Linux 且机器没有 swap 分区 → v0.31.0（2026-08-08）的 PR #15266 就是针对这一条的；
现象是界面/交互 → 优先怀疑跟着换掉的前端包，而不是 core。

回退是有代价的，这一点必须写在决策里：v0.28.0（2026-07-15）修复了四个安全漏洞，退到它之前，等于把这些已经修掉的问题又退回来。如果这台机器不是只给自己在 127.0.0.1 上用，这个代价就得单独衡量，而不是「先退了再说」。另外 v0.30.0（2026-08-03）才引入的 DETAIL 日志侧通道，退到 v0.29.x 就没有了——--verbose 的合法等级是 DEBUG、DETAIL、INFO、WARNING、ERROR、CRITICAL，其中 DETAIL 属于较新的等级。也就是说，你回退之后会同时失去一部分排查手段，这个顺序有点反直觉：想查得更细，反而要待在新版本上。

四、退完怎么验证

不要只看「界面能打开了」就收工，按这四处逐个确认：

版本对上了：确认代码确实停在你选的那个 stable tag 上，而不是 tag 附近的某个 commit。
依赖跟着退了：确认 comfyui-frontend-package、comfyui-workflow-templates、comfyui-embedded-docs 三个包的实际安装版本，跟你回退后那份 requirements.txt 里写的 == 版本一致。这三个不一致，回退就没做干净。
先用干净配置复现一次：加 --disable-all-custom-nodes 启动，确认原现象消失；然后去掉这个参数，再确认一次。两次结果不同，说明问题在自定义节点侧而不是 core 版本。
工作流单独验：如果你的现象跟 #13017 描述的那类「打开工作流数值被改写」相似，在回退后重新打开工作流时，先看数值、确认无误再保存。一旦保存，你就没有干净的对照样本了。文件在保存前留一份副本，是通用做法。

五、什么情况说明「不是升级引起的」

排查文章最怕读者一条道走到黑，下面几条是明确的止损信号：

退到旧 tag 之后问题依旧。那就不是这次升级带来的回归，往下应该查自定义节点、模型文件本身、显卡驱动与 torch，而不是继续往更老的版本退。README 的 Manual Install 章节写了 torch 侧的口径：torch 2.7 是最低支持版本但极力推荐用更新的，cu130 及以上在 NVIDIA 20 系及以上是必需的，如果你的 pytorch 超过 6 个月没更新请更新它。
你同时动了不止一个变量。这次既 git pull 了 core，又顺手升了 torch，还装了两个新节点——那「升级后坏了」这个判断本身就不成立，先把变量拆开。
只有一个工作流出问题，其它都正常。版本回归通常不会这么挑对象，先查这个工作流引用的节点与模型。
只退了代码没重装依赖。前面说过，三个 == pin 包不跟着回退，这次回退的结论不可用。
你用的是 Desktop 应用。README 写明 Comfy Desktop 是用最新 stable core 版本构建发布的，它跟 manual 安装目录里「切 tag + 重装依赖」不是一回事，别把两套做法混着用。
你拿 open 的 issue 当结论。issue 仍为 open 只说明它没关闭，既不代表官方确认了这是 bug，也不代表它跟你遇到的是同一个问题。它能给你的只有一个信息：这个方向值得排查。

最后给一条选择依据，回答「我到底该跟 master 还是跟 tag」：依据就是 README 那句原话——tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点。如果你的目录里装了一堆自定义节点，并且这台机器要拿来干活，那就跟 stable tag，每 2 周跟一次 major stable；只有在你确实要试某个刚合进 master 的能力、并且能接受节点集体罢工的时候，才有理由跟 master。

延伸阅读

本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、 release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0；文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。安全公告信息来自 GitHub Security Advisories，本文不含漏洞利用细节。