适用场景
ComfyUI 是一套基于节点连线的 Stable Diffusion 前端，工作流可以保存成 JSON 反复复用，适合需要精确控制采样、AI 词典：ControlNet">ControlNet、局部重绘等环节的出图需求。这套方案适合有一块独立显卡、想在自己电脑或公司内网机器上跑图，又不希望把图片上传到第三方服务的人。本文覆盖从零开始把 ComfyUI 跑起来、把模型放对位置、以及显存不够时怎么降级运行。
环境与前置条件
操作系统
- Windows 10 / 11（64 位）
- Linux（Ubuntu、Debian、CentOS 等常见发行版）
- macOS（Apple Silicon 芯片走 MPS 后端，速度与兼容性另说）
Python 与运行时
- Python 3.10 或更高版本，具体支持范围以官方仓库 README 当前说明为准。不建议用系统自带的 Python，容易和系统包管理器打架。
- pip 需要能访问外网。如果处在内网环境，提前配好镜像源。
显卡与驱动
- NVIDIA 显卡走 CUDA，需要安装对应驱动。先用
nvidia-smi看驱动版本，再决定装哪个 CUDA 版本的 PyTorch wheel。 - AMD 显卡在 Linux 上走 ROCm，Windows 上支持有限，买之前先查官方支持列表。
- 纯 CPU 也能跑，但出一张 512×512 的图可能要几分钟到十几分钟，只适合验证流程。
硬件建议
| 项目 | 建议 |
|---|---|
| 显存 | 8GB 以上比较舒服；6GB 可用低显存模式跑 SD1.5；4GB 及以下需要更激进的降级 |
| 内存 | 16GB 起步，32GB 更从容（低显存模式会把压力转移到内存） |
| 磁盘 | 预留 50GB 以上。底模单个 2~7GB，加上 LoRA、ControlNet、放大模型，很快上百 GB |
| 网络 | 拉取依赖和模型需要稳定外网 |
安装方式对比
| 方式 | 适合谁 | 优点 | 注意点 |
|---|---|---|---|
| Windows 便携包 | 只想快点出图的 Windows 用户 | 解压即用，自带 Python 和 PyTorch | 升级要按官方说明操作，装自定义节点偶尔会遇到依赖冲突 |
| 手动源码安装 | Linux 用户、想精细控制环境的人 | 环境干净，升级方便，便于接 CI | 需要自己装 Python、PyTorch、依赖 |
| comfy-cli | 习惯命令行的用户 | 一条命令装好、启动、更新 | 需要先有可用的 Python 环境 |
| 第三方整合启动器 | 完全不想碰命令行的用户 | 图形界面管理模型和节点 | 版本更新节奏和官方不同步，出问题排查链路长 |
下面重点写手动安装，因为它是所有方式的基础，理解了它，其他方式的报错也能看懂。
分步骤部署
第 1 步：确认显卡驱动
```bash
nvidia-smi
```
输出的右上角会显示 CUDA Version: xx.x，这表示当前驱动最高支持的 CUDA 版本。后面装 PyTorch 时选的 CUDA 版本不能超过这个数。
Windows 上如果提示找不到命令，说明驱动没装或没加入 PATH，去 NVIDIA 官网按显卡型号下载驱动安装。
第 2 步：安装 Git 与 Python
```bash
Ubuntu / Debian
sudo apt update
sudo apt install -y git python3 python3-venv python3-pip
验证
git --version
python3 --version
```
Windows 用户从 python.org 下载安装包，安装时勾选 Add Python to PATH。装完在 PowerShell 里执行 python --version 确认。
第 3 步：拉取 ComfyUI 源码
```bash
cd ~
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
```
克隆完成后目录里应该能看到 main.py、requirements.txt、models/、custom_nodes/ 等。
第 4 步：创建独立虚拟环境
```bash
python3 -m venv venv
Linux / macOS
source venv/bin/activate
Windows PowerShell
venv\Scripts\Activate.ps1
Windows CMD
venv\Scripts\activate.bat
```
激活成功后命令行前面会出现 (venv) 前缀。这一步的作用是把 ComfyUI 的依赖和系统 Python 隔离开，以后升级或删库都不会互相影响。
第 5 步：安装 PyTorch
PyTorch 的安装命令是分 CUDA 版本的，具体写法以 PyTorch 官网当前给出的命令为准。形如：
```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cuXXX
```
把 cuXXX 换成不超过第 1 步里看到的上限版本。纯 CPU 用户去掉 --index-url 参数直接装即可。
Apple Silicon 用户按官方说明安装支持 MPS 的版本。
第 6 步：安装 ComfyUI 依赖
```bash
pip install -r requirements.txt
```
这一步会拉取 transformers、safetensors、aiohttp 等库，视网络情况需要几分钟。
第 7 步：首次启动
```bash
python main.py
```
看到类似下面的输出说明启动成功：
```
Total VRAM xxxxx MB, total RAM xxxxx MB
pytorch version: x.x.x
Set vram state to: NORMAL_VRAM
Device: cuda:0 NVIDIA ...
Starting server
To see the GUI go to: http://127.0.0.1:8188
```
浏览器打开 http://127.0.0.1:8188，能看到节点画布就说明服务通了。
第 8 步：放置模型文件
ComfyUI 的 models/ 目录下按用途分子目录，常见的有：
| 目录 | 放什么 |
|---|---|
models/checkpoints | 底模（SD1.5、SDXL、Flux 等大模型） |
models/loras | LoRA 微调权重 |
models/vae | 独立的 VAE 文件 |
models/controlnet | ControlNet 模型 |
models/clip、models/clip_vision | 文本编码器、视觉编码器 |
models/unet 或 models/diffusion_models | 拆分后的 UNet / DiT 权重 |
models/embeddings | 文本反转（Textual Inversion） |
models/upscale_models | ESRGAN、SwinIR 等放大模型 |
目录名称可能随版本微调，以仓库里实际的 models/ 子目录为准。把下载好的 .safetensors 文件按类型丢进去，重启 ComfyUI 或在网页上点刷新，节点里的下拉框就能选到。
第 9 步：复用已有模型库（可选）
如果硬盘上已经有一份 WebUI 或其他工具的模型库，不必复制粘贴，用 extra_model_paths.yaml 指过去即可。在 ComfyUI 根目录新建 extra_model_paths.yaml：
```yaml
my_models:
base_path: /data/ai_models/
checkpoints: checkpoints
loras: loras
vae: vae
controlnet: controlnet
embeddings: embeddings
upscale_models: upscale_models
```
Windows 路径写成 D:/ai_models/ 这种正斜杠形式。配置完成后重启生效。
第 10 步：安装 ComfyUI Manager（可选但建议）
Manager 用来在网页里搜索、安装、更新自定义节点。在 custom_nodes 目录下拉取：
```bash
cd custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
cd ..
```
重启后界面右侧会出现 Manager 按钮。装完节点记得重启服务。
验证部署是否成功
验证 1：服务可访问
浏览器打开 http://127.0.0.1:8188，能看到默认工作流画布即为正常。
验证 2：GPU 是否被正确识别
```bash
python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
```
预期输出里第二个值是 True，第三个值是显卡型号。如果第二个是 False，看后面的排错部分。
验证 3：真的出一张图
在网页上依次点 Load Default（加载默认工作流），确认 Load Checkpoint 节点选到了模型，然后点 Queue Prompt。
预期结果：
- 命令行出现进度条和采样步数输出
output/目录下多出一张 PNG 文件- 网页预览区显示生成的图片
打开 output/ 目录能看到文件，就说明整条链路（模型加载 → 文本编码 → 采样 → VAE 解码 → 保存）都通了。
显存不足处理
出图时的显存主要被三部分占用：模型权重、文本编码器、VAE 解码时的中间张量。显存不够时按下面顺序尝试：
1. 换用低显存启动参数
```bash
中等显存（约 6~8GB）：把模型分块调度
python main.py --medvram
低显存（约 4~6GB）：更细粒度地搬运模型
python main.py --lowvram
极低显存：只把当前需要的层放进显存
python main.py --novram
```
这几个参数会让部分计算在内存里完成，代价是速度下降。--novram 相比 --lowvram 更省显存也更慢。内存建议 32GB 以上。
2. 降低分辨率
从 1024×1024 降到 768×768 或 512×512，显存占用大致按面积比例下降。先出小图确认效果，再用放大模型提分辨率。
3. 使用低精度权重
--fp8_e4m3fn 之类的低精度选项可以在支持的卡上减少权重占用，具体可用参数以官方 README 为准。部分模型社区直接提供 fp8 量化版本。
4. 换更小的模型
SD1.5 系模型比 SDXL 系省显存，SDXL 又比 Flux 系省。先用小模型跑通流程，再考虑换大的。
5. 关掉占显存的程序
浏览器（尤其是开了视频或硬件加速的标签页）、游戏、Docker 里的其他推理服务都会抢显存。Linux 上用 nvidia-smi 看有没有残留进程。
Windows 上要注意：任务管理器里显示的「共享 GPU 内存」是内存划过去的，不是真显存。当 nvidia-smi 显示显存已经满了，系统再往共享内存里塞数据，速度会掉得很厉害，看起来像"卡死"，其实是内存带宽不够。
常见报错与解决
报错 1：AssertionError: Torch not compiled with CUDA enabled
原因：装的是 CPU 版 PyTorch，或者装成了不匹配的 CUDA 版本。
解决：先看驱动支持的上限，再重装。
```bash
pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cuXXX
```
重装后用前面的验证命令确认 torch.cuda.is_available() 返回 True。
报错 2：torch.cuda.OutOfMemoryError: CUDA out of memory
原因：显存不足。常见于首次加载大模型、分辨率过高、同时跑了多个采样任务。
解决：按下面的顺序试。
```bash
先用低显存模式启动
python main.py --lowvram
```
同时把分辨率降到 512×512 或 768×768，关掉浏览器里其他吃显存的页面。如果是批量任务，减少并发数量。
报错 3：OSError: [Errno 98] Address already in use（Windows 上是 [Errno 10048]）
原因：8188 端口已被占用，通常是上一次的 ComfyUI 进程没退干净。
解决：换端口或者杀掉旧进程。
```bash
换端口最简单
python main.py --port 8189
Linux 查进程
lsof -i :8188
kill -9 <PID>
Windows 查进程
netstat -ano | findstr :8188
taskkill /PID <PID> /F
```
报错 4：Load Checkpoint 下拉列表是空的
原因：模型没放进 models/checkpoints，或者放进去的文件不是 ComfyUI 支持的格式，也可能是浏览器缓存了旧列表。
解决：
```bash
ls -lh models/checkpoints/
```
确认文件存在且后缀是 .safetensors 或 .ckpt。然后在网页上按 R 键或点刷新按钮重新拉取列表。如果配置了 extra_model_paths.yaml，检查路径写得对不对、有没有多余空格。
报错 5：ModuleNotFoundError: No module named 'xxx'（装完自定义节点后）
原因：自定义节点有自己的依赖，克隆下来不会自动安装。
解决：进入对应节点目录手动装。
```bash
cd custom_nodes/<节点目录名>
pip install -r requirements.txt
```
如果该节点目录下没有 requirements.txt，去看它的 README 说明。装完重启 ComfyUI。实在冲突严重，删掉该节点目录再重启，先恢复可用状态。
报错 6：克隆或安装依赖时卡住不动
原因：网络到 GitHub 或 PyPI 不稳定。
解决：PyPI 换镜像源，Git 可以配代理或改用镜像站点。这一步视所在网络环境处理，没有通用的一行命令。
后续维护
备份
需要备份的目录和文件：
models/——体积大，可以单独做增量备份或干脆不备份（能重新下载）custom_nodes/——自装节点，重新配置比较费时，建议备份user/default/workflows/——自己攒的工作流，这是最有价值的部分，务必定期导出extra_model_paths.yaml——配置文件，几行字，随手拷一份output/——出图结果，视需要保留
一个务实的做法：把工作流、extra_model_paths.yaml、custom_nodes 的目录清单定期打包，模型文件单独用同步工具处理。
升级
```bash
cd ComfyUI
git pull
pip install -r requirements.txt
```
升级前建议先备份 custom_nodes 目录，因为某些节点可能跟不上主仓库的接口变动。升级后如果启动报错，把 custom_nodes 临时改名为 custom_nodes_bak，确认是主程序问题还是节点问题。
便携包用户按官方仓库的更新说明操作，不要直接覆盖整个目录。
日志
前台运行时直接看命令行输出即可。需要后台运行：
```bash
nohup python main.py --lowvram > comfyui.log 2>&1 &
tail -f comfyui.log
```
日志里出现 Prompt executed in xx seconds 表示一次任务完整结束。
监控
```bash
每秒刷新显卡状态
watch -n 1 nvidia-smi
或者只记录一次
nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv
```
关注两个指标：显存占用是否贴近上限、GPU 利用率是否长期偏低。后者通常意味着瓶颈在内存或磁盘读取模型。
安全提醒
ComfyUI 默认只监听 127.0.0.1，也就是只有本机能访问。如果加 --listen 让局域网其他机器访问，注意它本身没有登录鉴权，不要把端口直接映射到公网。需要远程使用时，走内网穿透加认证，或者放在带鉴权的反向代理后面。
磁盘清理
output/ 和 temp/ 会持续增长，定期清理。模型换下来不用了也及时删，一个底模动辄几个 GB。可以写个定时任务，只保留最近若干天的输出图。