ComfyUI 超级详细中文文档#

适用范围：ComfyUI Desktop、Windows Portable、手动安装版、服务器/API 部署。
文档版本：2026.08
资料核对日期：2026-08-10
目标读者：零基础用户、AI 绘图进阶用户、工作流作者、自动化开发者、自定义节点开发者。
官方项目：Comfy-Org/ComfyUI
重要说明：ComfyUI、PyTorch、显卡驱动、模型格式和第三方节点更新很快。本文重点讲稳定的原理与排错方法；涉及版本号、安装命令和硬件后端时，请以官方文档与 PyTorch 安装选择器为准。

目录#

1. ComfyUI 是什么
2. 一分钟理解核心架构
3. 安装方式选择
4. 详细安装指南
5. 首次启动与界面导览
6. 第一个文生图工作流
7. 节点、端口、连接与数据类型
8. 模型体系与目录管理
9. 提示词与条件控制
10. 采样器、调度器与关键参数
11. 图生图
12. 局部重绘与扩图
13. LoRA 使用与管理
14. ControlNet 与结构控制
15. IPAdapter、参考图与身份一致性
16. 高清修复、放大与细节增强
17. 批量生产与工作流工程化
18. 视频、音频与 3D 工作流概览
19. 自定义节点与 ComfyUI Manager
20. 性能、显存与速度优化
21. 工作流 JSON、模板与版本管理
22. 本地 API 与自动化调用
23. 自定义节点开发入门
24. 服务器部署与安全
25. 常见错误与系统化排错
26. 最佳实践与检查清单
27. 术语表
28. 官方资料与延伸阅读

1. ComfyUI 是什么#

ComfyUI 是一个以**节点图（node graph）**为核心的生成式 AI 推理界面与执行引擎。你不只是填写提示词并点击“生成”，而是把模型加载、文本编码、潜空间初始化、条件注入、采样、VAE 解码、图像保存等步骤连接成一张可视化计算图。

它的核心价值有五点：

1. 透明：生成过程不再是黑盒，每一步都能看见、替换和复用。
2. 灵活：同一界面可组合文生图、图生图、局部重绘、ControlNet、LoRA、视频、音频、3D 等能力。
3. 高效：只重新执行发生变化的分支，并缓存未变化的中间结果。
4. 可复现：工作流、参数、种子和模型组合可保存为 JSON，也可嵌入生成图片元数据。
5. 可自动化：前端使用的工作流可以转换为 API 格式，通过 HTTP/WebSocket 调度。

1.1 它与传统“一键式 WebUI”的区别#

1.2 适合哪些人#

• 想精确控制 Stable Diffusion、Flux、SDXL、视频模型等生成流程的人。
• 需要制作可重复、可交付的生产工作流的人。
• 希望批量生成商品图、概念图、分镜、素材、数据集的人。
• 需要把图片生成能力接入脚本、网站、机器人或生产系统的开发者。
• 想编写自定义节点、算法实验或模型推理原型的研究者。

1.3 不适合哪些场景#

• 只想偶尔输入一句话快速出图，而且不愿意理解节点关系。
• 无法接受模型、节点与工作流之间存在版本兼容问题。
• 需要将未经保护的本地服务直接暴露到公网。

2. 一分钟理解核心架构#

一个最基础的扩散模型文生图流程可以表示为：

Checkpoint Loader
├─ MODEL ───────────────┐
├─ CLIP → 正向提示词 ──┤
│       → 负向提示词 ──┤→ KSampler → LATENT → VAE Decode → Save Image
└─ VAE ────────────────────────────────────────┘
Empty Latent Image ────────────────────────────┘

从概念上看：

1. Checkpoint Loader 加载模型，通常输出 MODEL、CLIP、VAE。
2. CLIP Text Encode 把文字变为模型可理解的条件向量 CONDITIONING。
3. Empty Latent Image 创建潜空间画布，决定宽、高、批量数。
4. KSampler 在噪声中进行多步去噪，输出潜空间结果 LATENT。
5. VAE Decode 把潜空间转换为可见图像 IMAGE。
6. Save Image 将图片写入输出目录，并通常保留工作流元数据。

2.1 三个必须掌握的空间#

像素空间（IMAGE）#

人能直接看到的 RGB 图像。上传图片、预处理、合成、保存通常发生在这里。

潜空间（LATENT）#

扩散模型主要工作的压缩表示。潜空间尺寸远小于像素空间，因此采样更高效。潜空间必须由对应 VAE 解码后才能成为可见图片。

条件空间（CONDITIONING）#

提示词、ControlNet、区域条件、风格条件等被编码后的信息。采样器根据这些条件决定去噪方向。

2.2 ComfyUI 为什么能“只算变化部分”#

ComfyUI 会分析依赖关系和节点输入。若你只修改提示词，模型加载节点的输入未变，就可能复用已加载模型；若只调整保存前的后处理，也不必重新运行无关分支。这种惰性执行、图依赖分析与缓存是复杂工作流高效运行的关键。

3. 安装方式选择#

先根据场景选路线，不要一上来就混用多套安装方法。

3.1 安装前硬件判断#

重点不是“能不能打开”，而是“模型能不能在你的内存/显存内稳定推理”。

• GPU 显存：决定模型规模、分辨率、批量数、ControlNet 数量和视频长度。
• 系统内存：模型加载、低显存卸载、视频帧和多模型工作流会大量占用 RAM。
• 磁盘：一个模型可能数 GB 到数十 GB；缓存、输出和自定义节点也会持续增长。
• 驱动与计算后端：NVIDIA/CUDA、AMD/ROCm、Apple Metal、Intel XPU 等路径不同。

经验原则：

• 8GB 显存可以做许多静态图工作流，但高分辨率、大模型与多控制器需要更激进的优化。
• 12–16GB 更适合 SDXL、Flux 的常见工作流。
• 24GB 及以上更适合多模型、视频、训练辅助与高分辨率批量任务。
• CPU 模式通常只适合验证、排错或极小工作流，不适合高效生产。

4. 详细安装指南#

4.1 ComfyUI Desktop#

1. 从 ComfyUI 官方下载页获取与你系统匹配的安装包。
2. 安装并启动。
3. 首次启动时选择数据/模型目录，确认磁盘空间充足。
4. 让程序完成 Python 环境与组件初始化。
5. 进入界面后先运行默认工作流，确认服务、前端与计算后端正常。
6. 再添加模型与自定义节点，不要在首次启动前一次性塞入大量第三方插件。

Desktop 版的优势是安装和更新体验更统一。遇到问题时，需要区分：

• Desktop 外壳问题；
• ComfyUI 后端问题；
• 前端问题；
• 模型或自定义节点问题。

4.2 Windows Portable#

典型流程：

1. 下载官方便携包。
2. 解压到路径短、权限正常、非系统保护目录的位置，例如 D:\AI\ComfyUI。
3. 避免目录中包含罕见符号、超长路径或被同步盘锁定。
4. 将模型放入 ComfyUI\models\ 对应子目录。
5. 使用包内针对显卡后端的启动脚本。
6. 浏览器打开本地地址，通常是 http://127.0.0.1:8188。

建议：

• 不要把整个目录放进 OneDrive 等实时同步目录。
• 不要随意使用系统 Python 覆盖便携包自带 Python。
• 安装节点依赖时，应使用便携环境中的 Python，而不是另一个全局 Python。

4.3 手动安装：通用流程#

下面是一条便于维护的手动安装思路。具体 PyTorch 命令必须按你的显卡和当前版本核对。

# 1. 获取代码
git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI

# 2. 创建虚拟环境
python -m venv .venv

# 3. 激活环境
# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
# .venv\Scripts\Activate.ps1

# 4. 安装与你硬件匹配的 PyTorch
# 请使用 PyTorch 官方安装选择器生成命令

# 5. 安装 ComfyUI 依赖
pip install -r requirements.txt

# 6. 启动
python main.py

为什么先安装 PyTorch#

PyTorch 包与 CUDA、ROCm、XPU、Metal 路径高度相关。先明确后端，可以避免依赖安装时拉取错误的构建版本。

4.4 NVIDIA GPU#

检查：

nvidia-smi

关注驱动是否识别 GPU。然后从 PyTorch 官方安装选择器获取与你系统和 CUDA 构建匹配的命令。安装后验证：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'NO CUDA')"

如果 torch.cuda.is_available() 为 False，常见原因包括：

• 安装了 CPU 版 PyTorch；
• 驱动过旧或异常；
• 当前 Python 环境与启动 ComfyUI 的环境不是同一个；
• 系统中 CUDA 工具包版本与 PyTorch wheel 概念混淆。多数情况下，关键是驱动与 PyTorch 自带运行时兼容，而不是强行安装很多本地 CUDA 工具包。

4.5 AMD GPU#

Linux 上通常走 ROCm 路线；Windows 支持状态、模型兼容性和推荐方案会随版本变化。应优先查看 ComfyUI 与 PyTorch 当前官方说明。

验证示例：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.hip)"

注意：PyTorch 在 ROCm 下仍可能复用 torch.cuda 命名空间，这不代表你安装了 NVIDIA CUDA。

4.6 Apple Silicon#

Apple Silicon 通常通过 PyTorch MPS/Metal 后端运行。建议：

• 使用官方支持的较新 macOS；
• 使用原生 arm64 Python；
• 避免在 Rosetta x86 Python 与 arm64 环境间混装依赖；
• 预留足够统一内存；
• 若个别算子不支持 MPS，可能回退 CPU 或报错。

验证：

python -c "import torch; print(torch.backends.mps.is_available()); print(torch.backends.mps.is_built())"

4.7 Intel GPU 与其他后端#

Intel Arc/XPU、DirectML 等方案的可用性会随 PyTorch 和 ComfyUI 演进。原则是：

1. 先确认官方当前支持路径；
2. 使用匹配的 PyTorch 构建；
3. 用最小工作流验证；
4. 再安装大型模型与第三方节点。

4.8 更新 ComfyUI#

手动 Git 安装通常可执行：

git pull
pip install -r requirements.txt

更新前建议：

git status
python -m pip freeze > requirements-lock-before-update.txt

若你修改过核心文件，git pull 可能冲突。正确做法是将个性化功能放到自定义节点中，而不是改核心源码。

4.9 启动参数的使用原则#

查看当前版本支持的完整参数：

python main.py --help

常见需求包括：

• 修改监听地址；
• 修改端口；
• 低显存模式；
• CPU 模式；
• 预览方法；
• 输出目录；
• 禁用某些前端/管理功能。

不要从旧教程机械复制整串参数。启动参数可能改名、废弃或改变默认值，--help 才是你本机版本的准确信息。

5. 首次启动与界面导览#

5.1 画布#

画布用于放置与连接节点：

• 滚轮缩放；
• 中键或空格拖动平移；
• 选中节点后拖动；
• 框选多个节点；
• 复制、粘贴、删除；
• 将节点分组、改色、折叠；
• 通过搜索菜单添加节点。

不同前端版本的快捷键与菜单位置可能变化，建议打开内置快捷键/帮助面板查看。

5.2 节点#

一个节点通常包括：

• 标题；
• 输入端口；
• 输出端口；
• 可编辑控件；
• 节点执行状态；
• 错误提示。

可被连线驱动的输入，经常能在“控件”和“输入端口”之间转换。这对参数自动化、批处理和子图封装很有用。

5.3 队列#

ComfyUI 不是“点击一次同步等待一次”的简单页面。任务会进入队列：

• 当前任务正在执行；
• 后续任务排队；
• 可查看历史；
• 可中断当前执行；
• 可清空待执行任务。

中断不一定立刻释放所有显存，因为模型仍可能保留在内存中供下一次使用。

5.4 工作流与模板#

常见保存方式：

• 保存为工作流 JSON；
• 导出 API 格式 JSON；
• 保存模板；
• 从带工作流元数据的 PNG/WebP 导入；
• 从示例工作流或模型模板开始。

5.5 日志窗口#

遇到错误时，网页红框只是摘要。真正有价值的信息通常在启动终端：

• Python traceback；
• 缺失模块；
• 模型加载失败；
• CUDA/ROCm/MPS 错误；
• 节点注册失败；
• 依赖冲突。

养成保留启动终端的习惯。

6. 第一个文生图工作流#

6.1 需要的核心节点#

• Load Checkpoint / Checkpoint Loader
• 两个 CLIP Text Encode：正向、负向
• Empty Latent Image
• KSampler
• VAE Decode
• Save Image 或 Preview Image

6.2 连接步骤#

1. Load Checkpoint.MODEL → KSampler.model
2. Load Checkpoint.CLIP → 两个文本编码节点的 clip
3. 正向文本编码输出 → KSampler.positive
4. 负向文本编码输出 → KSampler.negative
5. Empty Latent Image.LATENT → KSampler.latent_image
6. KSampler.LATENT → VAE Decode.samples
7. Load Checkpoint.VAE → VAE Decode.vae
8. VAE Decode.IMAGE → Save Image.images

6.3 推荐的首次验证参数#

这不是“最佳参数”，而是易于排错的起点：

• 分辨率：先用模型原生常见分辨率；
• Batch：1；
• Steps：20–30；
• CFG：根据模型家族使用常见区间，不同架构差异很大；
• Denoise：1.0；
• Seed：固定一个整数；
• Sampler/Scheduler：先使用模板默认组合。

6.4 首次出图检查#

若能生成图片，说明以下链路基本正常：

• 后端启动；
• GPU/计算设备可用；
• 模型文件可读；
• 文本编码器可用；
• 采样器可运行；
• VAE 可解码；
• 输出目录可写。

若图片是纯黑、彩噪、颜色异常或严重破碎，优先检查模型组件是否匹配，而不是只改提示词。

7. 节点、端口、连接与数据类型#

7.1 强类型连接#

ComfyUI 端口不是任意连接。常见类型：

第三方节点可以定义自己的数据类型。类型颜色只是视觉提示，不应代替阅读端口名称。

7.2 输入控件与输入连线#

固定参数可以直接写在节点控件里；需要联动、计算、批量变化的参数应转为输入：

Primitive / Math / List / Schedule
                ↓
             节点参数

这样可以实现：

• 多节点共享同一个宽高；
• 根据循环索引改变种子；
• 使用表达式计算尺寸；
• 将提示词从外部 API 注入；
• 把复杂流程封装成稳定接口。

7.3 Reroute 节点#

Reroute 用于整理长连线，减少交叉。建议：

• 主数据流从左到右；
• 模型加载放左上；
• 条件控制放中上；
• 潜空间流放中下；
• 解码和输出放右侧；
• 跨区域长线使用 Reroute。

7.4 节点组、子图与模块化#

复杂工作流应按职责分区：

• 模型装载区；
• 提示词区；
• 结构控制区；
• 主采样区；
• 二次精修区；
• 放大与后处理区；
• 输出区。

若当前前端支持子图，可将稳定模块封装为子图；否则使用分组、模板和清晰的输入/输出 Reroute 模拟模块边界。

7.5 执行顺序不是纯粹“从左到右”#

视觉位置不决定执行顺序。ComfyUI 根据输出节点反向解析依赖。没有连接到有效输出的孤立分支通常不会执行。

8. 模型体系与目录管理#

8.1 常见模型组件#

现代生成模型不一定是单一 checkpoint。常见组件包括：

• 扩散模型 / UNet / DiT；
• 文本编码器；
• VAE；
• LoRA；
• ControlNet；
• 视觉编码器；
• 放大模型；
• 人脸恢复模型；
• 视频 VAE / 时序模型；
• 音频编码器；
• 量化或分片权重。

下载工作流前，先确认它要求的是一体式 checkpoint还是分离组件。

8.2 典型目录#

具体目录以你的 ComfyUI 版本和节点说明为准。常见结构：

ComfyUI/
├─ models/
│  ├─ checkpoints/
│  ├─ diffusion_models/
│  ├─ text_encoders/
│  ├─ vae/
│  ├─ loras/
│  ├─ controlnet/
│  ├─ clip_vision/
│  ├─ upscale_models/
│  ├─ embeddings/
│  └─ ...
├─ custom_nodes/
├─ input/
├─ output/
├─ temp/
└─ user/

注意：旧教程可能使用 unet/ 等旧目录名；当前官方文档可能推荐新的目录命名。若加载器下拉框找不到文件，首先查看该节点从哪个类别扫描模型。

8.3 外部模型目录配置#

ComfyUI 支持通过额外模型路径配置复用已有模型库。典型用途：

• 多个 ComfyUI 实例共用模型；
• 与其他 UI 共用 checkpoint；
• 将模型放在大容量磁盘；
• 将程序与数据分离。

配置原则：

1. 复制官方提供的示例配置；
2. 使用正确 YAML 缩进；
3. 确保路径存在且服务账号有读取权限；
4. 修改后重启；
5. 检查启动日志中的扫描结果。

示意配置：

my_models:
  base_path: /data/ai-models
  checkpoints: checkpoints
  loras: loras
  vae: vae
  controlnet: controlnet
  upscale_models: upscale_models

Windows 路径建议使用正斜杠或规范转义，避免 \t、\n 被误解。

8.4 模型命名规范#

建议包含：

架构_用途_版本_精度_来源标识.safetensors

例如：

sdxl_productphoto_v2_fp16.safetensors
flux_style_ink_v1_rank32.safetensors
controlnet_depth_sdxl_fp16.safetensors

同时保留一个模型清单：

8.5 安全与完整性#

• 优先选择 safetensors。
• 不随意加载来源不明的 pickle/PyTorch 序列化文件。
• 校验哈希，尤其是团队共享和生产部署。
• 阅读模型许可证，区分研究、商用、署名与衍生限制。
• 模型文件可包含元数据，但不能仅靠文件名判断架构。

9. 提示词与条件控制#

9.1 提示词不是统一语言#

不同模型家族的文本编码器、训练标注和提示词偏好不同：

• 有的偏好标签式短语；
• 有的更适合自然语言长句；
• 有的对负面提示词响应弱；
• 有的使用特殊指导机制；
• 有的推荐特定 CFG 或 guidance 节点。

因此，不要把某个 SD1.5 教程的提示词格式直接套到所有新模型。

9.2 可维护提示词结构#

推荐按信息层组织：

主体：谁/什么
动作与状态：在做什么
环境：地点、时间、天气
构图：景别、视角、焦段、主体位置
光线：主光方向、软硬、色温
材质与细节：表面、纹理、服装、道具
风格与媒介：摄影、插画、3D、版画等
质量约束：只保留真正有效的描述

示例：

一名穿深蓝机能外套的女性地质学家，站在黑色玄武岩海岸，
手持岩石样本，清晨低角度侧光，阴云后的冷色天空，
中景，35mm 纪实摄影，人物位于画面右三分之一，
湿润岩石具有细腻反光，克制的电影色彩，真实皮肤纹理

9.3 负面提示词#

负面提示词用于降低不希望出现的概念，但不是“错误修复魔法”。

合理用途：

• 排除特定内容；
• 控制画面媒介；
• 减少某些常见伪影；
• 与模型推荐模板配合。

不合理做法：

• 堆几百个互相矛盾的质量词；
• 试图用负面词修复模型/VAE不匹配；
• 在对负面条件不敏感的模型上盲目加大 CFG。

9.4 权重、分段与区域提示#

提示词权重语法可能由前端和编码节点实现。区域提示通常需要：

1. 创建区域或遮罩；
2. 编码各自提示词；
3. 将条件限制到指定区域；
4. 合并为总条件；
5. 输入采样器。

区域提示适合多主体和版式控制，但边界过硬时可能出现拼贴感。应配合柔化遮罩、重叠区域或二次精修。

9.5 Seed 的正确理解#

Seed 初始化随机噪声。固定 seed 的意义是让比较更可控：

• 比较 LoRA 权重；
• 比较采样器；
• 比较 ControlNet 强度；
• 调整提示词局部内容。

但只要模型版本、设备精度、节点实现、分辨率或流程改变，像素级复现仍可能失效。

10. 采样器、调度器与关键参数#

10.1 Steps#

步数是去噪迭代次数。更多并不必然更好：

• 太少：结构未收敛、细节不足；
• 合适：质量与速度平衡；
• 太多：收益递减，甚至改变质感或增加伪影。

应以模型作者推荐区间为起点，通过固定 seed 做对照。

10.2 CFG / Guidance#

CFG 表示条件引导强度的一类实现。一般规律：

• 太低：提示词约束不足；
• 合适：语义和自然度平衡；
• 太高：过饱和、边缘发硬、细节“烧焦”、构图僵硬。

新模型可能采用不同 guidance 机制，不能把“7 是万能值”当作规则。

10.3 Sampler#

采样器是数值求解方法。常见差异：

• 收敛速度；
• 随机性；
• 纹理锐度；
• 对低步数的适应；
• 是否适合祖先采样；
• 与 scheduler 的组合表现。

选择方法：

1. 从官方/模板默认组合开始；
2. 固定其他参数；
3. 生成网格比较；
4. 用目标任务而非单张“惊艳图”判断。

10.4 Scheduler#

Scheduler 决定各步使用的噪声/σ 序列。相同 sampler 配不同 scheduler，结果可能显著变化。

10.5 Denoise#

denoise 表示重绘强度的一类控制：

• 1.0：通常从完整噪声开始，适合纯文生图；
• 较低值：更多保留输入潜空间结构；
• 太低：变化有限；
• 太高：输入图结构被重写。

图生图和高清修复中，denoise 往往比提示词更直接决定“保留多少原图”。

10.6 分辨率与潜空间约束#

许多模型对尺寸步长有要求，常见是 8、16、32 或更高倍数。即使节点允许任意值，也可能内部补齐或造成形状错误。

建议：

• 先使用模型推荐分辨率；
• 保持宽高为合理倍数；
• 极端长宽比使用分块、扩图或专用工作流；
• 不要一开始就直接生成超大图。

11. 图生图#

图生图的核心是把输入图编码到潜空间，再从某个噪声强度重新采样：

Load Image → VAE Encode → KSampler(latent_image) → VAE Decode → Save

11.1 操作步骤#

1. 加载图片；
2. 必要时缩放/裁剪到合适尺寸；
3. 使用与目标模型匹配的 VAE Encode；
4. 将 latent 输入 KSampler；
5. 将 denoise 从低到高测试；
6. 解码并保存。

11.2 Denoise 经验区间#

仅作思路，不是固定规则：

• 0.1–0.25：轻微材质和细节变化；
• 0.25–0.5：保留构图，明显改变风格与局部；
• 0.5–0.75：结构开始大幅变化；
• 0.75–1.0：越来越接近重新生成。

11.3 常见问题#

输入图颜色改变#

可能原因：

• VAE 往返有损；
• 色彩空间处理差异；
• denoise 太高；
• 模型风格偏色。

构图没变化#

• denoise 太低；
• 提示词与原图高度一致；
• 控制条件过强。

人脸变形#

• 输入分辨率与模型偏好不匹配；
• 人脸在画面中太小；
• denoise 太高；
• 需要局部二次精修。

12. 局部重绘与扩图#

12.1 Mask 基础#

遮罩通常定义“允许改变的区域”，但具体黑白含义可能因节点而异。务必用小测试验证。

常见流程：

Image + Mask
   ↓
Inpaint Encode / Set Latent Noise Mask
   ↓
KSampler
   ↓
VAE Decode
   ↓
Composite / Save

12.2 局部重绘步骤#

1. 准备原图；
2. 绘制遮罩；
3. 对遮罩边缘做适度羽化；
4. 使用适合 inpainting 的编码节点或模型；
5. 描述要生成的新内容；
6. 选择合适 denoise；
7. 必要时将生成区域与原图合成。

12.3 遮罩边缘#

• 太硬：出现接缝；
• 太软：修改区域扩散过大；
• 遮罩太小：模型缺少上下文；
• 遮罩太大：无关区域被重写。

修复物体时，遮罩应略大于物体边界，让模型有空间重建过渡。

12.4 扩图（Outpainting）#

扩图是先增加画布，再把新增区域作为待生成部分：

1. 对原图 padding；
2. 生成对应 mask；
3. 将扩展后的图与遮罩编码；
4. 使用描述场景延伸的提示词；
5. 采样；
6. 必要时分方向多次扩展，而不是一次增加巨大区域。

12.5 接缝排查#

• 检查 mask 是否覆盖边界；
• 增加羽化；
• 让采样区域包含更多原图上下文；
• 降低或提高 denoise 做对照；
• 检查 VAE 和 inpaint 模型是否匹配；
• 最后用局部细化消除纹理差异。

13. LoRA 使用与管理#

LoRA 是对基础模型的低秩增量适配，常用于风格、人物、服装、动作、物体或画面能力增强。

13.1 基础连接#

Checkpoint MODEL ─┐
Checkpoint CLIP ──┤→ Load LoRA → 输出 MODEL / CLIP → 后续流程
LoRA 文件 ────────┘

加载节点通常包含：

• strength_model：影响扩散模型；
• strength_clip：影响文本编码器；
• 不同架构可能只有部分组件可应用。

13.2 权重调试#

推荐固定：

• seed；
• 基础模型；
• 提示词；
• 采样参数。

然后只测试 LoRA 权重，例如：

0.4 / 0.6 / 0.8 / 1.0

若权重过高，常见表现：

• 颜色和纹理过拟合；
• 人脸趋同；
• 构图僵化；
• 触发词污染其他概念；
• 细节产生重复图案。

13.3 多 LoRA 叠加#

多 LoRA 会在模型层相互作用，不是简单相加。管理建议：

• 每次只新增一个，观察变化；
• 风格 LoRA 与人物 LoRA 分开调；
• 记录顺序、权重与基础模型；
• 避免多个强风格 LoRA 同时满权重；
• 检查是否属于同一架构和兼容底模。

13.4 LoRA 不生效的排查#

• 文件放错目录或未刷新；
• LoRA 与底模架构不兼容；
• 忘记把 LoRA 输出接到采样器/文本编码节点；
• 缺少触发词；
• 权重太低；
• 工作流中后面又加载了另一个模型，覆盖了 LoRA 结果。

14. ControlNet 与结构控制#

ControlNet 通过边缘、深度、姿态、线稿、分割等控制图约束生成结构。

14.1 通用流程#

控制图 → 预处理器 → ControlNet 条件图
ControlNet 模型 ────────────────┐
正向/负向 Conditioning ────────┤→ Apply ControlNet → KSampler

有些工作流使用预先生成的控制图，可跳过预处理器。

14.2 常见控制类型#

14.3 Strength 与作用区间#

常见参数：

• 强度：结构约束权重；
• 起始百分比：从采样早期还是中期开始；
• 结束百分比：何时停止施加控制。

思路：

• 早期控制更影响大结构；
• 后期控制更影响细节与边缘；
• 全程高强度可能限制创意；
• 多个 ControlNet 同时使用时需要分配职责。

14.4 多 ControlNet#

例：

• Pose 控制人物动作；
• Depth 控制空间关系；
• SoftEdge 保服装轮廓。

不要让多个控制器重复抢同一件事。先单独验证每个控制器，再叠加。

14.5 不生效或报 shape mismatch#

• ControlNet 与底模架构不匹配；
• 控制图尺寸或批次不匹配；
• 使用了错误预处理器；
• 作用区间设置为无效范围；
• 控制结果没有接入最终 conditioning；
• 模型或节点版本需要更新。

15. IPAdapter、参考图与身份一致性#

IPAdapter 类方案使用视觉编码器从参考图提取特征，再注入扩散模型。它通常依赖第三方节点和匹配的视觉编码器/适配器权重。

15.1 与 ControlNet 的区别#

• ControlNet 更偏结构控制；
• IPAdapter 更偏视觉语义、风格、构图或身份参考；
• 二者可组合，但显存和条件冲突都会增加。

15.2 通用组件#

参考图 → CLIP Vision Encode ─┐
IPAdapter 权重 ───────────────┤→ Apply IPAdapter → MODEL → KSampler
基础模型 ─────────────────────┘

具体节点名称取决于插件实现。

15.3 参考图准备#

• 主体清晰、遮挡少；
• 身份参考尽量减少夸张滤镜；
• 风格参考可选择代表性构图与材质；
• 多参考图要明确各自职责；
• 裁剪方式会影响编码器关注区域。

15.4 身份一致性不是绝对复制#

影响因素：

• 适配器类型；
• 视觉编码器；
• 权重；
• 作用区间；
• 参考图质量；
• 底模；
• 提示词冲突；
• 人脸在画面中的像素大小。

对于高一致性需求，通常还要结合人脸检测、局部重绘、专用身份条件或后期合成。

15.5 第三方节点安全提示#

IPAdapter、FaceID、InstantID 等生态实现变化很快。安装前检查：

• 仓库是否仍维护；
• 是否支持你的 ComfyUI 和模型架构；
• 需要哪些权重；
• 节点 README 的版本要求；
• 是否执行下载脚本或安装复杂二进制依赖。

16. 高清修复、放大与细节增强#

16.1 三种放大思路#

A. 像素放大#

IMAGE → Upscale Model → IMAGE

优点：快、稳定。缺点：不能真正创造与语义一致的新细节。

B. 潜空间放大后二次采样#

LATENT → Latent Upscale → KSampler(低 denoise) → Decode

优点：能补充语义细节。缺点：可能改变构图和人物。

C. 分块放大 / Tile#

将大图切块处理，再融合。优点是降低峰值显存；缺点是可能产生块间不一致和接缝。

16.2 典型两阶段工作流#

1. 第一阶段按模型擅长尺寸生成构图；
2. 放大 1.5–2 倍；
3. 第二阶段使用较低 denoise 精修；
4. 必要时用 Tile ControlNet 或分块采样维持结构；
5. 对人脸、手部、文字等区域局部修复；
6. 最后锐化、降噪和色彩调整。

16.3 放大常见伪影#

• 皮肤产生塑料纹理；
• 背景凭空增加重复物体；
• 眼睛、珠宝等细节过锐；
• 瓷砖纹理重复；
• 分块边缘色差；
• 文字被“重新想象”。

解决：降低 denoise、减少过强锐化、增加 tile overlap、控制种子和条件、对关键区域单独处理。

16.4 FaceDetailer 类节点#

自动检测人脸并局部重绘非常实用，但通常属于第三方节点。要注意：

• 检测模型也占内存；
• 小脸修复可能改变身份；
• 遮罩膨胀和羽化决定自然程度；
• 使用的人脸提示词应与全局人物一致；
• 多人图需要检查每个检测框。

17. 批量生产与工作流工程化#

17.1 Batch、列表与队列的区别#

• Batch size：一次张量中并行生成多张，速度可能更高，但显存占用明显增加。
• 列表映射：节点按列表元素执行，适合多提示词、多图、多参数组合。
• 队列多次提交：任务逐个执行，更稳、更容易恢复，但调度开销稍高。

显存有限时，优先把大 batch 改成多次队列。

17.2 批量变量#

常见变量：

• prompt；
• negative prompt；
• seed；
• checkpoint；
• LoRA 及权重；
• width/height；
• sampler/scheduler；
• ControlNet 强度；
• 输出文件名前缀。

17.3 避免“组合爆炸”#

若有 5 个提示词 × 4 个 LoRA 权重 × 4 个 seeds × 3 个采样器，已经是 240 个任务。生产前先做小规模筛选：

1. 固定采样器筛提示词；
2. 固定提示词筛 LoRA；
3. 固定组合筛 seed；
4. 只对候选做高分辨率生成。

17.4 输出命名#

推荐包含可追踪信息：

项目_场景_模型_日期_批次

示例：

shoe_campaign_studio_sdxl_20260810_b03

不要把完整提示词直接塞入文件名，容易超过路径限制并泄露业务信息。详细参数应保存在元数据、JSON 或旁车文件中。

17.5 生产工作流的“控制面板”#

把经常改的参数集中在左侧或顶部：

• 项目名；
• 主提示词；
• seed 模式；
• 尺寸；
• 主模型；
• 风格 LoRA；
• 结构控制强度；
• 是否启用二次精修；
• 输出路径/前缀。

内部节点应尽量隐藏实现细节，降低误操作。

17.6 可观测性#

生产工作流应记录：

• 工作流版本；
• ComfyUI 版本/提交；
• 自定义节点版本；
• 模型哈希；
• 关键参数；
• 输入素材标识；
• 失败原因；
• 运行耗时；
• GPU 信息。

17.7 可重复执行#

要做到可重复：

• 固定模型文件与哈希；
• 固定工作流 JSON；
• 固定自定义节点版本；
• 固定随机种子；
• 固定输入图片；
• 记录后端和精度设置；
• 避免依赖在线下载的“最新”资源。

18. 视频、音频与 3D 工作流概览#

ComfyUI 已扩展到视频、音频和 3D 等工作流，但不同模型的节点、显存和输入格式差异非常大。

18.1 视频工作流的典型阶段#

文本/首帧/尾帧/参考视频
        ↓
模型与编码器加载
        ↓
时空潜空间初始化与条件注入
        ↓
视频采样
        ↓
视频 VAE 解码
        ↓
帧序列后处理
        ↓
编码为 MP4/WebM/GIF

18.2 视频关键参数#

• 宽高；
• 帧数；
• FPS；
• 时长；
• 运动强度；
• 首尾帧条件；
• 上下文窗口；
• 分块解码；
• 插帧；
• 视频编码器与码率。

显存开销往往随分辨率、帧数和模型规模迅速增长。排错时先用低分辨率和短帧数。

18.3 一致性问题#

• 主体身份漂移；
• 纹理闪烁；
• 背景跳变；
• 镜头运动不连续；
• 手脚跨帧变形。

改善方法包括：首帧参考、结构控制、低运动强度、合理 prompt、专用一致性模型、分段生成与后期插帧/稳定。

18.4 音频工作流#

音频生成或音视频同步通常涉及：

• 文本/音频编码；
• 波形或声谱潜空间；
• 扩散/自回归生成；
• 解码；
• 音频格式保存；
• 采样率和声道管理。

务必关注声音模型许可证、音色身份权和生成内容合规。

18.5 3D 工作流#

可能包括多视图生成、深度/法线估计、点云、Gaussian Splatting、网格重建和纹理生成。输出格式和后处理工具链通常比静态图复杂。

18.6 使用官方模板#

对于新模型，优先从 ComfyUI 官方模板或官方教程开始。不要试图用旧的 SD 工作流猜测新模型组件连接方式。

19. 自定义节点与 ComfyUI Manager#

19.1 什么是自定义节点#

自定义节点是放在 custom_nodes 目录、由 Python 后端和可选前端扩展组成的插件。它可以：

• 增加新模型加载器；
• 增加预处理器；
• 增加图像/视频算法；
• 增加数据、字符串和数学工具；
• 改变前端交互；
• 下载或管理模型；
• 调用外部程序和网络服务。

这也意味着它本质上是可执行代码，必须谨慎信任。

19.2 Manager#

较新的 ComfyUI 发行中，Manager 可能已经集成或可在设置中启用。其用途通常包括：

• 搜索与安装自定义节点；
• 更新节点；
• 检测工作流缺失节点；
• 管理版本；
• 安装部分模型；
• 处理依赖。

具体入口与安全级别设置请以当前官方 Manager 文档为准。

19.3 安装第三方节点的安全清单#

安装前检查：

• 仓库所有者与维护状态；
• 最近提交和 issue；
• 是否需要运行额外脚本；
• requirements.txt 中的依赖；
• 是否下载可执行文件；
• 是否开放网络服务；
• 是否读取环境变量、浏览器或文件系统；
• 许可证；
• 与当前 ComfyUI 的兼容范围。

19.4 手动安装节点#

通用形式：

cd ComfyUI/custom_nodes
git clone <节点仓库地址>
cd <节点目录>
/path/to/comfyui/python -m pip install -r requirements.txt

关键是最后一行必须使用运行 ComfyUI 的同一个 Python。

19.5 缺失节点处理#

打开别人工作流出现红色未知节点时：

1. 记录节点 class/type 名；
2. 使用 Manager 的缺失节点功能；
3. 查看工作流作者列出的依赖；
4. 不要只按节点显示标题搜索，因为标题可以被重命名；
5. 安装后重启并观察启动日志；
6. 若仓库已停止维护，寻找兼容替代方案或手动重建流程。

19.6 更新策略#

不要在生产任务前同时更新：

• ComfyUI 核心；
• 所有自定义节点；
• PyTorch；
• 显卡驱动；
• 模型权重。

推荐分层更新，每次只改一类，并运行回归工作流。

19.7 节点冲突#

常见冲突：

• 两个节点包注册相同名称；
• 依赖要求不同版本的 NumPy、OpenCV、Transformers；
• 前端扩展使用过时 API；
• 节点假设了旧版 ComfyUI 内部结构。

排查方法：暂时移动/禁用一半节点，用二分法定位。

20. 性能、显存与速度优化#

20.1 先判断瓶颈类型#

20.2 降低显存占用的优先顺序#

1. Batch 降到 1；
2. 降低分辨率；
3. 减少视频帧数；
4. 关闭不必要的 ControlNet/IPAdapter/第二模型；
5. 使用分块 VAE 编解码；
6. 使用低显存启动模式；
7. 使用合适精度/量化模型；
8. 将部分组件卸载到 CPU；
9. 分阶段运行，而不是把所有模型同时留在工作流中。

20.3 为什么分辨率影响巨大#

像素数量是 宽 × 高。宽高各放大 2 倍，像素数变为 4 倍；中间注意力和特征图开销还可能更复杂。因此从 1024×1024 直接跳到 2048×2048，不是“只大一倍”。

20.4 精度与量化#

• FP32：精度高、内存大，推理通常没必要全程使用；
• FP16/BF16：常见推理精度；
• FP8/更低位量化：显著节省内存，但需要硬件、节点和模型支持；
• 量化可能降低质量、速度不一定更快、某些算子会回退。

不要只看文件大小判断运行显存。

20.5 Attention 优化#

不同后端可能支持不同注意力实现。判断原则：

• 使用 ComfyUI 当前默认通常最稳；
• 第三方优化库需要与 PyTorch/CUDA/平台匹配；
• 安装失败不要盲目编译；
• 速度比较必须用同一工作流、多次运行、排除首次编译与模型加载时间。

20.6 缓存的利弊#

缓存可避免重复加载和重复计算，但会占用内存。若工作流频繁切换多个大模型，可能出现：

• 模型不断装载/卸载；
• 系统内存交换；
• GPU 显存碎片；
• 表面上“第二次更慢”。

生产时尽量按模型分组任务，减少来回切换。

20.7 VAE OOM#

如果采样完成、在解码阶段 OOM：

• 使用 tiled VAE decode；
• 分批解码；
• 降低最终分辨率；
• 减少同时保留的图像批次；
• 检查是否意外把多批图拼成超大张量。

20.8 性能基准方法#

记录：

• 冷启动总时长；
• 热启动总时长；
• 采样 steps/s 或 s/it；
• 峰值显存；
• 峰值 RAM；
• 图片尺寸和 batch；
• 模型/精度；
• PyTorch、驱动与 ComfyUI 版本。

只比较“感觉快了”没有工程价值。

21. 工作流 JSON、模板与版本管理#

21.1 UI 工作流与 API 工作流#

ComfyUI 常见两类 JSON：

• UI 工作流格式：包含节点位置、尺寸、颜色、分组、连线等画布信息；
• API 格式：以节点 ID 为键，重点描述 class type、输入和依赖，便于后端执行。

不要把二者混淆。浏览器中保存的普通工作流通常不是直接提交 /prompt 的最终格式。

21.2 图片元数据#

ComfyUI 生成的 PNG 等文件通常可携带工作流信息。拖回界面可以恢复流程，但以下情况可能丢失：

• 社交平台压缩或重编码；
• 截图；
• 图片编辑器清除元数据；
• 转换格式；
• 隐私清理工具。

所以生产项目必须同时保存独立 JSON。

21.3 Git 管理工作流#

建议目录：

project/
├─ workflows/
│  ├─ source-ui/
│  └─ api/
├─ prompts/
├─ inputs/
├─ examples/
├─ manifests/
└─ README.md

Git 提交信息示例：

feat(workflow): add SDXL tile upscale stage
fix(workflow): correct ControlNet start/end range
chore(models): update manifest hashes

21.4 JSON diff 的噪声#

UI 工作流包含节点坐标和界面状态，移动节点也会产生大量 diff。改善方式：

• 重要版本打 tag；
• 同时保存 API 格式；
• 使用 JSON 格式化；
• 在发布前固定布局；
• 用 README 记录语义变化。

21.5 版本清单#

为每个生产工作流附带：

workflow: product-shot-v3
comfyui_commit: <git commit>
custom_nodes:
  package_a: <commit/tag>
  package_b: <commit/tag>
models:
  base: <filename + sha256>
  lora: <filename + sha256>
notes: "Requires 16 GB VRAM at 1536 px"

22. 本地 API 与自动化调用#

ComfyUI 服务端提供 HTTP 路由与 WebSocket 通信。官方文档列出的常见路由包括：

路由可能随版本扩展；部署时应以当前服务端源码/官方文档为准。

22.1 API 工作流结构#

简化示例：

{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": 123456,
      "steps": 24,
      "cfg": 6.5,
      "sampler_name": "euler",
      "scheduler": "normal",
      "denoise": 1.0,
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0]
    }
  }
}

["4", 0] 表示取节点 4 的第 0 个输出。

22.2 Python 提交示例#

下面代码演示读取 API JSON、修改提示词和 seed，然后提交。请先在 UI 中导出 API 格式工作流。

import json
import uuid
import urllib.request

SERVER = "127.0.0.1:8188"
CLIENT_ID = str(uuid.uuid4())

with open("workflow_api.json", "r", encoding="utf-8") as f:
    prompt = json.load(f)

# 根据你自己的工作流节点 ID 修改
prompt["6"]["inputs"]["text"] = "a cinematic product photo of a red sneaker"
prompt["3"]["inputs"]["seed"] = 20260810

payload = json.dumps({
    "prompt": prompt,
    "client_id": CLIENT_ID
}).encode("utf-8")

request = urllib.request.Request(
    f"http://{SERVER}/prompt",
    data=payload,
    headers={"Content-Type": "application/json"}
)

with urllib.request.urlopen(request) as response:
    result = json.loads(response.read())

print(result)

22.3 获取历史#

import json
import urllib.request

prompt_id = "提交后返回的 prompt_id"
url = f"http://127.0.0.1:8188/history/{prompt_id}"

with urllib.request.urlopen(url) as response:
    history = json.loads(response.read())

print(json.dumps(history, ensure_ascii=False, indent=2))

22.4 下载输出文件#

历史数据会包含输出节点生成的文件信息，通常有：

• filename；
• subfolder；
• type。

然后调用 /view：

from urllib.parse import urlencode
import urllib.request

params = urlencode({
    "filename": "ComfyUI_00001_.png",
    "subfolder": "",
    "type": "output"
})

urllib.request.urlretrieve(
    f"http://127.0.0.1:8188/view?{params}",
    "downloaded.png"
)

22.5 WebSocket 状态思路#

典型客户端流程：

1. 生成 client_id；
2. 连接 ws://HOST/ws?clientId=...；
3. 提交 /prompt；
4. 监听执行开始、节点执行、进度、缓存和完成消息；
5. 收到完成后查询 /history/{prompt_id}；
6. 下载输出。

消息结构可能演进，客户端应容忍未知事件类型，并以 prompt_id 隔离不同任务。

22.6 不要硬编码易变节点 ID#

更稳健的方式：

• 为节点设置可识别标题；
• 在旁车配置中记录语义名到节点 ID 的映射；
• 导出后做 schema 检查；
• 更新工作流时运行 API 回归测试。

22.7 API 错误处理#

要区分：

• HTTP 请求失败；
• 工作流校验失败；
• 任务入队后节点运行失败；
• 任务被中断；
• 输出为空；
• WebSocket 断线但任务仍完成。

生产客户端应实现超时、重试、幂等标识、状态查询和日志归档。

23. 自定义节点开发入门#

ComfyUI 自定义节点 API 正在演进。官方文档说明新的 V3 schema 仍属实验方向之一，发布节点前应确认当前稳定建议。

23.1 最小节点概念#

经典 Python 节点通常需要定义：

• 输入类型；
• 返回类型；
• 执行函数；
• 分类；
• 节点映射。

示意代码：

class AddNumbers:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "a": ("FLOAT", {"default": 0.0}),
                "b": ("FLOAT", {"default": 0.0})
            }
        }

    RETURN_TYPES = ("FLOAT",)
    RETURN_NAMES = ("sum",)
    FUNCTION = "add"
    CATEGORY = "examples/math"

    def add(self, a, b):
        return (a + b,)

NODE_CLASS_MAPPINGS = {
    "ExampleAddNumbers": AddNumbers
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "ExampleAddNumbers": "Add Numbers"
}

注意：这是经典结构示意。若官方当前推荐 V3 Node Definition，请优先按最新文档实现。

23.2 返回值必须是 tuple#

即使只有一个输出，也通常要写：

return (result,)

少了逗号可能返回普通对象而不是单元素 tuple。

23.3 IMAGE 与 MASK 张量#

开发时必须确认：

• batch 维；
• height/width 顺序；
• channel 数；
• 数值范围；
• device；
• dtype；
• contiguous 状态。

不要假设 OpenCV/PIL/NumPy/PyTorch 的通道顺序相同。常见错误来自 RGB/BGR、HWC/CHW、0–1/0–255 之间转换。

23.4 节点纯度与缓存#

如果输出只依赖输入，节点更容易被缓存。若节点依赖：

• 当前时间；
• 外部文件变化；
• 网络响应；
• 隐式全局状态；
• 随机数；

就要正确声明变化检测或把这些因素显式作为输入，否则 ComfyUI 可能错误复用缓存。

23.5 避免导入时副作用#

不要在模块 import 时：

• 下载大文件；
• 启动服务器；
• 申请大量显存；
• 修改用户配置；
• 扫描全盘；
• 发起未经说明的网络请求。

节点包导入失败会影响整个启动过程。

23.6 依赖管理#

• 精简 requirements.txt；
• 避免无上限地强制升级核心依赖；
• 对二进制库说明平台支持；
• 不要把用户的 PyTorch 随意替换成另一后端版本；
• 为可选功能使用延迟导入和友好错误。

23.7 前端扩展#

需要自定义画布行为、菜单、预览或 widget 时，可编写 JavaScript 前端扩展。前端 API 变化比纯 Python 节点更敏感，应：

• 使用官方扩展 API；
• 避免直接操作内部 DOM；
• 检测能力而非硬编码版本；
• 在新版前端做回归测试。

23.8 发布与 Registry#

官方自定义节点文档提供基于 Registry 的发布流程。发布前应准备：

• 明确许可证；
• README 与截图；
• 安装说明；
• 模型依赖说明；
• 节点输入输出说明；
• 安全与隐私说明；
• 版本号与变更日志；
• 可复现示例工作流。

24. 服务器部署与安全#

24.1 监听地址#

默认本地监听最安全。若监听 0.0.0.0，局域网甚至公网可能访问你的服务，具体取决于防火墙和路由。

不要把裸 ComfyUI 端口直接映射到公网。

24.2 为什么风险高#

服务可能允许：

• 提交任意复杂工作流耗尽 GPU；
• 上传文件；
• 读取可访问的输出；
• 触发第三方节点网络/文件操作；
• 利用有漏洞的节点；
• 泄露提示词、图片和模型信息。

24.3 推荐架构#

Internet
   ↓
HTTPS Reverse Proxy / API Gateway
   ↓ 认证、限流、请求校验
业务服务 / 队列
   ↓ 只提交白名单工作流和参数
ComfyUI Worker（隔离网络）
   ↓
受控模型与输出存储

24.4 安全措施#

• TLS；
• 身份认证；
• IP 限制/VPN；
• 请求体大小限制；
• 并发和队列限制；
• 工作流白名单；
• 参数 schema 校验；
• 上传文件类型和尺寸验证；
• 不以高权限用户运行；
• 容器/系统级隔离；
• 输出生命周期管理；
• 禁止不必要的第三方节点联网；
• 日志审计；
• 定期漏洞与依赖检查。

24.5 多用户#

ComfyUI 的本地设计不等同于完整的企业多租户平台。多用户服务应由外层业务系统负责：

• 用户认证；
• 配额；
• 任务隔离；
• 输出权限；
• 成本计量；
• 内容审核；
• 数据保留策略。

24.6 容器数据卷#

建议分离：

• 程序镜像；
• 模型只读卷；
• 输入卷；
• 输出卷；
• 自定义节点卷；
• 缓存；
• 用户配置。

模型卷设为只读可以减少误删和供应链风险。

25. 常见错误与系统化排错#

25.1 排错总流程#

复现错误
  ↓
保存完整终端日志与工作流
  ↓
判断：启动失败 / 加载失败 / 校验失败 / 执行失败 / 输出异常
  ↓
最小化工作流
  ↓
禁用第三方节点验证核心
  ↓
确认模型架构、路径、版本和硬件后端
  ↓
一次只改变一个变量
  ↓
记录结论与修复

25.2 ModuleNotFoundError#

原因：

• 依赖未安装；
• 安装到了错误 Python；
• 节点 README 漏写依赖；
• 依赖包名与 import 名不同。

检查：

python -c "import sys; print(sys.executable)"
python -m pip show <package>

务必确认这个 python 与 ComfyUI 启动日志中的解释器一致。

25.3 节点启动时 ImportError / 二进制错误#

可能是：

• NumPy ABI 不兼容；
• OpenCV、Torch、xformers 等二进制包版本冲突；
• Python 版本不支持该 wheel；
• Apple arm64 与 x86 混装；
• Windows 缺少运行库。

不要立刻“升级所有包”。先确定哪个节点引入冲突。

25.4 CUDA out of memory#

立即操作：

1. batch=1；
2. 降低宽高；
3. 减少 ControlNet/IPAdapter；
4. 使用 tiled VAE；
5. 关闭其他占 GPU 程序；
6. 重启 ComfyUI 清理碎片；
7. 使用低显存模式；
8. 检查是否误加载多个大模型。

日志中“已分配”和“已保留”有助于判断碎片与真实需求。

25.5 mat1 and mat2 shapes cannot be multiplied / shape mismatch#

常见于组件架构不匹配：

• SD1.5 LoRA 用在 SDXL；
• SDXL ControlNet 用在其他架构；
• 文本编码器不匹配；
• VAE/latent 通道不匹配；
• 节点版本不支持新模型；
• 图像或 mask 批次/尺寸不一致。

25.6 模型下拉框找不到文件#

检查：

• 是否放在正确类别目录；
• 扩展名是否支持；
• 是否需要刷新模型列表；
• 是否重启；
• 额外路径 YAML 是否缩进正确；
• 服务进程是否有权限；
• 文件是否仍在下载、被隔离或是快捷方式失效。

25.7 工作流打开后全部节点红色#

• 缺少节点包；
• 节点 class 名已变；
• 工作流来自更高版本前端；
• 自定义节点导入失败；
• 浏览器缓存了旧前端资源。

先看终端中的“failed to import custom node”信息。

25.8 Prompt outputs failed validation#

说明工作流在入队前校验失败。常见原因：

• 必填输入未连接；
• 下拉框值不存在；
• 参数越界；
• 模型文件不存在；
• 输出节点没有有效依赖；
• API JSON 节点格式错误。

网页错误通常会指出节点 ID。定位该节点，不要盲目重装。

25.9 生成纯黑图#

• VAE 不匹配；
• 精度溢出；
• 模型组件不完整；
• latent 格式不匹配；
• 后处理节点范围错误；
• 输入图 Alpha/色彩处理异常。

先绕过所有后处理，用核心 VAE Decode → Preview Image 验证。

25.10 生成噪声或彩色马赛克#

• KSampler 未真正去噪；
• denoise/steps 配置异常；
• 模型与采样节点不匹配；
• VAE 错误；
• 误把 latent 当 image 保存；
• 自定义采样器设置错误。

25.11 图片与预期完全不符#

依次确认：

1. 实际加载的模型；
2. 正负提示词是否接反；
3. LoRA 输出是否进入最终模型；
4. ControlNet 是否错误过强；
5. seed 是否自动变化；
6. 目标模型的提示词规范；
7. 是否有后续节点覆盖结果。

25.12 ComfyUI 卡在启动#

观察最后一条日志：

• 扫描巨大网络盘；
• 某节点 import 卡住；
• 节点在启动时下载文件；
• 端口被占用；
• 前端资源安装/更新；
• Python 依赖正在编译。

临时将最近安装的节点移出 custom_nodes 再试。

25.13 页面打不开#

• 后端是否仍在运行；
• 地址和端口是否正确；
• 端口是否被占用；
• 防火墙；
• 监听地址；
• 反向代理 WebSocket 配置；
• 浏览器扩展或缓存问题。

本机先访问 127.0.0.1，不要先排查公网链路。

25.14 队列执行但没有输出文件#

• 使用的是 Preview 而不是 Save；
• Save 节点没有连到执行分支；
• 输出目录无写权限；
• 文件被写入子目录；
• 自定义保存节点路径逻辑不同；
• 任务后半段报错但前端状态未注意。

25.15 更新后坏了#

正确回退需要知道更新前版本：

• 核心 Git commit；
• 节点 commit/tag；
• Python 依赖快照；
• 模型文件是否改变。

如果没有记录，先查看 Git reflog/Manager 快照/备份，不要继续随机升级。

25.16 最小复现模板#

报告问题时提供：

操作系统：
GPU / 显存：
驱动：
Python：
PyTorch：
ComfyUI commit/version：
启动命令：
自定义节点：
模型架构：
最小工作流 JSON：
完整错误日志：
复现步骤：
预期结果：
实际结果：

不要只发一张红框截图。

26. 最佳实践与检查清单#

26.1 新手七日学习路线#

第 1 天：核心链路#

• 加载 checkpoint；
• 正负提示词；
• latent；
• KSampler；
• VAE 解码；
• 保存图片。

第 2 天：参数实验#

固定 seed，对比 steps、CFG、sampler、scheduler、分辨率。

第 3 天：图生图与局部重绘#

理解 denoise、VAE Encode、mask、羽化。

第 4 天：LoRA 与模型管理#

学习架构兼容、权重调试、目录管理。

第 5 天：ControlNet#

从单一 Canny 或 Depth 开始，再尝试多控制。

第 6 天：高清修复#

像素放大、潜空间放大、低 denoise 二次采样。

第 7 天：工作流整理与 API#

分组、注释、模板、导出 JSON、提交 /prompt。

26.2 下载工作流前检查#

• 来源可信；
• 截图与说明完整；
• 已列出模型；
• 已列出自定义节点；
• 模型架构明确；
• 许可证可接受；
• 显存需求可承受；
• 不包含可疑脚本或远程调用。

26.3 运行工作流前检查#

• 模型路径正确；
• 加载器选择了正确文件；
• 输出尺寸合理；
• batch=1 做首次验证；
• seed 固定；
• Save 节点路径安全；
• 第三方节点成功加载；
• 没有把服务裸露公网。

26.4 发布工作流前检查#

• 节点分组清晰；
• 关键参数集中；
• 有使用说明；
• 有模型清单与来源；
• 有自定义节点清单；
• 有显存建议；
• 有输入输出示例；
• 已移除本机绝对路径；
• 已清理隐私提示词与图片；
• 保存 UI JSON 与 API JSON；
• 用干净环境验证。

26.5 更新前检查#

• 当前有可用备份；
• 记录核心 commit；
• 导出 pip freeze；
• 记录节点版本；
• 保存回归工作流；
• 当前没有紧急生产任务；
• 一次只更新一个层级。

26.6 工作流美化规范#

• 从左到右布局；
• 同类节点同色；
• 每个区域有标题；
• 关键参数用醒目颜色；
• 复杂长线使用 Reroute；
• 不用的测试分支删除或明确标记；
• 对第三方节点写明来源；
• 在 Notes 中写模型版本与最低显存。

26.7 团队治理建议#

• 建立批准的模型白名单；
• 建立批准的节点白名单；
• 建立黄金回归工作流；
• 用模型哈希而非文件名做身份确认；
• 开发/测试/生产环境分离；
• 所有升级先在测试环境验证；
• 对输出和输入设数据保留期限；
• 记录模型许可证和商用限制。

27. 术语表#

28. 官方资料与延伸阅读#

以下资料是本文优先参考的官方来源：

1. ComfyUI 官方文档
   https://docs.comfy.org/↗
2. ComfyUI 官方 GitHub 仓库
   https://github.com/Comfy-Org/ComfyUI↗
3. 安装与系统要求
   https://docs.comfy.org/installation/system_requirements↗
4. ComfyUI Server 路由说明
   https://docs.comfy.org/development/comfyui-server/comms_routes↗
5. 工作流 JSON 规范
   https://docs.comfy.org/specs/workflow_json↗
6. 自定义节点文档
   https://docs.comfy.org/custom-nodes/overview↗
7. ComfyUI 示例工作流
   https://comfyanonymous.github.io/ComfyUI_examples/↗
8. PyTorch 官方安装选择器
   https://pytorch.org/get-started/locally/↗

28.1 阅读资料的优先级#

遇到冲突时建议按以下顺序判断：

1. 当前 ComfyUI 官方文档；
2. 当前 ComfyUI 仓库 README、源码和 --help；
3. 模型作者的官方模型卡和示例工作流；
4. 自定义节点仓库 README 与 release；
5. 社区教程。

社区教程可能非常有用，但最容易因版本变化而过时。

结语：掌握 ComfyUI 的关键不是记住几百个节点，而是理解“模型对象、条件、潜空间、图像、遮罩”五类数据如何流动；知道每个阶段在解决什么问题；能够用最小工作流验证假设；最后再把经过验证的模块组合成可复现、可维护、可自动化的生产流程。