ComfyUI 的版本关系：Core、前端、模板包、桌面版到底谁跟着谁

2026-08-09

在 ComfyUI 的社区讨论里，「我就是升了个级」后面通常跟着三件事：界面布局变了、以前用的模板在模板库里找不到了、某个自定义节点开始报 import 失败。这三件事看着像三个 bug，其实往往是同一次操作的连带结果——因为你升的那个”级”，压根不是一个包。

ComfyUI 是由好几条版本线拼起来的：Core 是一条，前端是一条，工作流模板和内置文档各是一条，桌面版又是一条。搞清楚谁跟着谁走，比背错误信息有用得多。这篇按官方仓库 README 里 Release Process 章节的原始规则，把这几层的从属关系摊开讲。核对日为 2026-08-09，对应 ComfyUI v0.31.0（发布于 2026-08-08）。

一、官方 README 定的三仓规则

README 的 Release Process 章节列的是三个互相关联的仓库，规则原文要点如下。

第一个是 ComfyUI Core（仓库 comfyanonymous/ComfyUI，现在会跳转到 github.com/Comfy-Org/ComfyUI）：

大约每 2 周发一个新的 major stable 版本（README 自己举的例子是 v0.7.0）。
从 v0.4.0 起，patch 版本用于把修复 backport 到当前的 stable release。
minor 版本用于 master 分支上的发布。
在 backport 没有意义的情况下，master 分支上的发布也可能用 patch 版本号。
stable release tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点。
Core 是 desktop 发布的基础。

第二个是 Comfy Desktop（github.com/Comfy-Org/Comfy-Desktop）：README 只有一句话——用最新 stable core 版本构建发布。

第三个是 ComfyUI Frontend（github.com/Comfy-Org/ComfyUI_frontend）：

每 2 周以上把前端更新合并进 core 仓库。
特性会在即将发布的 core release 之前冻结。
冻结之后前端开发继续进入下一个周期。

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

这几条规则读起来平淡，但已经把两个高频问题的答案写死了：桌面版为什么总比 core 慢半拍（因为它按定义就要等 stable），以及你跟 master 时为什么容易把自定义节点搞炸（因为官方明说 tag 外的 commit 会弄坏很多自定义节点）。

二、一张表：谁被 pin 在什么版本上

光看 README 还不够，真正决定”升级一次会连带换掉什么”的是 core 仓库的 requirements.txt。下面这张表是 2026-08-09 核对 v0.31.0 时的对应关系。

组件	仓库 / 包	v0.31.0 时的 pin
Core	`github.com/Comfy-Org/ComfyUI`	v0.31.0（2026-08-08）
前端	`ComfyUI_frontend` → pypi `comfyui-frontend-package`	`==1.48.7`
工作流模板	pypi `comfyui-workflow-templates`（模板 JSON 在 `Comfy-Org/workflow_templates`）	`==0.11.37`
内置文档	pypi `comfyui-embedded-docs`	`==0.5.9`
桌面版	`github.com/Comfy-Org/Comfy-Desktop`	用最新 stable core 构建
Manager	`Comfy-Org/ComfyUI-Manager`（manager-v4 分支）	需 `manager_requirements.txt`
自研运行时	pypi `comfy-kitchen`、`comfy-aimdo`	`==0.2.28`、`==0.4.13`

这张表怎么读，关键在第三列那三个 ==。

== 不是 >=，也不是 ~=，它是精确锁定。这意味着当你 checkout 到 v0.31.0 并跑 pip install -r requirements.txt 时，pip 会把你环境里的 comfyui-frontend-package 换成 1.48.7、comfyui-workflow-templates 换成 0.11.37、comfyui-embedded-docs 换成 0.5.9——不管你之前装的是哪个版本，高了也会被降回去。

所以”升级 core”这个动作，实际上一次性动了四样东西：后端代码、前端界面、模板库、内置文档。 你升完之后界面按钮位置变了、模板列表里少了或多了几项、节点的帮助文档措辞变了，这些都不是幻觉，也不是各自独立的 bug，而是同一条 pin 链带来的连带更新。release notes 里能直接看到这类条目被频繁 bump，比如 v0.31.0 里的「Bump comfyui-frontend-package to 1.47.12」（PR #15244）和「Update workflow templates to v0.11.31」（PR #15297）。

这里有个容易踩的坑：release notes 条目里出现的版本号，和你核对当天 requirements.txt 里的 pin 值不一定是同一个数字。 上面那两条写的是 1.47.12 和 0.11.31，而 v0.31.0 的 pin 表里是 1.48.7 和 0.11.37。要判断自己环境里”应该是哪个版本”，唯一可靠的依据是你实际 checkout 的那个 tag 里的 requirements.txt，而不是 release notes 的叙述文字。

另外必须说清楚的是：知道前端版本变了，不等于知道某个 UI 问题的原因是前端版本变了。 这两件事之间需要具体证据（比如降回旧版本能复现/不复现），只凭”我升级过”就把锅扣给前端，排查方向很容易一开始就跑偏。

三、还有两个包也被 pin：comfy-kitchen 与 comfy-aimdo

表格最后一行经常被忽略。comfy-kitchen 和 comfy-aimdo 是 ComfyUI 依赖的自研包，同样以 == 精确 pin，在 v0.31.0 上分别是 0.2.28 和 0.4.13。它们在 release notes 里出现的频率很高，例如 v0.30.0 的「Update comfy-kitchen package version to 0.2.23」和「Update comfy-kitchen to fix flux kv issue」（PR #15144），以及 v0.31.0 的 comfy-aimdo 0.4.12（PR #15290）。另外，Triton 后端归属 comfy-kitchen——这一点可以从 --enable-triton-backend 这个参数的 help 文本里看出来。

这两个包的内部实现，我们没有任何可引用的事实，所以这篇不会去猜它们干了什么。但对使用者来说，有一条结论已经够用了：当你只是想”回退前端看看”而手工 pip 装了某个旧版本时，你动的是一个被 pin 的依赖树里的节点；下一次跑 pip install -r requirements.txt，它会被重新拉回 pin 值。想让手工降级持久生效，你得接受”不再跑那条命令”这个代价，而这本身又会让你和官方组合渐行渐远。

四、跟 tag 还是跟 master：判断依据只有一条

这是最常被问的问题，而官方 README 已经给了答案，不需要凭感觉：stable release tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点。

据此可以直接推出适用边界：

如果你的工作流严重依赖自定义节点，跟 tag。你要的是”节点能加载”，而不是”我有最新特性”。
如果你在追一个刚发布的新模型或刚合并的修复，跟 master 是唯一的路，但代价是官方已经提前告诉你会弄坏自定义节点——出问题时应该首先怀疑这一点，而不是怀疑自定义节点作者。
如果你完全不想管这些，桌面版就是这个定位：它按 README 的规则用最新 stable core 构建。代价是它天然滞后于 core 仓库的 tag，更滞后于 master。桌面版”版本比 GitHub 上低”不是打包错误，是设计如此。

顺带说一句版本号的读法。按 Release Process 的规则，patch 版本从 v0.4.0 起承担”把修复 backport 到当前 stable”的职责，但同时又写了”在 backport 没有意义的情况下，master 分支上的发布也可能用 patch 版本”。所以不能只看第三位数字就断定某个版本是不是纯修复版——这个语义在两种情况下都会被复用，判断依据只能是该版本的 release notes 条目本身。

五、升级前值得多看一眼的地方

除了前端和模板会被连带更新，还有一类变化更隐蔽：API / partner 节点会被增删。 这不是推测，release notes 里有明确条目：

v0.28.0（2026-07-15）移除 StabilityAI 节点（PR #14737），移除 IdeogramV1 与 IdeogramV2 节点（PR #14712）。
v0.31.0（2026-08-08）移除 Kling 已退役的 legacy 模型与 Virtual Try-On API（PR #15249）。
同时也在加：v0.29.0 新增 OpenAI GPT5.6 模型（PR #14957）与 Google Gemini 3.5 Flash LLM 模型（PR #14972）；v0.31.0 新增 TopazAI Bloom 2 与 Wonder 3.5（PR #15294）、BFL Flux 3 video model（PR #15295）。

由此可以直接得出一条判断：依赖 API/partner 节点的工作流，存在”上游模型退役 → 节点被移除 → 老工作流打不开”这条链路。 升级之前扫一遍 release notes 里的 removed 条目，比升级之后再回滚省事得多。至于哪个节点接下来会被移除，没人能预测，这里也不做预测。

所以一个可操作的升级前检查清单是这样的：先确认你要升到哪个 tag，再去看那个 tag 的 release notes 里有没有 remove 类条目命中你在用的 API 节点，最后看一眼那个 tag 的 requirements.txt，心里对前端和模板包会被换到什么版本有个数。真出问题时，你至少知道有四层可以分别怀疑，而不是只能对着一个”升级了”三个字发呆。

六、这套逻辑不适用的情况

有几种场景，上面的推理链是断的，别硬套：

你装的是 portable 包或第三方一键包。 这类分发的依赖版本组合由打包者决定，未必等于官方 tag 的 requirements.txt。
你的问题出在模型权重或显存上。 版本关系解释的是”代码与资源包的组合”，跟权重加载失败、显存不足是两类问题，别混在一起排查。
你想据此判断某个具体 UI 异常的根因。 前面说过，pin 链只能告诉你”什么被换了”，不能告诉你”是它导致的”。

最后提醒一句版本号写法：本文所有结论都绑定 v0.31.0（2026-08-08）这个快照。ComfyUI 大约每 2 周一个 major stable 版本，pin 值和 release notes 条目都会变，看到这篇时请以你自己 checkout 的那个 tag 为准。

延伸阅读

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