一句话定义
排障的方法论是先读控制台日志、再二分定位(bypass 节点)、最后查表对症——本页把高频故障整理成"症状→原因→修法"速查表,并给出通用排查流程。
为什么重要
生成出问题 90% 发生在:环境(缺节点/模型错位)、显存、精度(VAE/黑图)、参数(炸图/灰图)。会排查的人把"卡住三小时"变成"两分钟修复"。
前置知识
节点与工作流的心智模型：端口、连线与执行(bypass 技能)、潜空间与 VAE:压缩的图像世界(VAE 机制)。
核心概念:通用排查流程
1. 看控制台(启动 ComfyUI 的终端/日志窗口):红色报错通常直接点名节点与原因
2. 二分定位:对可疑分支 bypass,缩小故障范围(数据流视角,见 kp-002)
3. 变量隔离:一次只改一个参数复现问题(结合 kp-006 的种子纪律)
4. 对照组:用官方/能跑通的模板替换自定义部分,判断"工作流问题"还是"环境问题"速查表
| 症状 | 高频原因 | 修法 |
|---|---|---|
| 纯黑图 | VAE 错配/未加载;fp16 解码 NaN | 核对 VAE 与模型同源;VAE 换 fp32 或用 Tiled 解码 |
| 灰图/雾图 | 蒸馏模型(Turbo/LCM)用了高 cfg;调度器不匹配 | cfg→1-2,换推荐 scheduler(采样器与调度器选型指南) |
| 过曝/高饱和 | cfg 过高;负面堆砌 | 降 cfg 或 RescaleCFG(CFG 与负面引导:引导强度的数学/模型采样补丁:ModelSampling/RescaleCFG/FreeU) |
| 重复肢体 | 分辨率偏离模型家族;步数过低 | 回到原生分辨率族;提高 steps(SDXL 与多编码器家族:换模型换什么) |
| 红节点 missing node | 缺 custom node | Queue 报错里通常给出包名,用 Manager 补装(ComfyUI Manager:生态的包管理器) |
| size mismatch 加载报错 | 文件不完整/放错目录/家族不匹配 | 重下完整文件;核对目录与家族(模型文件与目录组织) |
| 加载列表空 | 目录错位;未刷新 | 放对 models 子目录;R 刷新或重启 |
| 爆显存 OOM | 分辨率/帧数/模型过大 | 见 性能优化与显存管理 降级序列 |
| 速度极慢 | lowvram 换层;sampler 重;后端未优化 | 缩图/换轻 sampler/装 sageattention(条件允许) |
| NaN / 生成中断 | 特定 sampler+cfg 组合数值溢出 | 换 sampler(dpmpp_sde 系高 cfg 高危)或降 cfg |
| 拖图不还原工作流 | 图来自其他工具/元数据被剥离 | 用原工具读元数据;要求分享者给 json |
| 中文路径报错 | 部分平台对非 ASCII 路径兼容差 | 安装与模型路径用英文 |
原理与机制
为什么"黑图"高发于 VAE:解码是对潜张量的连续数值映射,fp16 表示范围有限,溢出即 NaN → 整图无效(黑)。而 NaN 又与"调度路径"相关——某些 sampler 在高 cfg 下的数值轨迹更易溢出,这就是"黑图换个 sampler 就好了"的原理。
日志阅读要点:报错行通常包含 node id、node type、异常栈最后一行;Python traceback 从最后一行往上读,先看异常类型再定位。
直观类比
排障像修水管:日志是水表读数(告诉你哪段没水),bypass 是逐段关阀(定位漏点),查表是师傅的故障手册(常见漏点清单)——顺序永远是"读数→关阀→查手册",上来就换管子(重装)是最后选项。
实例与案例
- 社区工作流导入即报错:八成缺 custom node → 记下红节点名 → Manager Install Missing;再报错查模型文件(ComfyUI Manager:生态的包管理器)。
- "昨天还好好的":回顾三个变量——升级了什么(版本/节点)、动过什么文件、改了什么参数;版本回退是快速验证手段。
- 同一工作流时好时坏:查种子纪律(队列、种子与可复现性),randomize 是否关着;再看是否随机类 sampler。
常见误区
- 不看日志瞎猜:控制台红色行往往直接给出答案;浏览器界面报错信息也完整可复制。
- 一次改多个参数:问题"好了"也不知道哪个起效;单变量原则。
- 重装上瘾:90% 的故障与重装无关;先二分,再查表,重装是终局手段。
- 把"慢"当"坏":lowvram 下首图慢是机制(性能优化与显存管理),不是故障。
自测题
- 排查四步流程是什么?
- 黑图的两个第一嫌疑人与验证方法?
- 灰图+cfg 检查的组合判断逻辑?
- size mismatch 的三种根因?
参考答案
- 读日志→bypass 二分→单变量复现→对照组模板。
- VAE 错配/未加载、fp16 NaN;验证:换 fp32/Tiled 解码、核对 VAE 来源。
- 若模型是蒸馏家族(Turbo/LCM/某些 sdxl-turbo),灰图几乎必是 cfg 未降为 1-2;否则查 scheduler 与模型推荐值。
- 文件下载不完整、放错目录导致误读、模型与加载器家族不匹配。
与其他知识点的关系
- 性能优化与显存管理 处理"崩与慢"的显存域;本页是总索引。
- ComfyUI Manager:生态的包管理器 的 Manager 是"缺节点"类故障的自动修复器。
- 节点与工作流的心智模型：端口、连线与执行 的 bypass 是本页方法论的工具基础。
延伸阅读
- 官方 issue 区搜索报错关键字:github.com/comfyanonymous/ComfyUI/issues
- 社区排障贴:r/StableDiffusion、ComfyUI 官方 Discord
前置知识
节点与工作流的心智模型：端口、连线与执行潜空间与 VAE:压缩的图像世界