ComfyUI 工作流报错…

当 ComfyUI 工作流失败、报错或产出异常结果时，按错误分类、上下文收集、模式匹配的流程定位并修复问题。

适用场景

解决思路

1. 先对错误分类：Server（连接被拒、超时、崩溃）先检查 ComfyUI 是否在运行并访问 `/system_stats`；Workflow（节点报错、缺输入、类型不匹配）对照 inventory 校验工作流；Quality（伪影、身份不对、模糊）检查 CFG、权重、分辨率等设置；Performance（OOM、生成慢、VRAM 报错）检查 VRAM 占用与模型大小。
2. 诊断前先收集上下文：精确的错误信息文本、正在执行的工作流（或描述）、涉及的模型（checkpoint、LoRA、ControlNet 等）、设置（CFG、steps、分辨率、采样器）、硬件信息（来自 `foundation/hardware-profile.md`）、当前安装清单（来自 `state/inventory.json`）。
3. 对照 `references/troubleshooting.md` 中的完整错误数据库匹配错误模式。
4. 遇到 "CUDA out of memory"：使用 FP8（`--fp8_e4m3fn-unet`）、启用 tiled VAE、降低分辨率、重启 ComfyUI 以清理显存碎片。
5. 遇到 "Node type not found: {name}"：通过 ComfyUI-Manager 安装对应自定义节点包，并查阅 `comfyui-inventory` 的节点到包映射。
6. 遇到 "Expected scalar type BFloat16 but found Float"：这是精度不匹配，添加 `--force-fp16` 或改用精度匹配的节点。
7. 遇到人脸过曝/发烫：将 CFG 降到 4-5（InstantID），降低身份方法权重，在负面嵌入中加入 35% 噪声。
8. 遇到 "No model found at path"：检查文件名拼写（必须完全匹配）、确认文件在正确子目录、运行 inventory 扫描确认。
9. 遇到 1024x1024 出现水印伪影：改用 1016x1016 或 1020x1020。
10. 遇到身份与参考图不符：使用更高质量、清晰正面的参考图，将 IP-Adapter 权重提高到 0.8 以上，确认已安装 InsightFace antelopev2。
11. 遇到视频闪烁：将 FaceDetailer denoise 降到 0.3，加入 deflicker 后处理，将 AnimateDiff context overlap 提高到 4 以上。
12. 遇到队列卡住不处理：POST `/interrupt` 取消，POST `/free` 卸载模型，重启 ComfyUI。
13. 遇到生成慢：检查是否启用了 `--lowvram`（在 RTX 5090 上应移除），改用 `--highvram`，将 cuDNN 升级到 8800+，对 Wan 模型启用 SageAttention。
14. 质量问题的决策树——人脸：太光滑/塑料感则加皮肤纹理 LoRA（0.2-0.4）；身份不对则提高身份权重并检查参考图质量；过曝/发烫则降低 CFG 到 4-5 并降低 InstantID 权重；变形则在负面提示加 "bad anatomy, deformed"；每次都不一样则固定 seed 并加 LoRA 提升一致性。
15. 质量问题的决策树——颜色：过饱和则降低 CFG 并在负面加 "oversaturated"；发白则检查 VAE 是否加载并尝试不同 scheduler；视频偏色则加颜色校正后处理。
16. 质量问题的决策树——分辨率/锐度：模糊则提高 steps（25-30）并检查分辨率是否匹配模型；像素化则用正规放大器（4x-UltraSharp）而非直接缩放；伪影则降低 denoise 并检查模型是否损坏。
17. 质量问题的决策树——构图：忽略提示则略微提高 CFG 并简化提示；多手多脚/多余物体则加入负面提示并使用 ControlNet；姿势不对则用参考图加 ControlNet OpenPose。
18. 缺失自定义节点时：从 class_type 识别包名（见 inventory 技能的映射），建议在 ComfyUI-Manager 中搜索并安装该包，或执行 `cd {ComfyUI}/custom_nodes && git clone {repo_url}`，并提醒安装后重启 ComfyUI。
19. 缺失模型时：在 `references/models.md` 查找下载链接，提供精确文件名、下载 URL、目标目录；大于 10GB 的模型建议用 HF CLI 提高可靠性：`huggingface-cli download {repo} {file} --local-dir {path}`。
20. 版本不兼容时：检查 ComfyUI 版本与节点包要求，建议用 `cd {ComfyUI} && git pull` 更新 ComfyUI，或在最新版出问题时固定特定节点版本。
21. 若排查后仍未解决：依次检查 ComfyUI GitHub Issues、对应节点包的 Issues、r/comfyui 社区方案，最后建议带错误详情到 ComfyUI Discord 发帖求助。
22. 参考文件：`references/troubleshooting.md`（完整错误数据库）、`state/inventory.json`（当前安装状态）、`references/models.md`（模型下载链接与路径）。

适用边界 · 注意事项

• 不适用于非 ComfyUI 的生成式 AI 工具或框架的故障排查。
• 不适用于与 ComfyUI 无关的通用编程错误或系统故障。
• 需要先有 ComfyUI 安装及相应 inventory/硬件配置文件才能执行上下文收集与匹配。