ComfyUI 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

ComfyUI 是一个以节点图（node graph）为核心的扩散模型图形用户界面、应用程序接口（API）与后端引擎。项目使用 Python 编写，默认分支为 master，许可证为 GPL-3.0；资料中的仓库统计为 127891 个 Star 和 15058 个 Fork。

它把模型加载、提示词编码、采样、条件控制、解码、后处理和媒体输出组织为可连接的节点。README 明确列出图像、视频、音频、3D、文本和视觉处理能力，同时提供本地运行、桌面应用、Windows 便携包、手动安装与官方云版本等使用路径。

• 项目类型：模块化 AI 内容创作引擎，提供 GUI、API 和后端。
• 主要交互：通过节点图构建、保存和复用工作流。
• 运行方式：支持 Windows、Linux 和 macOS；手动安装说明覆盖 NVIDIA、AMD、Intel、Apple Silicon 与 Ascend GPU 类型。
• 版本信息：仓库 pyproject.toml 中的项目版本为 0.33.0。
• 适用重点：需要控制模型、参数、执行顺序和输出过程的本地创作或生产流程。

定位与目标用户

本项目的核心定位不是单一模型的图片生成前端，而是把不同模型组件与处理步骤组合成可执行工作流的模块化引擎。节点图同时承担编排、复用和参数可视化职责，API 则用于将工作流接入应用程序或生产流水线。

目标用户包括需要逐项调整推理过程的视觉专业人员、需要保存和复用复杂流程的创作者，以及希望在本地部署模型并通过接口集成生成能力的开发团队。README 还提到 App Mode 可将复杂工作流呈现为简单界面，因此面向最终使用者时不必暴露全部节点细节。

核心使用模型

• 创作型使用：在画布中连接节点，调整提示词、模型、条件控制、遮罩和输出参数，再将图或媒体加入队列执行。
• 流程型使用：将工作流保存为 JSON，或从受支持的生成媒体中恢复完整工作流与种子值。
• 集成型使用：使用本地 API 将已构建的工作流嵌入应用程序或生产管线。
• 封装型使用：用可复用子图、工作流模板和 App Mode 降低复杂工作流的操作门槛。

核心功能

ComfyUI 的功能边界由节点、模型组件和执行队列共同决定。一个工作流的输入可以是文本、图像、遮罩、参考条件或其他媒体，节点执行后输出潜空间数据、图像帧、音频、3D 或文本相关结果，具体输入输出由所选节点定义。

节点图工作流

节点图（node graph）将每个处理步骤表示为节点，并通过连线传递数据。执行时，系统根据图中的依赖关系运行相关节点；README 提到支持异步排队与部分图重新执行，这意味着修改局部参数时，执行系统可以围绕受影响的图部分重新计算，而不是把所有步骤都视为独立的手工操作。

工作流可保存为 JSON，便于复用和移植。对于受支持的生成媒体，ComfyUI 还可以恢复完整工作流与种子值，输入文件因此不仅是结果展示物，也可以成为后续编辑的流程入口。

模型组件与条件控制

项目支持加载完整检查点，也支持将扩散模型、变分自编码器（VAE）、文本编码器、低秩适配器（LoRA）、ControlNet、适配器和放大器分别加载。分离式加载使工作流可以独立替换模型组件，但实际可用性仍取决于模型格式、节点实现、硬件资源和相应模型文件是否已经准备完成。

内置工具覆盖修复绘制（inpainting）、扩图（outpainting）、参考条件、遮罩与合成、模型合并、放大、帧插值、分割、深度估计和媒体处理。这些能力并不是一个单独按钮的固定流程，而是由多个节点组成；输入通常包括图像、遮罩、条件或模型，输出则交给后续采样、解码或媒体处理节点。

多模态内容生成

README 的工作流分类包括图像生成、图像编辑、视频生成、音频与视频生成、音频生成、3D 与视觉、文本生成。项目原生支持的模型列表包含 Stable Diffusion 1.5、SDXL、SD3.5、Flux.1、Flux.2、Qwen Image、Wan 2.1 和 2.2、LTX-Video、Hunyuan3D、SAM 3 和 3.1、Qwen3 与 Qwen3-VL 等，列表仅代表 README 中列出的模型范围，并不构成对每个模型运行条件的完整说明。

对于闭源模型，README 通过 Partner nodes 提供访问入口，并列举 Nano Banana、Seedance 和 Hunyuan3D 等名称。此类节点涉及外部服务或付费 API 时，数据传输、账号、费用、可用区域和服务条款不能从 ComfyUI 核心仓库的资料中推断，部署前应分别核对对应服务说明。

离线运行与扩展

README 声明核心在完全离线状态下运行，除非用户主动请求，否则核心不会下载内容。使用 --disable-api-nodes 可以禁用可选的付费 Comfy API nodes，并强制内置功能保持离线；这项参数适用于需要明确限制外部 API 调用的本地或隔离环境。

项目允许通过自定义节点扩展功能，也可以通过 extra_model_paths.yaml 配置额外的模型位置。自定义节点和外部模型不是核心仓库资料可以统一保证的组件，安装前应审查其代码来源、许可证、模型授权和网络行为。

系统架构与关键模块

从仓库描述和 README 的功能边界看，系统可以理解为“前端画布、工作流定义、节点执行引擎、模型与内存管理、API 接入”几个协同层。以下结构是根据项目公开描述归纳的逻辑架构，不等同于仓库内部已经公布的正式模块图。

逻辑分层

1. 交互层：提供节点画布、工作流编辑、队列操作、App Mode 和模板入口，负责把用户操作转换为工作流数据。
2. 工作流层：以节点和连线表达执行依赖，支持 JSON 保存、加载以及从受支持媒体恢复工作流。
3. 执行层：负责异步队列、依赖节点执行、部分图重新执行及结果传递。
4. 资源层：处理显存与内存管理、模型卸载、量化模型和模型组件加载。
5. 服务层：提供本地 API，供外部应用和生产流程调用；可选 API nodes 则属于需要单独控制的外部服务能力。

一次工作流的处理路径

以文本到图像为例，用户输入文本并选择模型后，节点图会把文本交给文本编码节点，把编码结果与模型、采样参数交给采样相关节点，再经 VAE 解码为图像，最后由保存或后处理节点输出。该路径是对扩散工作流概念的说明；仓库资料没有提供统一的节点名称、接口签名或固定 JSON schema，因此不能据此推导具体 API 请求格式。

视频、音频、3D 和视觉任务会增加相应的编码、时序、几何或分析节点。README 明确提到部分图重新执行、模型卸载以及量化模型支持，但没有在给定资料中提供调度算法、显存阈值、并发模型或性能基准，这些实现细节应以对应版本源码和官方文档为准。

依赖与运行环境

项目元数据要求 Python 版本为 >=3.10，项目语言为 Python。README 给出的平台范围为 Windows、Linux 和 macOS；手动安装路径列出的硬件类型包括 NVIDIA、AMD、Intel、Apple Silicon 和 Ascend。

资料未提供完整的依赖锁定文件、CUDA 或其他 GPU 运行时版本、最低显存、CPU 要求、磁盘空间要求，也没有给出所有模型的兼容性矩阵。部署时不能仅凭项目版本推断某个模型或硬件后端一定可用。

快速开始

官方资料提供三类本地入口：Windows 与 macOS 桌面应用、Windows 便携包，以及覆盖所有操作系统和所列 GPU 类型的手动安装；此外还有官方云版本。给定资料没有包含完整的手动安装命令、启动脚本名称、依赖安装命令或验证接口，因此下面只给出不会伪造入口细节的最小闭环说明。

安装路径选择

1. Windows 或 macOS：优先查看官方桌面应用页面。
2. Windows 且需要便携目录：查看 Windows Portable Package 说明。
3. 其他操作系统或硬件：查看 Manual Install 说明，并先确认 Python 满足 >=3.10。
4. 不使用本地硬件：查看 Comfy Cloud 页面；云版本的价格、配额和服务级别不在本仓库资料中。

最小可运行示例

下列命令只使用资料中明确出现的仓库地址、Python 版本条件和离线参数。资料未给出启动入口文件、依赖文件名、端口和健康检查接口，因此不能在此虚构完整的启动命令；安装与运行的准确命令应以最新 README 的 Manual Install 章节为准。

# 安装前确认 Python 满足项目元数据要求
python --version

# 获取项目源码；仓库地址来自项目资料
git clone https://github.com/Comfy-Org/ComfyUI

# 进入源码目录
cd ComfyUI

# 运行参数示例：README 明确提供该参数，用于禁用可选 API nodes
# 官方仓库未提供启动入口，以下位置不填入未经资料确认的脚本名
# <官方启动命令> --disable-api-nodes

其中 <官方启动命令> 不是可执行命令，而是待从最新 README 确认的占位符。由于给定资料没有列出安装依赖和启动文件，以上示例的“安装”阶段仅完成源码获取，“运行”和“验证”阶段必须依据官方安装章节补齐，不能把占位符误当作真实命令。

验证思路

本地验证至少应确认三件事：程序能够按官方入口启动、工作流可以进入队列、输出能够按所选节点保存或返回。README 明确给出的快捷键是 Ctrl + Enter，其作用为将当前图加入生成队列；端口、健康检查路径和 API 请求示例在给定资料中未提供。

验证清单：
1. Python 版本满足 >=3.10。
2. 按最新 README 的手动安装步骤完成依赖安装。
3. 使用官方启动入口启动本地实例。
4. 加载官方模板工作流或示例工作流。
5. 使用 Ctrl + Enter 将当前图加入生成队列。
6. 检查工作流定义的输出节点是否产生结果。

配置说明

仓库资料中可核验的配置主要来自 pyproject.toml 项目元数据和 README 命令行参数。下表不把未公开的端口、环境变量或启动参数写成事实；缺失项统一标注为未提供。

表中 --disable-api-nodes 的“默认值”仅表示资料没有说明启动时默认是否启用，不能理解为固定的程序默认行为。端口、日志级别、并发数、缓存大小、模型目录字段和 API 认证配置均未在给定资料中说明。

进阶用法

进阶使用的重点是把工作流当作可版本化、可复用和可集成的资产，而不是只保存最终媒体。复杂流程可以通过子图和模板封装，再利用 App Mode 对外提供更简单的操作界面。

工作流复用与模板化

建议将关键工作流以 JSON 保存，并同时记录所用模型组件、节点来源、输入素材和许可信息。README 提供了新版模板工作流和旧版示例工作流入口，但给定资料没有列出具体模板文件内容、节点清单或兼容版本，因此模板加载失败时应先核对模板与当前核心版本。

可复用子图适合把重复的预处理、条件控制、采样或后处理步骤封装起来。App Mode 则适合把稳定工作流的少量输入暴露给非技术用户；根据本文作者的经验判断，正式使用前应为模型缺失、节点缺失和资源不足保留可诊断的错误路径，而不是只保留简化后的界面。

本地 API 与生产管线

README 明确说明项目提供本地 API，可用于把工作流接入应用程序。API 的具体端点、请求体、响应格式、认证机制和队列语义没有出现在给定资料中，不能根据“提供 API”这一描述编写未经核验的接口签名。

在集成场景中，应先固定一份经过验证的工作流 JSON，再围绕输入、队列状态、输出文件和错误信息设计适配层。若接入外部应用，建议将 ComfyUI 置于内网或受控主机，并在应用层完成访问控制；这属于部署设计建议，不是仓库声明的内置安全能力。

模型路径与自定义节点

通过 extra_model_paths.yaml 可以声明额外模型位置，适合已有模型目录与项目目录分离的场景。配置文件样例的具体键名和层级未在资料正文中展开，不能在此补写 YAML 字段；应以仓库中的 extra_model_paths.yaml.example 和对应文档为准。

自定义节点可以扩展核心能力，但它们会进入工作流执行路径，可能读取输入素材、加载模型或访问网络。安装第三方节点前应进行源码审查和许可证核验，并在隔离环境中测试；不要因为节点能够被导入就将其视为 ComfyUI 核心的一部分。

可观测性与运维

给定资料强调异步排队、部分图重新执行、显存与内存管理、模型卸载及量化模型支持，但没有给出正式的监控指标、日志格式、健康检查端点、告警规则或高可用方案。运维设计因此需要区分“项目具备的执行能力”和“部署方需要补充的可观测性”。

• 作业层：记录工作流标识、输入来源、模型组件、队列提交时间、执行结果和失败节点。
• 资源层：观察显存、内存、模型加载与卸载行为；具体指标名称和采集接口未提供。
• 版本层：稳定发布与 master 分支应分开管理。README 警告稳定标签之外的提交可能不稳定，并可能破坏许多自定义节点。
• 变更层：核心、桌面应用和前端存在相互关联的发布流程，升级前应同时检查三者的兼容说明。
• 数据层：为输入素材、模型文件、工作流 JSON 和输出结果设计独立的备份与留存策略。

README 描述的发布节奏是：核心大版本约每两周发布一次，目标为每周一但会因模型发布或大型代码变更而调整；桌面应用基于最新稳定核心构建，前端更新以两周以上的周期合入核心。该节奏不能被解释为 SLA，也不能替代生产环境的变更冻结和回滚方案。

安全与合规边界

ComfyUI 面向内容生成与处理，不是授权管理、数据脱敏或合规审计系统。凡是处理个人图像、内部素材、客户数据或闭源模型接口的部署，都应在获得授权的环境中进行，并由使用方负责数据治理。

授权与隐私

• 仅处理拥有合法使用权或已取得授权的图像、音频、视频、文本、3D 素材和模型文件。
• 启用 Partner nodes 或其他外部 API nodes 前，确认输入数据是否会离开本地环境，并核对服务方的隐私政策、数据留存和使用条款。
• 对本地 API 设置网络边界和访问控制，避免将未认证的生成服务直接暴露到互联网；仓库资料没有声明内置认证方案。
• 第三方自定义节点应在隔离环境中运行和审查，尤其要检查文件访问、网络请求和动态执行行为。
• 对生成结果进行人工或业务审核，不把模型输出自动视为事实、授权内容或合规内容。

README 声明核心默认不会主动下载内容，并提供 --disable-api-nodes 以禁用可选付费 API nodes。该选项有助于缩小网络边界，但不能替代操作系统权限控制、容器隔离、出口防火墙、日志审计和敏感数据分级。

许可证与商用条款

仓库许可证为 GNU General Public License version 3（GNU GPL-3.0），许可证文件明确将其定义为带有 copyleft 条款的自由软件许可证。LICENSE 序言说明，GPL 允许复制、修改和分发，并允许分发者收费；因此，从许可证文本的一般授权范围看，商业使用并非被许可本身禁止。

商业分发或提供修改版本时，不能只关注是否收费，还必须遵守 GPL-3.0 的对应条件。LICENSE 要求分发者向接收者提供相同自由、提供或允许取得源代码，并展示许可证条款；修改版本还应明确标记修改，以免将修改版问题归因于原作者。

• 分发 ComfyUI 或其受 GPL-3.0 覆盖的修改版本时，应保留版权和许可证信息。
• 向他人传递覆盖作品时，应按 GPL-3.0 提供相应源代码或获取源代码的方式。
• 许可证文件声明软件不提供保证，具体免责声明和分发条件以仓库 LICENSE 为准。
• 模型、LoRA、ControlNet、外部 API、第三方节点及其生成内容的许可不一定与 ComfyUI 核心相同，应分别核验。

以上内容是对仓库 LICENSE 的信息整理，不构成法律意见。企业将其集成到产品、提供托管服务或分发修改版本时，应由法务依据实际交付方式审查；不确定的部分以仓库 LICENSE 为准。

局限性与已知限制

项目提供了很宽的模型和媒体工作流范围，但“支持某模型”不等于在任意硬件、任意版本和任意节点组合下都能直接运行。模型文件、格式、显存、依赖、节点版本和工作流版本之间存在耦合，给定资料没有提供统一的兼容性或性能保证。

• 资源要求未量化：没有提供最低显存、内存、磁盘、生成时延或吞吐基准。
• 接口细节不完整：本资料没有给出本地 API 的端点、认证、请求体和响应体定义。
• 安装细节缺失：给定 README 片段没有列出完整安装命令、启动文件、端口或依赖锁定信息。
• 生态兼容性风险：README 明确提示稳定标签之外的提交可能不稳定，并可能破坏自定义节点。
• 外部服务边界：Partner nodes 和付费 API nodes 的服务条款、费用、隐私和可用性不属于核心 GPL 项目资料能够保证的范围。
• 输出责任：生成结果的真实性、版权、肖像权、内容安全和行业合规性不能由工作流引擎自动担保。

根据本文作者的经验判断，最容易被低估的运维成本不是画布本身，而是模型资产管理、节点版本固定、失败任务重试策略和输出审核流程。若这些内容未纳入交付设计，工作流从个人实验迁移到团队环境时会出现可复现性问题。

适合谁

以下信号表明 ComfyUI 与需求匹配度较高，尤其适合需要显式控制生成链路而非只使用固定表单的团队。

• 需要同时编排模型、VAE、文本编码器、LoRA、ControlNet、适配器和后处理步骤，并希望逐节点调整参数。
• 需要保存 JSON 工作流、复用子图或模板，并要求同一流程能够被创作者和应用程序重复调用。
• 团队已有 Python、本地 GPU 或模型文件管理能力，能够承担环境安装、显存排查和节点版本维护。
• 需要在 Windows、Linux 或 macOS 上本地运行，并且对离线处理或本地数据边界有明确要求。
• 需要把图像流程扩展到视频、音频、3D、视觉或文本，并接受针对不同模型分别准备工作流和资源。

不适合谁

以下情况不宜直接把 ComfyUI 作为唯一方案，或至少应先验证桌面应用、云版本和目标模型的实际可用性。

• 只需要固定功能、固定参数和统一表单，不希望维护节点图、模型文件或自定义节点。
• 团队没有可管理的本地运行环境，且又要求零配置、固定价格、固定配额或明确 SLA；这些承诺不在仓库资料中。
• 需要直接获得企业级认证、审计、租户隔离、自动扩缩容或高可用集群，而不准备在外围系统补充这些能力。
• 需要大规模并发处理，却没有经过目标模型、硬件、队列和内存行为验证；仓库资料未提供吞吐和并发基准。
• 处理的数据受到严格地域、隐私或版权限制，却计划直接启用外部 Partner nodes 或付费 API nodes，且无法完成供应商条款审查。

常见问题与排查（FAQ / Troubleshooting）

排查时应先区分核心程序、模型资产、第三方节点、前端版本和外部 API。下面的判断只使用仓库资料能够支持的边界，未提供的具体日志命令和接口路径应以官方文档为准。

为什么无法直接给出统一安装命令

给定资料包含桌面应用、Windows 便携包和手动安装入口，但没有展开手动安装章节的命令、依赖文件和启动入口。官方仓库未提供该信息，建议以最新 README 为准；不要把本文中的占位符当成真实命令执行。

如何确认是否发生了外部 API 调用

README 明确提供 --disable-api-nodes，该参数用于禁用可选的付费 Comfy API nodes，并强制内置功能保持离线。若业务要求本地隔离，应在启动方式、网络出口和节点清单三个层面同时核验，不能只依据界面是否显示某个节点。

工作流在更新后无法加载怎么办

先确认核心是否从稳定标签升级到 master 或其他稳定标签之外的提交。README 已提示这类提交可能不稳定并可能破坏自定义节点；随后固定工作流 JSON、模型组件、第三方节点版本，并使用官方模板或示例逐项定位缺失节点。

为什么模型文件已存在但节点仍不可用

模型可以是完整检查点，也可以拆分为扩散模型、VAE、文本编码器、LoRA、ControlNet、适配器和放大器。应检查工作流要求的组件类型、文件格式、模型路径配置及节点实现；额外模型路径应参考 extra_model_paths.yaml.example，具体字段在给定资料中未展开。

能否据此确定端口或 API 请求格式

不能。资料只说明存在本地 API，没有提供端口、路径、方法、认证方式、请求体或响应体；官方仓库未提供该信息，建议以最新文档为准。生产集成前应为接口版本、错误处理、超时和队列状态建立独立测试。

如何处理显存或内存不足

README 列出智能显存与内存管理、模型卸载和量化模型支持，但没有给出具体开关、阈值或硬件基准。应先减少工作流中的模型组件和输入规模，记录实际资源使用，再根据目标硬件的官方安装与模型说明选择相应配置；不要从项目描述推导固定显存要求。

发布与版本管理

版本管理需要同时关注核心、桌面应用和前端三个相互关联的仓库。核心大版本约每两周发布一次，补丁版本用于当前稳定版本的修复回移；README 还说明小版本用于从 master 分支发布。

1. 生产环境优先选择经过验证的稳定标签，不直接把未标记提交作为长期基线。
2. 升级前保存工作流 JSON、模型清单、节点清单和当前版本信息。
3. 同时检查 Comfy Desktop 与 ComfyUI Frontend 的发布关系。
4. 在隔离环境中验证模板、模型加载、队列执行和输出恢复。
5. 保留旧版本运行目录或可回滚源码，以便处理自定义节点不兼容。

上述流程是根据 README 发布说明整理的运维建议。仓库资料没有提供长期支持版本、弃用周期或安全修复承诺，不能将发布节奏理解为维护 SLA。

项目地址与资源

以下链接均来自项目元数据或 README 中出现的官方入口，适合用于获取源码、安装方式、文档、工作流和服务说明。

• ComfyUI GitHub 仓库
• ComfyUI 官网
• ComfyUI 官方文档
• ComfyUI Desktop 下载页面
• Comfy Cloud 官方页面
• 新版模板工作流
• ComfyUI 示例工作流
• Partner nodes 官方说明
• Comfy API nodes 官方说明
• ComfyUI 核心版本发布页
• Comfy Desktop 仓库
• ComfyUI Frontend 仓库