mcpField
C
comfyui-troubleshooter

comfyui-troubleshooter

github.com/mckruz创意与媒体921.0k 次安装32 周前更新
代码仓库

关于 comfyui-troubleshooter

面向 ComfyUI 用户和 Agent 的故障排查技能，覆盖服务端、工作流、输出质量和性能问题。它依据错误模式和安装清单，提出检查项与处理办法。

主要功能

  1. 01分类处理四类问题
  2. 02按错误匹配已知修复方案
  3. 03检查模型与自定义节点
  4. 04建议质量和性能调整

适用场景

  1. 01诊断 ComfyUI 连接故障
  2. 02解决工作流节点或模型缺失
  3. 03处理输出瑕疵或生成缓慢

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mckruz/comfyui-expert --skill comfyui-troubleshooter

安装后在 Claude Code 中输入/comfyui-troubleshooter确认已加载。

详细介绍

ComfyUI 故障排查器

诊断并解决 ComfyUI 的问题，涵盖四个类别：服务端错误、工作流错误、质量问题和性能问题。

诊断流程

第 1 步：对错误分类
类别症状首要检查项
服务端连接被拒绝、超时、崩溃ComfyUI 是否正在运行？检查 /system_stats
工作流节点错误、缺少输入、类型不匹配根据清单验证工作流
质量伪影、身份不符、输出模糊检查设置（CFG、权重、分辨率）
性能OOM、生成缓慢、VRAM 错误检查 VRAM 使用量和模型大小
第 2 步：收集上下文

诊断前请收集：

  1. 错误消息（准确文本）
  2. 正在执行的工作流（或其描述）
  3. 涉及的模型（检查点、LoRA、ControlNet 等）
  4. 设置（CFG、步数、分辨率、采样器）
  5. 硬件（参见 foundation/hardware-profile.md）
  6. 清单（参见 state/inventory.json）
第 3 步：匹配错误模式

完整错误数据库见 references/troubleshooting.md。

快速修复参考

最常见的 10 种错误

1. "CUDA out of memory" → 使用 FP8：--fp8_e4m3fn-unet → 启用分块 VAE → 降低分辨率 → 重启 ComfyUI（清除内存碎片）

2. "Node type not found: {name}" → 通过 ComfyUI-Manager 安装自定义节点包 → 检查 comfyui-inventory 中的节点与软件包映射

3. "Expected scalar type BFloat16 but found Float" → 精度不匹配。添加 --force-fp16，或使用精度匹配的节点

4. 面部过曝／曝光过度 → 将 CFG 降至 4-5（InstantID） → 降低身份方法权重 → 向负面嵌入添加噪声（35%）

5. "No model found at path" → 检查文件名拼写（必须完全匹配） → 确认文件位于正确的子目录中 → 运行清单扫描以确认

6. 分辨率为 1024x1024 时出现水印伪影 → 改用 1016x1016 或 1020x1020

7. 身份与参考图不符 → 使用质量更高的参考图（清晰、正面朝向） → 将 IP-Adapter 权重提高至 0.8+ → 确认已安装 InsightFace antelopev2

8. 视频闪烁 → 将 FaceDetailer 降噪强度降至 0.3 → 添加去闪烁后处理 → 将 AnimateDiff 上下文重叠增加至 4+

9. 队列卡住／未处理 → POST /interrupt 以取消 → POST /free 以卸载模型 → 重启 ComfyUI

10. 生成缓慢 → 检查是否启用了 --lowvram（在 RTX 5090 上请移除此选项） → 改用 --highvram → 将 cuDNN 更新至 8800+ → 为 Wan 模型启用 SageAttention

决策树：质量问题

OUTPUT LOOKS WRONG
    |
    |-- Faces look wrong
    |   |-- Too smooth/plastic → Add skin texture LoRA (0.2-0.4)
    |   |-- Wrong identity → Increase identity weight, check reference quality
    |   |-- Burned/hot → Lower CFG to 4-5, reduce InstantID weight
    |   |-- Deformed → Add "bad anatomy, deformed" to negative
    |   |-- Different every time → Fix seed, add LoRA for consistency
    |
    |-- Colors wrong
    |   |-- Oversaturated → Lower CFG, add "oversaturated" to negative
    |   |-- Washed out → Check VAE is loaded, try different scheduler
    |   |-- Color shift in video → Add color correction post-processing
    |
    |-- Resolution/sharpness
    |   |-- Blurry → Increase steps (25-30), check resolution matches model
    |   |-- Pixelated → Use proper upscaler (4x-UltraSharp), not resize
    |   |-- Artifacts → Lower denoise, check for model corruption
    |
    |-- Composition
    |   |-- Ignoring prompt → Increase CFG slightly, simplify prompt
    |   |-- Extra limbs/objects → Add to negative prompt, use ControlNet
    |   |-- Wrong pose → Add ControlNet OpenPose with reference

缺失依赖项处理

当工作流引用的内容不在清单中时：

缺失的自定义节点
1. Identify package from class_type (see inventory skill's mapping)
2. Suggest: "Open ComfyUI-Manager → Search → Install {package_name}"
3. Alternative: "cd {ComfyUI}/custom_nodes && git clone {repo_url}"
4. Remind: Restart ComfyUI after installation
缺失的模型
1. Look up in references/models.md for download link
2. Provide: exact filename, download URL, target directory
3. For large models (>10GB): suggest HF CLI for reliability
   "huggingface-cli download {repo} {file} --local-dir {path}"
版本不兼容
1. Check ComfyUI version vs node package requirements
2. Suggest: "cd {ComfyUI} && git pull" for ComfyUI update
3. Or: pin specific node version if newest breaks things

升级处理

如果故障排查仍无法解决问题：

  1. 查看 ComfyUI GitHub Issues，确认是否存在已知问题
  2. 查看特定节点包的 Issues
  3. 在 r/comfyui 搜索社区解决方案
  4. 建议在 ComfyUI Discord 发帖并附上错误详情

参考资料

  • references/troubleshooting.md - 完整错误数据库及解决方案
  • state/inventory.json - 当前安装状态
  • references/models.md - 模型下载链接和路径

评论

支持 Markdown