ComfyUI 前端出问题该提到哪个仓库：三路分流规则与 `--front-end-version` 的用法

2026-08-09

界面上某个按钮点了没反应、节点面板搜不到东西、画布拖动手感变了——大多数人的第一反应是打开 github.com/comfyanonymous/ComfyUI 提个 issue。这个仓库现在会跳转到 Comfy-Org/ComfyUI，看上去也确实是”ComfyUI 的仓库”，但如果你的问题是纯界面层的，提到这里等于放错了收件箱。

原因很朴素：ComfyUI 的前端从 2024-08-15 起已经迁到了独立仓库 Comfy-Org/ComfyUI_frontend。README 里明写了一句话——前端相关的 bug 与需求应该提到前端仓库，这样便于官方分流处理。这不是社区约定，是官方自己写在文档里的收件规则。

现象：同一个问题，两个仓库都”像”对的

会踩这个坑，是因为你日常只跑一条命令：python main.py。装的时候没有单独装过前端，用的时候也是一个地址打开，界面和执行引擎在体感上就是一个东西。但在源码组织和发布节奏上，它们早就分家了——前端有自己的仓库、自己的 pypi 包、自己的发布频率。

分家之后带来的第二层困惑是版本号对不上。你在 issue 里写”我用的是 v0.31.0”，对方问”前端是哪个版本”，你答不上来——因为你从来没单独装过前端。

怎么确认这是前端的问题

第一步：先搞清楚你跑的前端是哪来的

前端的编译产物发布到 pypi 的 comfyui-frontend-package，作为 ComfyUI 的一个依赖被装进来。在 ComfyUI v0.31.0（2026-08-08）里，requirements.txt 里这一行 pin 的是：

comfyui-frontend-package==1.48.7

去 <你的 ComfyUI 目录>/requirements.txt 里找这一行，就是你的前端版本来源。注意它是 == 精确 pin，不是 >=。同一份 requirements.txt 里还有两个同样用 == 钉死的包：

组件	包名	v0.31.0 时的 pin
前端	`comfyui-frontend-package`（源码在 `Comfy-Org/ComfyUI_frontend`）	`==1.48.7`
工作流模板	`comfyui-workflow-templates`（模板 JSON 在 `Comfy-Org/workflow_templates`）	`==0.11.37`
内置文档	`comfyui-embedded-docs`	`==0.5.9`

这张表值得多看两眼：升级 core 会连带把前端、模板、内置文档一起换掉。ComfyUI 的 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）这类条目。所以”我只是升了个版本，怎么界面也变了”是完全正常的，不是你装错了东西。

反过来也要克制：别因为前端版本变过，就断言某个 UI 现象一定是前端引起的。那需要具体证据，光看到 pin 号变了不算证据。下一步就是去拿证据。

第二步：换一个前端版本做对照

这是本文最有操作性的一步。ComfyUI 提供了两个参数来替换默认随包安装的前端：

# 取前端仓库的每日发布版
python main.py --front-end-version Comfy-Org/ComfyUI_frontend@latest

# 取指定版本（README 举的例子是 1.2.2）
python main.py --front-end-version Comfy-Org/ComfyUI_frontend@1.2.2

# 用本地目录里的前端（这个参数会覆盖 --front-end-version）
python main.py --front-end-root PATH

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 python main.py --help 的实际输出为准。

两者的差别要分清楚：

--front-end-version 后面跟的是远端仓库 + 版本标识，格式是 [repoOwner]/[repoName]@[version]，version 位置填 latest 或具体版本号；默认值是 comfyanonymous/ComfyUI@latest。comfy/cli_args.py（v0.31.0）里这个参数的 help 明写它需要联网，去 GitHub releases 查询并下载可用的前端实现——所以断网的机器、被公司代理挡住的机器、离线部署的服务器，得考虑另一条路。
--front-end-root 后面跟的是本地前端目录路径，指向一份你自己准备好的前端产物；comfy/cli_args.py（v0.31.0）里注明它会校验该目录存在且可读，并且覆盖（Overrides） --front-end-version——两个都写的时候，--front-end-root 说了算。这一点很容易翻车：有人加了 --front-end-version 发现完全没生效，回头一看启动脚本里还留着一个早就忘了的 --front-end-root。

为什么换版本对照有意义？因为主仓库里的前端每两周更新一次，而独立仓库有每日发布。这两个节奏差摆在那儿：你手上随 core 装进来的那份前端，未必等于前端仓库当下的状态。所以「同一台机器、同一个工作流，只换前端版本」这个动作，本身就是把变量收窄到前端的最直接手段。

对照的判定动作很直接：带上 --front-end-version Comfy-Org/ComfyUI_frontend@latest 重启一次。

现象消失：说明它跟前端版本相关，归属前端仓库这一路的可能性最大。这时先别急着开 issue——既然新版本上已经没有了，更值得做的是去前端仓库搜一遍已有 issue，看是不是别人早就提过。
现象还在：至少说明换到每日版也没解决，它要么是前端仍存在的问题，要么根本不在前端——那就往下走第三步和最后一节。

需要提醒的是，这一步只是把嫌疑范围收窄，不是判决书。换版本之后同时变化的东西不止一样，能得出的结论仅限于「与前端版本相关 / 无关」，不要顺手推出「一定是某某功能的 bug」。

第三步：对照官方模板给的三路分流规则

ComfyUI 官方的工作流模板里，内嵌的说明直接写了报错去向，一共三条：

你遇到的	去哪个仓库
跑不起来、运行时错误	`github.com/comfyanonymous/ComfyUI/issues`
UI / 前端问题	`github.com/Comfy-Org/ComfyUI_frontend/issues`
工作流本身的问题	`github.com/Comfy-Org/workflow_templates/issues`

第三条最容易被忽略。很多人以为”官方模板打开后效果不对”是 ComfyUI 的 bug，其实模板 JSON 有自己的仓库和自己的版本线（就是上面那个 comfyui-workflow-templates==0.11.37）。模板里的默认值本身就是可以讨论的对象——举个官方自己都承认的例子：MiniMax H3 的官方模板里，ResolutionSelector 的 megapixels 默认值是 0.4，而官方教程页推荐的是 1.0；模板说明里还写着对参考密集的提示词，beta 或 normal 调度器往往比模板默认的 simple 表现更好。默认值和推荐值不一致，这类事情提到 workflow_templates 才是对的收件人。

顺便提醒一句：ComfyUI-Manager 是又一个独立仓库（Comfy-Org/ComfyUI-Manager，当前在 manager-v4 分支，需要 manager_requirements.txt），上面这三条分流规则里没有它。自定义节点安装管理相关的问题该往哪提，官方模板那段说明没覆盖，别想当然按”UI 问题”塞进前端仓库。

处置后怎么验证

判定完归属，落地动作按情况分两种。

如果是想先绕过去继续干活，用 --front-end-version 或 --front-end-root 把前端切到一个可用版本。验证点有三个：

启动命令里确认没有第二个前端参数在抢——特别是 --front-end-root 覆盖 --front-end-version 这条；
回到浏览器复现原来的操作路径，确认现象变化；
把参数去掉再启动一次，确认现象回来。能一去一回复现两遍，才算把变量锁定在前端上，只验证一个方向很容易把别的偶发因素当成结论。

如果是要提 issue，把上面这套对照结果写进去比什么都管用：core 版本（如 v0.31.0）、requirements.txt 里 comfyui-frontend-package 的 pin 号、你切换到的前端版本、切换前后的差异。这几项凑齐了，对方才有可能判断该不该转仓。

什么情况说明这不是前端的问题

这一节比前面都重要，因为最常见的浪费不是提错仓库，而是围着前端查了半天，问题压根不在那儿。

一、“我改了参数但结果没变 / 点了没反应”。 这多半不是 UI 失灵。README 的执行模型里明写了两条规则：只有输出端所有输入都正确的那部分图会被执行；只有相对上一次执行发生了变化的部分会被执行。提交两次相同的图，只有第一次真正执行；只改了图的末端，就只有改动部分与依赖它的部分会重新跑。所以”看着没动静”很可能是缓存复用，是设计如此。想验证，可以用 --cache-none 启动，它的语义是每次运行都重新执行每个节点；如果加上之后行为就正常了，那这就是执行模型而不是前端 bug。

二、“同一个提示词每次队列出来的结果都不一样”。 如果你的提示词里用了 {day|night} 这种动态提示语法，README 写得很清楚："{wild|card|test}" 会由前端在每次排队提交时随机替换成其中之一。它确实发生在前端，但这是已文档化的行为，不是缺陷——提 issue 之前先确认自己不是踩了这个。想排除它，把花括号转义成 \{ \} 就是字面字符了。

三、“升级之后工作流打不开 / 某个节点变红了”。 先别怀疑前端渲染。API 与 partner 节点是会被增删的，release notes 里有实打实的条目：v0.28.0 移除了 StabilityAI 节点（PR #14737）、移除了 IdeogramV1 与 IdeogramV2 节点（PR #14712）；v0.31.0 移除了 Kling 已退役的 legacy 模型与 Virtual Try-On API（PR #15249）。上游模型退役 → 节点被移除 → 老工作流打不开，这条链是由 release notes 直接支撑的。判定动作：翻一下你跨过的那几个版本的 release notes，搜 “remove”。这属于 core 侧的变更，不是前端能背的锅。

四、“节点行为和我以为的不一样”。 比如 Ctrl+B（Bypass）和 Ctrl+M（静音）被当成一回事。README 只对 bypass 给了解释——行为等同于该节点被移除、连线从中穿过重新接上。两者语义不同，把它们混用之后得到的”异常”，不是 bug。同理还有两种复制粘贴：Ctrl+C / Ctrl+V 不保留与未选中节点输出的连接，而 Ctrl+C / Ctrl+Shift+V 保留未选中节点输出到粘贴节点输入的连接。粘贴完发现线断了，多半是用了前一种。

五、“界面上的某些东西连不上外网”。 如果你的启动参数里有 --disable-api-nodes，它的语义不只是不加载 api 节点，同时还会阻止前端与互联网通信。这是一个你自己开的开关，不是故障。去掉它再看现象是否变化，就能把这个变量排除掉。

一句话收尾：判定归属的成本远低于提错仓库来回转的成本。先看 requirements.txt 的 pin 行，再用 --front-end-version / --front-end-root 做一次一去一回的对照，最后照官方那三条分流规则投递——这套动作花不了十分钟，但能让你的 issue 落到真正能处理它的人手里。

延伸阅读

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