一、基础知识

ComfyUI 本质上是一个「节点图」工具。它不像一键出图的界面那样把所有选项塞进一个表单,而是把流程拆成一堆节点:加载模型、编码提示词、生成潜变量、采样、解码、保存图片。你用线把节点连起来,数据就顺着线流动。

理解节点只要抓住三件事:输入、参数、输出。输入是别的节点传来的数据,参数是你在节点里填的数字或文本,输出是它算完交出去的结果。连线是有类型的——MODEL、CLIP、VAE、LATENT、IMAGE 各有各的接口,类型对不上就连不起来。所以报错「类型不匹配」通常不是程序坏了,而是你把输出接错了口。

模型目录是另一个高频坑。ComfyUI 从安装目录下的 models/ 文件夹里读模型,并且按类型分子目录:主模型放 checkpoints,LoRA 放 loras,VAE 放 vae,控制模型放 controlnet,诸如此类。文件放错目录,界面里就看不到。不同安装方式和版本的具体目录会有差异,以你实际安装的目录结构为准。

显存方面要建立一个直觉:加载大模型会占一块固定显存,采样过程中还会有一块峰值开销。显存不够时有两种表现——一种是直接报 CUDA out of memory 中断,另一种是没报错但自动把数据挪到内存里,速度骤降。两者处理方式不完全一样。

二、实操步骤

第 1 步:确认环境与安装。

安装请以官方仓库的说明为准,下面只给通用的检查命令:

# 查看 Python 与显卡驱动状态
python --version
nvidia-smi

# 若你已克隆官方仓库,进入目录安装依赖(具体命令以官方说明为准)
cd ComfyUI
pip install -r requirements.txt

第 2 步:整理模型目录。

# 看看有哪些模型子目录
ls models/

# 把主模型、LoRA、VAE 分别放进对应目录
ls -lh models/checkpoints models/loras models/vae

第 3 步:用脚本核对模型文件,避免「以为放对了」。

# list_models.py —— 列出各目录里的模型文件与大小
from pathlib import Path

root = Path("models")
exts = {".safetensors", ".ckpt", ".pt", ".bin", ".gguf"}
for p in sorted(root.rglob("*")):
    if p.is_file() and p.suffix.lower() in exts:
        size = p.stat().st_size / (1024 ** 3)
        print(f"{size:6.2f} GB  {p}")
python list_models.py

第 4 步:搭一条最小工作流。

在界面里依次添加并连接这些节点:

  1. Load Checkpoint —— 加载主模型,同时输出 MODEL、CLIP、VAE 三路。
  2. CLIP Text Encode 两个 —— 一个写正向提示词,一个写负向提示词,都连到上面的 CLIP。
  3. Empty Latent Image —— 设置宽高和 batch size,新手先用较小分辨率、batch 设为 1。
  4. KSampler —— 接 MODEL、两路提示词编码和 LATENT,这里控制采样步数等参数。
  5. VAE Decode —— 把采样出来的 LATENT 转成 IMAGE,接上 VAE。
  6. Save Image —— 把 IMAGE 保存下来。

这条链路跑通,再往上加 LoRA、控制模型等节点。节点的具体名称在不同版本里可能有出入,以你界面里实际显示为准。

第 5 步:显存不够时按顺序降级。

# 实时监控显存占用,观察是哪一步涨上去的
nvidia-smi -l 1

# 低显存启动参数是否可用、名称如何,以你所装版本的官方说明为准
python main.py --lowvram

同时把分辨率调小、batch 保持 1、关掉其他占显卡的程序。先用最小配置验证流程能跑通,再逐步加回分辨率。

三、关键细节

  1. 模型放错目录是「列表里看不到模型」的第一原因。 先跑 list_models.py 确认文件在正确位置,再考虑刷新界面或重启服务。
  2. 改了模型文件要刷新或重启。 有些版本会缓存模型列表,光把文件复制进去还不够。
  3. 显存不足要分阶段判断。 一启动就爆,多半是主模型太大;加载成功、采样时才爆,多半是分辨率或 batch 太大。处理方式不同。
  4. VAE 别忘了接。 VAE Decode 没接 VAE,或者用了与主模型不匹配的 VAE,容易出全黑、全灰或颜色异常的图片。
  5. 把工作流导出成 JSON 文件保存。 只截屏不导出,换台机器或重装后基本没法复现。导出时连同用到的模型文件名一起记下来。
  6. 先低分辨率跑通,再谈质量。 用较小的分辨率和较少的步数验证链路,能出图之后再逐步提高,排查成本最低。

四、常见错误

错误做法 现象 原因 修正
模型文件随便丢进根目录 下拉列表里找不到模型 没放进 models/ 下对应的类型子目录 按类型移动文件,刷新或重启后重试
一上来就用大分辨率、大 batch CUDA out of memory 直接中断 采样峰值显存超过显卡容量 batch 设为 1,降低宽高,必要时用低显存启动参数
连线随便接,颜色对得上就以为对了 报节点类型不匹配 接口的数据类型不同(如把 IMAGE 接到 LATENT) 从正确的输出端点重新连线,核对接口类型
VAE Decode 没接 VAE 生成全黑、全灰或偏色图片 解码阶段缺少或不匹配 VAE 接上主模型自带的 VAE,或换用兼容的 VAE 文件
调完参数直接关页面 下次打开发现工作流没了 没导出工作流文件 导出 JSON 保存到本地,并记录使用的模型名
没报错但出图极慢 显存不足后数据被挪到内存 显存占用过高触发卸载 用 nvidia-smi -l 1 观察,降分辨率、关掉其他占显存程序

五、排查方法

照这个顺序做:

# 1. 看显卡显存到底被谁占了
nvidia-smi

# 2. 确认模型文件在不在、放对没有、有多大
python list_models.py
ls -lh models/checkpoints

# 3. 看终端或日志最后的报错栈,定位是哪个节点炸的
# 如果你把输出重定向到了文件:
tail -n 40 comfyui.log

# 4. 回到最小工作流验证:只保留加载模型、采样、解码、保存四个环节
# 能出图就说明问题在后来添加的节点上,逐个加回去定位

# 5. 持续观察显存变化,判断爆点是在加载阶段还是采样阶段
nvidia-smi -l 1

排查口诀:先看显存,再看目录,再看连线,最后才看参数。大多数「跑不起来」都能在这四步里找到原因。

六、注意事项

  • 模型目录名、启动参数、节点名称会随版本变化,具体操作以你所装版本的官方说明和界面为准。
  • 模型文件来源和许可证要自己核对,不要下载来路不明的文件。
  • 大模型文件体积很大,操作前确认磁盘空间充足。
  • 低显存模式、平铺解码等手段通常以速度为代价,能正常跑时不建议无脑开启。
  • 不要同时运行多个占满显存的程序;排查时先关掉浏览器硬件加速等无关占用。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。