Comfy CLI 故障排查指南

Comfy CLI 的大多数故障都源于缺少前置条件或跳过了某个设置步骤。遇到问题时，请先按下面的顺序检查。

前置条件

Comfy CLI 需要系统已安装 git。请先安装 git，这样 comfy install 和 comfy update 才能克隆 ComfyUI 及其自定义节点。

comfy install 会把 ComfyUI 安装到当前激活的 Python 环境，该环境需要 Python 3.10 或更高版本。请先创建并激活虚拟环境：

python3 -m venv comfy-env
source comfy-env/bin/activate
comfy install

comfy install 会询问你使用哪种 GPU，并安装与之匹配的 PyTorch 构建。你可以直接回答提示，也可以用参数指定 GPU，以便在无人值守环境下运行：

平台	`comfy install` 安装内容	你仍需准备
NVIDIA	含 CUDA runtime 的 PyTorch（pip wheel）	最新 GPU 驱动（不必完整 CUDA Toolkit）
AMD Linux	ROCm PyTorch wheel	满足这些 wheel 要求的 ROCm 兼容 AMD 驱动/栈
AMD Windows	`torch-directml`	兼容的 AMD GPU（走 DirectML，不是 ROCm）
Apple silicon	PyTorch nightly wheel（CPU 索引；Metal/MPS）	Apple silicon 上的 macOS
Intel Arc	PyTorch XPU wheel	兼容的 Intel Arc GPU / XPU 栈
CPU	CPU 版 PyTorch wheel	无需独立 GPU

comfy install --nvidia

如果你自行安装 PyTorch，请加上 --skip-torch-or-directml。comfy env 会打印 ComfyUI 使用的 Python 环境和工作区。

comfy setup 通过浏览器登录，因此在 CI、devcontainer 或无头服务器上无法完成。此时请改用 API Key 并以非交互方式运行：

comfy setup --where cloud --api-key comfyui-... --non-interactive