我们日常收到的诸多反馈问题,我们发现绝大部分的问题提交都与自定义节点有关,所以在提交对应的错误反馈之前,请你确保详细阅读了 自定义节点故障排除 部分的指南,来确保对应的问题并不是由 ComfyUI 核心问题导致的。
自定义节点故障排除指南
查看如何排查自定义节点导致的问题。
常见问题与快速修复
在深入详细故障排除之前,请尝试这些常见解决方案:ComfyUI 无法启动
症状: 应用程序在启动时崩溃、黑屏或无法加载 快速修复:- 检查系统要求 - 确保您的系统符合最低要求
- 更新 GPU 驱动程序 - 从 NVIDIA/AMD/Intel 下载最新驱动程序
生成失败或产生错误
症状: “Prompt execution failed”(提示执行失败)对话框,带有”Show report”(显示报告)按钮,工作流停止执行 快速修复:- 点击”Show report” - 阅读详细错误消息以识别具体问题
- 检查是否是自定义节点问题 - 遵循我们的自定义节点故障排除指南
- 验证模型文件 - 查看模型文档了解模型设置
- 检查显存使用情况 - 关闭其他使用 GPU 内存的应用程序
性能缓慢
症状: 生成时间非常慢、系统冻结、内存不足错误 快速修复:- 降低分辨率/批次大小 - 减少图像大小或图像数量
- 使用内存优化标志 - 请参见下方性能优化部分
- 关闭不必要的应用程序 - 释放 RAM 和显存
- 检查 CPU/GPU 使用率 - 使用任务管理器识别瓶颈
安装过程中出现的问题
桌面应用问题
有关全面的桌面安装故障排除,请参见桌面安装指南。- Windows
- macOS
- Linux
- 无法安装:以管理员身份运行安装程序
- 缺少依赖项:安装 Visual C++ 可再发行组件
- 启动时崩溃:检查 Windows 事件查看器以获取错误详细信息
手动安装问题
文档可能略有过时。如果出现问题,请手动验证是否存在更新的稳定版本的 pytorch 或任何列出的库。请参考 pytorch 安装矩阵 或 ROCm 网站 等资源。
Linux 特定问题
LD_LIBRARY_PATH 错误: 常见错误:- “libcuda.so.1: cannot open shared object file”
- “libnccl.so: cannot open shared object file”
- “ImportError: libnvinfer.so.X: cannot open shared object file”
- 现代 PyTorch 安装(最常见):
- 查找你拥有的库:
- 为你的环境永久设置:
- 替代方案:使用 ldconfig:
- 调试库加载:
模型相关问题
有关综合模型故障排除,包括架构不匹配、缺少模型和加载错误,请参见专门的模型问题页面。网络和 API 问题
API 节点不工作
症状: API 调用失败、超时错误、配额超出 解决方案:连接问题
症状: “无法连接到服务器”、超时错误 解决方案:- 检查防火墙设置 - 允许 ComfyUI 通过防火墙
- 尝试不同端口 - 默认是 8188,尝试 8189 或 8190
- 临时禁用 VPN - VPN 可能阻止连接
- 检查代理设置 - 如果不需要,禁用代理
硬件特定问题
NVIDIA GPU 问题
CUDA 错误、GPU 未检测到:AMD GPU 问题
ROCm 支持、性能问题:Apple Silicon (M1/M2/M3) 问题
MPS 后端错误:获取帮助和报告错误
报告错误之前
-
检查是否是已知问题:
- 搜索 GitHub Issues
- 检查 ComfyUI 论坛
- 查看 Discord 讨论
- 尝试基本故障排除:
如何有效报告错误
对于 ComfyUI 核心问题
问题提交: GitHub Issues对于桌面应用问题
问题提交: 桌面 GitHub Issues对于前端问题
问题提交: 前端 GitHub Issues对于自定义节点问题
问题提交: 请到对应的自定义节点仓库中提交问题在 issue 中你需要提供的信息
报告任何问题时,请包括以下内容:1
系统信息
- 从 ComfyUI 中获取
- 从命令行获取
- 操作系统(Windows 11、macOS 14.1、Ubuntu 22.04 等)
- ComfyUI 版本(检查设置中的关于页面)
-
Python 版本:
python --version
-
PyTorch 版本:
python -c "import torch; print(torch.__version__)"
-
GPU 型号和驱动程序版本
2
错误的详细信息
- 问题的清晰描述
- 重现问题的步骤
- 预期行为与实际行为
- 如果可以,提供截图或复现过程的屏幕录制
3
错误消息
- 控制台/终端的完整错误文本
- 浏览器控制台错误(F12 → 控制台选项卡)
- 任何崩溃日志或错误对话框
4
其他上下文
- 已安装的自定义节点列表
- 重现问题的工作流文件(.json)
- 最近的更改(新安装、更新等)
社区资源
- 官方论坛: forum.comfy.org
- Discord: ComfyUI Discord 服务器
- Reddit: r/comfyui
- YouTube: ComfyUI 教程
对于影响许多用户的紧急问题,请查看我们的状态页面和官方 Twitter以获取公告。