奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

ComfyUI 是什么：一个节点式的生成引擎，以及它带来的一整套工程问题

2026-08-09

本文口径为 ComfyUI v0.31.0（2026-08-08）时点的官方仓库内容。ComfyUI 大约每两周发一个大版本，参数、默认值与功能都会变，具体请以你本地 python main.py --help 的输出为准。

如果你是从「找个工具画图」这条路过来的，第一次打开 ComfyUI 大概会有点懵：没有输入框和生成按钮，只有一张画布和一堆连着线的方块。这个第一印象会让很多人把它归类成「更难用的 Stable Diffusion 前端」，然后在遇到第一个报错时放弃。

但这个归类是过期的。官方 README 给自己的定位原文是 “The most powerful and modular AI engine for content creation”——内容创作的模块化 AI 引擎。它的 Features 章节里，图像生成、图像编辑、视频生成、音视频生成、音频生成、3D 与视觉、文本生成是并列的七大类。把它当画图工具看，你会看不懂它一半的设计。

这篇是整个 ComfyUI 专题的入口。我不打算在这里教你点哪个按钮，而是把六件事说清楚：它是什么、它的版本怎么走、装在哪、跑起来之后的执行逻辑、显存这条贯穿始终的主线、以及扩展它要付的代价。每一节末尾都挂了对应的深入篇，文末有整个专题的完整目录。

一、它到底是什么：一张图，和图上流动的数据

ComfyUI 的核心抽象是一张有向图。每个节点做一件具体的事——加载模型、编码提示词、采样、解码、保存——节点之间连线传数据。你搭出来的不是一次生成，而是一条可以存下来、改一改再跑的流水线。

这个抽象带来的直接好处是可复现：README 明确写了，把生成出来的 png 拖回网页上，会得到完整的工作流，包括当时用的 seed。工作流本身也能存成 JSON。所以在 ComfyUI 里，「上次那张图是怎么出来的」不是靠记笔记，是靠文件。

官方 Features 里列的原生模型支持是一份很长的清单，README 自己注明这只是「代表性列表」。举几类看看密度：图像生成有 Stable Diffusion 1.5、SDXL、SD3.5、Flux.1、Flux.2、Qwen Image、Z-Image 等十几个；视频生成有 Wan 2.1/2.2、LTX-Video 2 与 2.3、HunyuanVideo 1.5、CogVideoX 等；音视频生成这一类目前列着 MiniMax H3 与 LTX-AV；文本生成有 Gemma 3/4、Qwen3、Qwen3-VL。此外还有 API 节点，用来访问闭源模型。

许可证是 GPL-3.0。仓库首页显示 125.2k star、4k 个 Issues。这两个数字放在一起大致能说明它的处境：用的人非常多，未解决的问题也非常多。

本节延伸：ComfyUI 适不适合接进生产流水线。

二、版本节奏：这是理解一切怪现象的前提

很多人踩的坑其实不是功能问题，是版本问题。所以这一节要放在前面。

README 的 Release Process 章节写得相当直白，有三个互相关联的仓库：

仓库角色节奏
ComfyUI Core主体大约每 2 周一个 major stable 版本；patch 版本用于把修复 backport 到当前 stable
Comfy Desktop桌面应用用最新 stable core 版本构建
ComfyUI Frontend前端每 2 周以上合并进 core；独立仓库有每日发布

其中有一句必须记住的原话：stable release tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点。

再叠加一层：requirements.txt 里有三个包是用 == 精确 pin 的——comfyui-frontend-package、comfyui-workflow-templates、comfyui-embedded-docs。这意味着升级 core 会连带换掉你的前端、工作流模板和内置文档。当你发现「我只是 git pull 了一下，界面怎么变了」，答案通常在这里。

桌面版与云端跟随 stable 发布，所以有一个结构性的滞后：某些「nightly 才支持」的新模型，在桌面版上暂时用不了。这不是 bug，是发布策略的必然结果。

本节延伸：ComfyUI 的版本关系：Core、前端、模板包、桌面版到底谁跟着谁、升级后坏了：ComfyUI 的版本回退策略、ComfyUI 前端出问题该提到哪个仓库：三路分流规则与 --front-end-version 的用法。

三、装在哪：四条路，官方的推荐和你的直觉可能相反

README 给了四条路径，各自的定位写得很清楚：

  • 桌面应用：官方原话是「最简单的开始方式」，在 Installing 章节里进一步写「对新用户是最简单也是最好的方式」。支持 Windows 与 macOS。
  • Windows Portable 包：能拿到最新 commit、完全便携。但 README 紧接着写了一句很多人没看到的话——「不推荐给普通用户，普通用户应该用上面的桌面应用」。
  • comfy-cli：pip install comfy-cli 然后 comfy install。
  • 手动安装：支持所有操作系统与 GPU 类型（NVIDIA、AMD、Intel、Apple Silicon、Ascend）。

这里最容易出事的是 portable 包，因为它有四个，下错了直接起不来。特别是那个 cu126 版本，README 用全大写写着 DO NOT USE THIS ON NEWER 20 SERIES AND ABOVE GPUS——它是给 10 系及更老的卡准备的。

版本矩阵也值得先看一眼再动手：Python 3.13 是「支持得很好」，3.14 能用但部分自定义节点有问题，3.12 是遇到依赖问题时的退路；torch 2.7 是最低支持但官方极力建议用更新的，cu130 及以上在 NVIDIA 20 系及以上是必需的。README 甚至直接写了一句：如果你的 pytorch 超过 6 个月没更新，请更新它。

本节延伸：Windows 上装 ComfyUI 的四条路径：桌面版、portable、comfy-cli、手动装怎么挑、四个 portable 包别下错：ComfyUI Windows 便携版的选包与落地流程、ComfyUI 的 Python 与 PyTorch 版本怎么定：照 README 版本矩阵倒推一条安装命令、桌面版 / portable / 手动装：ComfyUI 三条安装路怎么选。

四、跑起来之后：它只执行「变了的那部分」

装完之后第一个让人困惑的行为，通常是「我改了参数，它好像没重跑」。

这是设计如此。README 的 Notes 章节给了两条执行规则：

  1. 只有输出端所有输入都正确的那部分图会被执行。
  2. 只有相对上一次执行发生变化的部分会被执行。提交两次相同的图，只有第一次真正执行；如果只改了图的末端，那么只有你改动的部分以及依赖它的部分会重新执行。

理解这两条，很多「玄学」就消失了：为什么点了没反应、为什么改个种子就重跑了整条链、为什么把某个节点 bypass 掉之后下游全部重算。与之配套的是缓存参数，其中 --cache-none 的语义正好是这条规则的反面——每次运行都重新执行每个节点。

提示词这一侧也有几条 README 明写的语法规则，比如 () 调权重且默认值是 1.1、{day|night} 这种动态提示是由前端在每次排队时替换的。最后这条尤其值得知道：它不是采样器层面的随机，所以「为什么每次队列结果不一样」有了确切答案。

本节延伸：为什么改了参数它不重跑：ComfyUI 局部重执行机制怎么读、ComfyUI 五种缓存模式该选哪个：从 --cache-ram 的默认阈值倒推启动参数、ComfyUI 提示词语法全解：权重、转义、动态提示与 embedding 引用。

五、显存：贯穿整个专题的一条主线

如果这篇文章只能让你记住一件事，我希望是这件——ComfyUI 的显存管理已经换了一代，网上大量教程还停在上一代。

最典型的例子是 --lowvram。v0.31.0 的 comfy/cli_args.py 里，这个参数的 help 原文是：如果启用了 dynamic vram，这个选项不做任何事。而在默认配置下，dynamic VRAM 恰恰是启用的。也就是说，「显存小就加 --lowvram」这句流传甚广的建议，在当前版本的默认配置下命中的是「什么都不做」那条分支。

判定逻辑在源码里是一个很短的函数：

def enables_dynamic_vram():
    if args.enable_dynamic_vram:
        return True
    return not args.disable_dynamic_vram and not args.highvram and not args.gpu_only and not args.novram and not args.cpu

读法是：显式给了 --enable-dynamic-vram 就一定开；否则 --disable-dynamic-vram、--highvram、--gpu-only、--novram、--cpu 这五个里出现任意一个，dynamic VRAM 就是关的。这条名单里没有 --lowvram，所以它自己关不掉 dynamic VRAM，只是被架空的那一方。

顺带一个容易忽略的连带效果：有人为了「多占显存提速」加 --highvram，实际上同时把 dynamic VRAM 关掉了，退回了估算式加载。

围绕显存还有一批参数值得知道存在：--reserve-vram 给操作系统留显存、--vram-headroom 让 ComfyUI 额外保持一块完全空闲的显存（它会把其它应用占用的部分也算进来）、--async-offload 异步权重卸载（NVIDIA 上默认启用）、--fast-disk 在快 NVME 上优先用磁盘做动态加载。另外 Windows 和 Linux 在这里的默认值不一样：保留显存常量在 Windows 上更高，源码注释把原因归到 shared vram；pinned memory 的上限公式两边也是两套。

本节延伸：读懂 DynamicVRAM：它什么时候会被悄悄关掉、ComfyUI 的 --lowvram 为什么不管用了、ComfyUI 报 CUDA OOM 时的排查顺序、ComfyUI 启动日志逐行读懂：八行关键信息与 VRAM 状态机。

六、扩展它，以及扩展的代价

自定义节点是 ComfyUI 生态最活跃的部分，也是问题最集中的部分。官方给了三个开关，语义都很直接：--disable-all-custom-nodes 全部不加载、--whitelist-custom-nodes 在全关的前提下放行指定目录、--disable-api-nodes 不加载 API 节点（同时阻止前端与互联网通信）。

前两个组合起来就是一套可执行的二分排查法：全关能起来，说明问题在自定义节点侧；再逐批放行定位到具体是哪个。这比在报错堆栈里猜快得多。

风险这一侧也要如实说两件事。一是官方仓库披露过四个高危漏洞：2026-07-15 发布的四条 GitHub Security Advisory，严重等级均为 high，两条是存储型 XSS、两条是路径穿越，全部修复于 0.28.0。跑更早版本的实例，这四个问题是存在的。二是社区侧报告过通过 Comfy Registry 分发的自定义节点携带恶意程序的情况（issue #11791，2026-01-10 创建，截至 2026-08-09 仍为 open）。

顺带一提，API 节点也不是装上就一劳永逸的。看 release notes 能看到真实的移除记录：v0.28.0 移除了 StabilityAI 节点与 Ideogram V1/V2，v0.31.0 移除了 Kling 已退役的 legacy 模型与 Virtual Try-On API。依赖这类节点的工作流，有「上游模型退役 → 节点被移除 → 工作流打不开」的现实风险。

本节延伸：ComfyUI 自定义节点的供应链风险怎么控：三个官方开关的取舍路径、ComfyUI 的四个高危漏洞与为什么必须升到 0.28.0、依赖 API 节点的工作流有什么风险：从三次真实的节点移除说起。

七、它现在也能跑 MiniMax H3

这件事值得单独拎出来，因为它很好地说明了 ComfyUI 现在的位置：它是新模型落地的一个标准前端。

MiniMax 在 H3 的官方 README 里推荐了四种推理框架，ComfyUI 是其中之一，另外三个是 SGLang、vLLM 和 diffusers。ComfyUI 这边从 v0.30.0（2026-08-03）起支持，官方教程与两个工作流模板（T2V / R2V）都已就位；紧接着的 v0.31.0 修了 H3 VAE 的一个设备转换问题。

但这里有一个非常容易误解的点，必须先说明白：ComfyUI 用的 H3 权重和 MiniMax 官方发布的不是同一套。ComfyUI 侧从 Comfy-Org/MiniMax-H3 下载的是 pruned_int8_convrot、nvfp4_awq 这类量化权重，而 MiniMax 官方 README 写的精度是 BF16。两条路的产物不要混着评估。

本节延伸：在 ComfyUI 里跑 MiniMax H3：版本门槛、模型放置与 R2V 模板节点链拆解、ComfyUI 里的 H3 和官方权重不是同一套。

八、你现在应该往哪走

按你的处境挑一条：

  1. 还没装，想知道该走哪条路 → 先看第三节，再读安装路径选型。如果确定用 Windows，四条路径那篇给的是可直接执行的流程。
  2. 装好了但跑不起来 / 报错 → 直接去文末「排查与故障」那一组，18 篇按现象归类，每篇的结构都是：现象 → 怎么确认是这个问题 → 官方口径的处置 → 怎么验证 → 什么情况说明不是这个原因。最后一步是刻意留的，避免你在一条错路上走到黑。
  3. 能跑，但想搞懂参数到底在干什么 → 看「机制与参数」那一组，尤其是 DynamicVRAM 和缓存模式两篇，它们是其它参数的地基。
  4. 要放到服务器上给团队用 → 看「部署实战」和「安全与选型」两组，尤其是公网暴露那篇——认证在官方仓库仍是一个 open 的 feature request，这个前提会影响你的整个方案。
  5. 冲着 MiniMax H3 来的 → 直接跳到「在 ComfyUI 里跑 MiniMax H3」那一组。

有三件事这个专题回答不了，先说清楚免得你白找：具体显卡该买哪张（官方只给了一个 wiki 链接，我们没有取过其内容，也没有实测数据）、各模型的显存占用与生成耗时（没有实测就没有数字）、画质好坏的横向对比（同上）。凡是这三类问题，本专题一律不给结论。

专题全部内容

入门与安装

机制与参数

部署实战

安全与选型

在 ComfyUI 里跑 MiniMax H3

排查与故障

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

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员