> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-mintlify-b90d3c69.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何排查和解决 ComfyUI 中出现的错误

> 常见 ComfyUI 问题、解决方案和如何有效报告错误

<Tip>
  我们日常收到的诸多反馈问题，我们发现绝大部分的问题提交都与自定义节点有关，所以在提交对应的错误反馈之前，请你确保详细阅读了[自定义节点故障排查](/zh/troubleshooting/custom-node-issues)部分的指南，来确保对应的问题并不是由 ComfyUI 核心问题导致的。
</Tip>

<Card title="自定义节点故障排查指南" icon="puzzle-piece" href="/zh/troubleshooting/custom-node-issues">
  查看如何排查自定义节点导致的问题。
</Card>

## 常见问题与快速修复

在深入详细故障排查之前，请尝试这些常见解决方案：

### ComfyUI 无法启动

**症状：** 应用程序在启动时崩溃、黑屏或无法加载

**快速修复：**

1. **检查系统要求** - 确保您的系统符合[最低要求](/zh/installation/system_requirements)
2. **更新 GPU 驱动程序** - 从 NVIDIA/AMD/Intel 下载最新驱动程序

### 生成失败或产生错误

**症状：** "Prompt execution failed"（提示执行失败）对话框，带有"Show report"（显示报告）按钮，工作流停止执行

**快速修复：**

1. **点击"Show report"** - 阅读详细的报错信息以识别具体问题
2. **检查是否是自定义节点问题** - [遵循我们的自定义节点故障排查指南](/zh/troubleshooting/custom-node-issues)
3. **验证模型文件** - 查看[模型文档](/zh/development/core-concepts/models)了解模型设置
4. **检查显存使用情况** - 关闭其他使用 GPU 内存的应用程序

### 性能缓慢

**症状：** 生成时间非常慢、系统冻结、内存不足错误

**快速修复：**

1. **降低分辨率/批次大小** - 减少图像大小或图像数量
2. **使用内存优化标志** - 请参见下方性能优化部分
3. **关闭不必要的应用程序** - 释放 RAM 和显存
4. **检查 CPU/GPU 使用率** - 使用任务管理器识别瓶颈

**性能优化命令：**

对于低显存系统：

```bash theme={null}
# 低显存模式（使用 CPU 处理文本编码器）
python main.py --lowvram

# CPU 模式（非常慢但适用于任何硬件，仅作为最后手段使用）
python main.py --cpu
```

提高性能：

```bash theme={null}
# 禁用预览（节省显存和处理）
python main.py --preview-method none

# 使用优化的注意力机制
python main.py --use-pytorch-cross-attention
python main.py --use-flash-attention

# 异步权重卸载
python main.py --async-offload
```

内存管理：

```bash theme={null}
# 为操作系统保留特定显存量（以 GB 为单位）
python main.py --reserve-vram 2

# 禁用智能内存管理
python main.py --disable-smart-memory

# 使用不同的缓存策略
python main.py --cache-none      # 更少的内存使用，但更慢
python main.py --cache-lru 10    # 缓存 10 个结果，更快
python main.py --cache-classic   # 使用旧风格（激进）的缓存
```

## 安装过程中出现的问题

### 桌面应用问题

有关全面的桌面安装故障排查，请参见[桌面安装指南](/zh/installation/desktop/windows)。

<Tabs>
  <Tab title="Windows">
    * **不支持的设备**：Comfy Desktop Windows 仅支持带有 CUDA 的 NVIDIA GPU。对于其他 GPU，请使用 [ComfyUI 便携版](/zh/installation/comfyui_portable_windows)或[手动安装](/zh/installation/manual_install)
    * **安装失败**：以管理员身份运行安装程序，确保至少 15GB 磁盘空间
    * **维护页面**：如果下载失败，请检查[镜像设置](/zh/installation/desktop/windows#mirror-settings)
    * **缺少模型**：迁移时模型不会被复制，仅链接。请验证模型路径
  </Tab>

  <Tab title="macOS">
    * **"应用程序已损坏"**：在安全性与隐私设置中允许应用程序
    * **性能问题**：在隐私设置中授予完整磁盘访问权限
    * **崩溃**：检查控制台应用程序以获取崩溃报告
  </Tab>

  <Tab title="Linux">
    * **缺少库**：使用包管理器安装依赖项
    * **LD\_LIBRARY\_PATH 错误**：PyTorch 库路径问题（见下文）
  </Tab>
</Tabs>

### 手动安装问题

<Note>
  文档可能略有过时。如果出现问题，请手动验证是否存在更新的稳定版本的 pytorch 或任何列出的库。请参考 [pytorch 安装矩阵](https://pytorch.org/get-started/locally/) 或 [ROCm 网站](https://rocm.docs.amd.com/projects/install-on-linux/en/develop/install/3rd-party/pytorch-install.html#using-a-wheels-package) 等资源。
</Note>

**Python 版本冲突：**

```bash theme={null}
# 检查 Python 版本（需要 3.9+，推荐 3.12）
python --version

# 使用虚拟环境（推荐）
python -m venv comfyui_env
source comfyui_env/bin/activate  # Linux/Mac
comfyui_env\Scripts\activate     # Windows
```

**包安装失败：**

```bash theme={null}
# 首先更新 pip
python -m pip install --upgrade pip

# 安装依赖项
pip install -r requirements.txt

# 对于 NVIDIA GPU（CUDA 13.0）
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

# 对于 AMD GPU（仅限 Linux - ROCm 7.2）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2
```

### 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"

**解决方案：**

1. **现代 PyTorch 安装（最常见）：**

```bash theme={null}
# 对于带有 NVIDIA 包的虚拟环境
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 对于 conda 环境
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 或自动查找您的 Python site-packages
PYTHON_PATH=$(python -c "import site; print(site.getsitepackages()[0])")
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 您可能还需要其他 NVIDIA 库
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cuda_runtime/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cublas/lib:$LD_LIBRARY_PATH
```

2. **查找你拥有的库：**

```bash theme={null}
# 检查已安装的 NVIDIA 包
python -c "import site; import os; nvidia_path=os.path.join(site.getsitepackages()[0], 'nvidia'); print('NVIDIA libs:', [d for d in os.listdir(nvidia_path) if os.path.isdir(os.path.join(nvidia_path, d))] if os.path.exists(nvidia_path) else 'Not found')"

# 查找 PyTorch 需要的缺失库
python -c "import torch; print(torch.__file__)"
ldd $(python -c "import torch; print(torch.__file__.replace('__init__.py', 'lib/libtorch_cuda.so'))")
```

3. **为你的环境永久设置：**

```bash theme={null}
# 对于虚拟环境，添加到激活脚本
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> $VIRTUAL_ENV/bin/activate

# 对于 conda 环境
conda env config vars set LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 对于全局 bashrc（根据需要调整 Python 版本）
echo 'export LD_LIBRARY_PATH=$(python -c "import site; print(site.getsitepackages()[0])")/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
```

4. **替代方案：使用 ldconfig：**

```bash theme={null}
# 检查当前库缓存
ldconfig -p | grep cuda
ldconfig -p | grep nccl

# 如果缺失，添加库路径（需要 root 权限）
sudo echo "/usr/local/cuda/lib64" > /etc/ld.so.conf.d/cuda.conf
sudo ldconfig
```

5. **调试库加载：**

```bash theme={null}
# 详细库加载以查看缺失的内容
LD_DEBUG=libs python main.py 2>&1 | grep "looking for"

# 检查 PyTorch CUDA 可用性
python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"
```

## 模型相关问题

有关综合模型故障排查，包括架构不匹配、缺少模型和加载错误，请参见专门的[模型问题](/zh/troubleshooting/model-issues)页面。

## 网络和 API 问题

### 合作节点不工作

**症状：** API 调用失败、超时错误、配额超出

**解决方案：**

1. **检查 API 密钥有效性** - 在[用户设置](/zh/interface/user)中验证密钥
2. **检查账户积分** - 确保有足够的 [API 积分](/zh/interface/credits)
3. **验证互联网连接** - 使用其他在线服务进行测试
4. **检查服务状态** - 提供商可能正在经历停机

### 连接问题

**症状：** "无法连接到服务器"、超时错误

**解决方案：**

1. **检查防火墙设置** - 允许 ComfyUI 通过防火墙
2. **尝试不同端口** - 默认是 8188，尝试 8189 或 8190
3. **临时禁用 VPN** - VPN 可能阻止连接
4. **检查代理设置** - 如果不需要，禁用代理

### 前端问题

**"Frontend or Templates Package Not Updated"（前端或模板包未更新）：**

```bash theme={null}
# 通过 Git 更新 ComfyUI 后，更新前端依赖
pip install -r requirements.txt
```

**"Can't Find Custom Node"（找不到自定义节点）：**

* 在 ComfyUI 设置中禁用节点验证

**"Error Toast About Workflow Failing Validation"（工作流验证失败的错误提示）：**

* 暂时在设置中禁用工作流验证
* 向 ComfyUI 团队报告问题

**非 Localhost 访问时的登录问题：**

* 普通登录仅在从 localhost 访问时有效
* 对于局域网/远程访问：在 [platform.comfy.org/login](https://platform.comfy.org/login) 生成 API 密钥
* 在登录对话框中使用 API 密钥，或使用 `--api-key` 命令行参数

## 硬件特定问题

### NVIDIA GPU 问题

**"Torch not compiled with CUDA enabled" 错误：**

```bash theme={null}
# 先卸载 torch
pip uninstall torch

# 安装带 CUDA 13.0 的稳定版 PyTorch
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

# 对于 nightly 版本（可能有性能改进）
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132

# 验证 CUDA 支持
python -c "import torch; print(torch.cuda.is_available())"
```

**GPU 未被检测到：**

```bash theme={null}
# 检查 GPU 是否可见
nvidia-smi

# 检查驱动版本和 CUDA 兼容性
nvidia-smi --query-gpu=driver_version --format=csv
```

### AMD GPU 问题

**ROCm 支持（仅限 Linux）：**

```bash theme={null}
# 安装稳定的 ROCm PyTorch（撰写时为 7.2）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2

# 对于 nightly 版本（撰写时为 ROCm 7.2，可能有性能改进）
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2
```

**不支持的 AMD GPU：**

```bash theme={null}
# 对于 RDNA2 或更老型号（6700、6600）
HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py

# 对于 RDNA3 显卡（7600）
HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py
```

**性能优化：**

```bash theme={null}
# 启用实验性内存高效注意力（PyTorch 2.4 后不再需要）
TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention

# 启用可调优操作（首次运行慢，后续运行更快）
PYTORCH_TUNABLEOP_ENABLED=1 python main.py
```

### Apple Silicon (M1/M2/M3) 问题

**MPS 后端设置：**

```bash theme={null}
# 安装 Apple Silicon 的 PyTorch nightly
# 请遵循 Apple 指南：https://developer.apple.com/metal/pytorch/

# 检查 MPS 可用性
python -c "import torch; print(torch.backends.mps.is_available())"

# 启动 ComfyUI
python main.py
```

**如果 MPS 导致问题：**

```bash theme={null}
# 强制 CPU 模式
python main.py --cpu

# 带内存优化
python main.py --force-fp16 --cpu
```

### Intel GPU 问题

**方式一：原生 PyTorch XPU 支持（Windows/Linux）：**

```bash theme={null}
# 安装带 XPU 支持的 PyTorch nightly
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu

# 启动 ComfyUI
python main.py
```

**方式二：Intel Extension for PyTorch（IPEX）：**

```bash theme={null}
# 对于 Intel Arc A 系列显卡
conda install libuv
pip install torch==2.3.1.post0+cxx11.abi torchvision==0.18.1.post0+cxx11.abi torchaudio==2.3.1.post0+cxx11.abi intel-extension-for-pytorch==2.3.110.post0+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/
```

## 获取帮助和报告错误

### 报告错误之前

1. **检查是否是已知问题：**
   * 搜索 [GitHub Issues](https://github.com/Comfy-Org/ComfyUI/issues)
   * 检查 [ComfyUI 论坛](https://forum.comfy.org/)
   * 查看 [Discord 讨论](https://discord.com/invite/comfyorg)

2. **尝试基本故障排查：**
   * 使用[默认工作流](/zh/get_started/first_generation)进行测试
   * 禁用所有自定义节点（参见[自定义节点故障排查](/zh/troubleshooting/custom-node-issues)）
   * 检查控制台/终端中的报错信息
   * 如果使用 comfy-cli，尝试更新：`comfy node update all`

### 如何有效报告错误

#### 对于 ComfyUI 核心问题

**提交位置：** [GitHub Issues](https://github.com/Comfy-Org/ComfyUI/issues)

#### 对于桌面应用问题

**提交位置：** [桌面 GitHub Issues](https://github.com/Comfy-Org/desktop/issues)

#### 对于前端问题

**提交位置：** [前端 GitHub Issues](https://github.com/Comfy-Org/ComfyUI_frontend/issues)

#### 对于自定义节点问题

**提交位置：** 请到对应的自定义节点仓库中提交问题

### 需要提供的信息

报告任何问题时，请包括以下内容：

<Steps>
  <Step title="系统信息">
    <Tabs>
      <Tab title="从 ComfyUI 界面获取">
        **系统信息（可在设置的关于页面找到）：**

        * 操作系统（Windows 11、macOS 14.1、Ubuntu 22.04 等）
        * ComfyUI 版本（检查设置中的关于页面）
        * Python 版本：`python --version`
        * PyTorch 版本：`python -c "import torch; print(torch.__version__)"`
        * GPU 型号和驱动程序版本
        * 安装方式（桌面版、便携版、手动安装、comfy-cli）

                  <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/13fptzMgnetfPFwP/images/troubleshooting/menu-about.jpg?fit=max&auto=format&n=13fptzMgnetfPFwP&q=85&s=3b2088b0d0449c7c4cb50c2675b8eab8" alt="设置菜单-关于页面" width="4002" height="2442" data-path="images/troubleshooting/menu-about.jpg" />
      </Tab>

      <Tab title="从命令行获取">
        <Tabs>
          <Tab title="Windows">
            ```bash theme={null}
            # 系统信息
            systeminfo | findstr /C:"OS Name" /C:"OS Version"

            # GPU 信息
            wmic path win32_VideoController get name

            # Python 和 PyTorch 信息
            python --version
            python -c "import torch; print(f'PyTorch: {torch.__version__}')"
            python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
            ```
          </Tab>

          <Tab title="macOS/Linux">
            ```bash theme={null}
            # 系统信息
            uname -a

            # GPU 信息（Linux）
            lspci | grep VGA

            # Python 和 PyTorch 信息
            python --version
            python -c "import torch; print(f'PyTorch: {torch.__version__}')"
            python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
            ```
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Step>

  <Step title="桌面应用问题">
    **对于桌面应用问题，还需提供：**

    * 日志文件来自：`C:\Users\<用户名>\AppData\Roaming\ComfyUI\logs`（Windows）
    * 配置文件来自：`C:\Users\<用户名>\AppData\Roaming\ComfyUI`（Windows）
  </Step>

  <Step title="问题的详细信息">
    **问题的详细信息：**

    * 问题的清晰描述
    * 重现问题的步骤
    * 预期行为与实际行为
    * 如果可以，提供截图或复现过程的屏幕录制

    **报错信息：**

    * 控制台/终端的完整错误文本
    * 浏览器控制台错误（F12 → 控制台选项卡）
    * 任何崩溃日志或错误对话框
  </Step>

  <Step title="其他上下文">
    **其他上下文：**

    * 已安装的自定义节点列表
    * 重现问题的工作流文件（.json）
    * 最近的更改（新安装、更新等）
  </Step>
</Steps>

## 社区资源

* **官方论坛：** [forum.comfy.org](https://forum.comfy.org/)
* **Discord：** [ComfyUI Discord 服务器](https://discord.com/invite/comfyorg)
* **Reddit：** [r/comfyui](https://reddit.com/r/comfyui)
* **YouTube：** [ComfyUI 教程](https://www.youtube.com/@comfyorg)