Troubleshooter

ComfyUI 工作流调试

四类错误诊断流程

1. 连接错误

症状： 无法访问 ComfyUI 界面、API 调用失败、浏览器显示"连接被拒绝"

诊断步骤：

1. 检查 ComfyUI 是否启动

   • 查看终端/命令行窗口是否有 ComfyUI 运行日志
   • 检查进程：tasklist | findstr python（Windows）
   • 如果未启动 → 启动 ComfyUI

2. 检查端口是否正确

   • 默认端口：8188
   • 访问地址：http://127.0.0.1:8188
   • 如果端口被占用，ComfyUI 会自动使用下一个可用端口，检查启动日志中的实际端口
   • 修复：使用 --port 指定端口 参数启动

3. 检查防火墙/安全软件

   • Windows 防火墙可能阻止 Python 网络访问
   • 杀毒软件可能拦截本地服务
   • 修复：添加 Python 到防火墙白名单

4. 检查监听地址

   • 默认监听 127.0.0.1（仅本机）
   • 如需局域网访问：使用 --listen 0.0.0.0 参数
   • 如果从其他设备访问：确认 IP 地址正确

修复命令示例：

# 指定端口启动
python main.py --port 8188

# 允许局域网访问
python main.py --listen 0.0.0.0

# 秋叶整合包
启动器中修改端口设置

2. 节点错误

症状： 节点显示红色、"Node not found"、输入/输出类型不匹配、节点缺失

诊断步骤：

1. 节点缺失（Node not found）

   • 原因：自定义节点未安装或安装失败
   • 检查：打开 ComfyUI Manager → 查看是否有缺失节点提示
   • 修复：通过 ComfyUI Manager 安装缺失节点，或手动 git clone 到 custom_nodes/ 目录

2. 节点版本不兼容

   • 原因：工作流使用的节点版本与安装版本不一致
   • 检查：查看节点报错信息中的函数名/参数名
   • 修复：更新节点到最新版本（ComfyUI Manager → Update All），或回退到工作流兼容版本

3. 输入类型不匹配

   • 原因：节点 A 输出类型与节点 B 输入类型不兼容
   • 常见案例：
     • IMAGE 连到 LATENT 输入（需要 VAE Encode 中间节点）
     • CONDITIONING 连到 STRING 输入
     • 不同尺寸的 tensor 连接
   • 修复：检查连线两端的类型，添加转换节点

4. 节点内部错误

   • 检查 ComfyUI 终端日志中的完整错误堆栈
   • 常见原因：依赖包缺失、Python 版本不兼容
   • 修复：在节点目录下运行 pip install -r requirements.txt

快速修复流程：

节点报错
├── 红色节点 "Node not found"
│   └── ComfyUI Manager → Install Missing Nodes
├── 连线报错
│   └── 检查输出/输入类型是否匹配 → 添加转换节点
├── 执行时报错
│   └── 查看终端日志 → 定位具体错误
└── 节点 UI 异常
    └── 刷新浏览器（Ctrl+Shift+R）或重启 ComfyUI

3. OOM 崩溃（显存不足）

症状： CUDA out of memory、进程被杀死、ComfyUI 无响应后崩溃

诊断步骤：

1. 确认是 OOM

   • 终端日志出现 RuntimeError: CUDA out of memory
   • 或系统提示 Python 进程异常终止

2. 检查当前显存占用

   • 命令：nvidia-smi
   • 查看 GPU 显存使用量
   • 是否有其他进程占用显存（关闭不需要的程序）

3. 分析显存需求

   • 模型大小：FLUX（12GB）、SDXL（6GB）、SD1.5（~4GB）
   • 分辨率影响：1024x1024 比 512x512 多约 4 倍显存
   • 批次大小：每增加 1 倍 batch，显存翻倍
   • 视频帧数：帧数越多，显存需求越大

4. 应用 VRAM 降级策略（见下方详细表格）

4. 输出质量差

症状： 生成图片模糊、颜色异常、构图错误、与 prompt 不符

诊断步骤：

1. 检查采样参数

   • 采样步数过低（< 15 步）→ 增加到 20-30 步
   • CFG/Guidance Scale 不当 → SDXL 用 5-8，FLUX 用 2.5-4.5
   • 采样器选择 → 推荐 euler_a（快速）或 dpmpp_2m_sde（质量）

2. 检查模型适配性

   • 使用的 checkpoint 与 LoRA 是否匹配（SD1.5 LoRA 不能用于 SDXL）
   • VAE 是否匹配（SDXL 需要 SDXL VAE）
   • CLIP 模型是否正确加载

3. 检查分辨率

   • SD1.5：512x512 或 512x768
   • SDXL：1024x1024 或 1024x768
   • FLUX：1024x1024
   • 使用非原生分辨率会导致质量下降或构图异常

4. 检查 prompt 质量

   • 参考 prompt-engineer skill 优化提示词
   • 确认正面/负面提示词设置正确
   • 关键词权重是否合理

VRAM 降级策略表

当显存不足时，按以下顺序逐步降级，每步都尝试运行，直到不再 OOM：

各模型显存估算

以上为模型本身显存占用，实际推理还需额外 2-6GB 用于中间计算。

--lowvram 与 --highvram 说明

ComfyUI 日志路径和关键字段解读

日志位置

• 终端输出： ComfyUI 主要日志直接输出到启动终端
• 秋叶整合包： 查看启动器窗口或日志文件
• 系统日志： Windows 事件查看器（严重崩溃时）

关键日志字段

错误堆栈阅读方法

当出现错误时，终端会打印 Python 堆栈跟踪（Traceback）：

1. 从最后一行开始看 — 最后一行是实际错误类型和信息
2. 向上找第一个自定义节点路径 — 定位是哪个节点出错
3. 关注 File "custom_nodes/xxx/..." 行 — 这是自定义节点代码位置
4. 搜索错误信息 — 在节点的 GitHub Issues 中搜索

常用调试命令

# 查看 GPU 状态
nvidia-smi

# 查看 CUDA 版本
nvcc --version

# 查看 Python 版本
python --version

# 查看 PyTorch 和 CUDA 版本
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.cuda)"

# 查看已安装的自定义节点
ls custom_nodes/

# 检查特定节点的依赖
pip list | grep 某个包名