ComfyUI 本地环境配置与插件安装教程
从安装路线选择、模型目录规划，到插件安装与报错排查，一篇帮新手跑通本地 AI 绘图工作流
封面图：ComfyUI 本地节点式 AI 绘图环境搭建示意。
文章摘要
ComfyUI 是目前本地 AI 绘图和生成式视觉工作流里非常常用的节点式工具。它不像传统 WebUI 那样只依赖一个提示词输入框，而是把模型加载、文本编码、采样、VAE 解码、ControlNet、LoRA、放大、修脸、换脸、局部重绘等环节拆成一个个节点，适合做可复用、可调试、可扩展的工作流。
这篇教程面向第一次接触 ComfyUI 的新手，按照“先选路线、再装环境、再放模型、再装插件、最后排错”的顺序展开。读者照着做，可以从零完成 Windows、macOS 或 Linux 下的 ComfyUI 本地环境配置，并学会安装 ComfyUI Manager、自定义节点和常见模型文件。
| 项目 | 建议 |
| 适合读者 | AI 绘图新手、Stable Diffusion 用户、ComfyUI 工作流初学者、自媒体封面图/电商图创作者 |
| 推荐系统 | Windows + NVIDIA 显卡优先；Mac 建议 Apple Silicon；Linux 适合服务器或进阶用户 |
| 推荐路线 | 新手选 ComfyUI Desktop 或 Windows Portable；进阶用户选手动安装 |
| 本文重点 | 安装路线选择、模型目录、插件安装、Manager、常见报错排查、SEO 发布信息 |
目录
- 为什么选择 ComfyUI
- 安装前准备：硬件、软件与目录规划
- 三种安装路线：Desktop、Portable、手动安装
- 模型文件应该放在哪里
- ComfyUI 插件安装完整流程
- 跑通第一个工作流
- 常见问题排查
- 维护、更新与备份
- FAQ
- 相关阅读
- SEO 文档
- 官方参考来源
为什么选择 ComfyUI
ComfyUI 的核心优势
- 节点式工作流：每一步都可以被看见、复制、替换和复用，适合复杂 AI 绘图流程。
- 模型支持丰富：常见的 SD1.5、SDXL、FLUX、ControlNet、LoRA、Upscaler 等都能组合使用。
- 插件生态活跃：通过自定义节点可以扩展视频、图生图、局部重绘、风格化、批量处理等能力。
- 适合长期沉淀：工作流可以保存为 JSON，适合做团队模板、文章封面流水线、批量内容生产。
ComfyUI 适合哪些人
| 人群 | 是否推荐 | 原因 |
| AI 绘图新手 | 推荐，但建议从 Desktop/Portable 开始 | 安装门槛降低后，节点逻辑比 A1111 更适合理解生成流程 |
| Stable Diffusion 老用户 | 非常推荐 | 可以复用模型，并搭建更复杂的 ControlNet / LoRA 工作流 |
| 视频和工作流创作者 | 非常推荐 | 自定义节点生态支持 AnimateDiff、视频处理、局部控制等扩展 |
| 只想快速出图的人 | 可以，但不一定是最省心 | 如果只需要简单文生图，传统 WebUI 或在线工具更直接 |
| 服务器部署用户 | 推荐手动安装 | 更容易控制 Python、PyTorch、CUDA、依赖和多用户环境 |
安装前准备：硬件、软件与目录规划
硬件建议
| 配置 | 最低可用 | 推荐配置 | 说明 |
| 显卡 | CPU 也能跑，但非常慢 | NVIDIA RTX 3060 12GB / 4060 Ti 16GB / 4070 以上 | 显存越大，分辨率、批量和模型自由度越高 |
| 内存 | 16GB | 32GB 以上 | 复杂工作流、视频节点、批量任务建议更大内存 |
| 硬盘 | 30GB 可尝试 | 100GB – 500GB SSD | 模型文件很大，SDXL/FLUX/ControlNet/LoRA 会快速占满空间 |
| 系统 | Windows 10/11、macOS、Linux | Windows + NVIDIA 或 Linux + NVIDIA | Windows 新手优先；Linux 适合服务器 |
提示：如果你是 Windows + NVIDIA 显卡用户，先更新 NVIDIA 驱动，再安装 ComfyUI。很多启动失败并不是 ComfyUI 本身的问题，而是驱动或 PyTorch CUDA 版本不匹配。
基础软件清单
- 解压工具：7-Zip 或系统自带解压工具，用于解压 Windows Portable 包。
- Git：安装自定义节点、ComfyUI Manager、下载插件时很常用。
- Python：手动安装路线需要；Desktop/Portable 通常会自动或内置 Python。
- NVIDIA 驱动：NVIDIA GPU 用户必须确认驱动可用，命令行可用 nvidia-smi 验证。
- 文本编辑器：VS Code、Notepad++ 或系统记事本，用于编辑 YAML 配置。
nvidia-smi
python –version
git –version
推荐目录规划
- 不要放在中文路径、超长路径或 OneDrive 同步目录中，避免插件依赖安装失败。
- Windows 推荐放在 D:\AI\ComfyUI 或 D:\ComfyUI_windows_portable。
- 模型可以单独放在 D:\AI_Models，再通过 extra_model_paths.yaml 复用。
- 插件目录 custom_nodes 建议定期备份，复杂工作流依赖的节点都在这里。
安装路线怎么选
路线选择结论
| 使用场景 | 推荐路线 | 理由 |
| 完全新手，Windows NVIDIA 显卡 | ComfyUI Desktop 或 Windows Portable | 减少 Python 和依赖折腾，最快跑通第一张图 |
| 已有 A1111/Forge 模型库 | Desktop 或 Portable + extra_model_paths.yaml | 可以复用模型，避免重复下载几十 GB 文件 |
| Linux 服务器或云主机 | 手动安装 / comfy-cli | 方便控制环境、CUDA、端口和远程访问 |
| Mac M 系列芯片 | ComfyUI Desktop 或手动安装 | Desktop 仅支持 Apple Silicon；部分插件可能不兼容 |
| 需要开发自定义节点 | 手动安装 | 更容易调试依赖和源码 |
路线一：ComfyUI Desktop 安装
适用人群
ComfyUI Desktop 是官方推出的桌面应用路线，目标是把 Python 环境、依赖安装、启动服务、模型/工作流迁移等步骤尽量图形化。它适合不想手动管理 Python 和 PyTorch 的新手。
Windows Desktop 安装步骤
1. 进入 ComfyUI 官方下载页面，选择 Windows Desktop 版本。
2. 确认电脑是 NVIDIA 显卡路线，安装前更新 NVIDIA 驱动。
3. 双击安装包，按提示完成安装。
4. 首次启动时点击 Get Started，等待它创建环境和安装依赖。
5. 如果出现维护页面，按页面提示修复 Git、VC 运行库、Python 虚拟环境或依赖。
6. 进入界面后，先加载默认模板工作流，验证能否生成图片。
提示：Desktop 版本仍处于 Beta 阶段，实际界面和安装流程可能随版本调整。遇到界面变化时，以官方文档和安装器提示为准。
macOS Desktop 安装步骤
1. 确认 Mac 是 Apple Silicon（M1/M2/M3/M4）芯片。
2. 下载 macOS 安装包，打开后拖动 ComfyUI 到 Applications。
3. 也可以使用 Homebrew：brew install comfyui。
4. 首次启动后按初始化向导配置环境、模型目录和工作流。
5. 复杂插件如果安装失败，优先查看插件是否支持 macOS/Metal。
Linux Desktop 当前情况
截至本文整理时，ComfyUI 官方文档提示 Linux Desktop 预构建包暂未提供，Linux 用户建议走手动安装路线。Linux 服务器用户通常更关心 CUDA、Python、PyTorch、端口和远程访问，手动安装也更可控。
路线二：Windows Portable 解压即用
下载与解压
1. 进入 ComfyUI 官方 releases 或 portable 下载页面。
2. 根据显卡选择 NVIDIA、AMD、Intel 或 CPU 版本。NVIDIA 老显卡可考虑 PyTorch CUDA 12.6 + Python 3.12 的备用包。
3. 下载后用 7-Zip 解压到 D:\AI\ComfyUI_windows_portable。
4. 不要把压缩包直接放在桌面、中文目录或同步盘中长期运行。
D:\AI\ComfyUI_windows_portable
├── ComfyUI
├── python_embeded
├── update
├── run_cpu.bat
└── run_nvidia_gpu.bat
启动 ComfyUI
1. NVIDIA 显卡用户双击 run_nvidia_gpu.bat。
2. CPU 用户双击 run_cpu.bat，但速度会比较慢。
3. 命令行窗口出现 “To see the GUI go to: http://127.0.0.1:8188” 后，在浏览器打开该地址。
4. 第一次不要立刻安装一堆插件，先用默认工作流生成一张图。
http://127.0.0.1:8188
Portable 如何更新
- 优先使用 update 目录里的官方更新脚本。
- 更新前备份 ComfyUI/custom_nodes、models 和用户工作流 JSON。
- 如果插件依赖较多，先不要在重要项目交付前更新核心版本。
路线三：手动安装 ComfyUI
适用场景
- Linux 服务器部署。
- 需要自己控制 Python、PyTorch、CUDA 版本。
- 需要开发或调试自定义节点。
- 想用 conda、venv、uv 等工具管理环境。
Windows / Linux 通用思路
1. 安装 Git 和 Python。
2. 创建项目目录并克隆 ComfyUI 仓库。
3. 创建虚拟环境。
4. 根据显卡平台安装 PyTorch。
5. 安装 ComfyUI 依赖。
6. 运行 python main.py 启动服务。
git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate
pip install -r requirements.txt
python main.py
NVIDIA 用户 PyTorch 安装参考
手动安装时，最容易出错的是 PyTorch CUDA 版本。ComfyUI 官方 README 当前给出 NVIDIA 稳定版 PyTorch 安装示例，实际生产环境建议结合 PyTorch 官网安装选择器和本机驱动版本确认。
pip install torch torchvision torchaudio –extra-index-url https://download.pytorch.org/whl/cu130
macOS Apple Silicon 手动安装提醒
- Apple Silicon 可以运行 ComfyUI，但速度和 CUDA 显卡不可直接类比。
- 建议优先尝试 Desktop；需要手动安装时，参考 PyTorch Metal/MPS 路线。
- 部分插件只针对 CUDA/NVIDIA 优化，Mac 上可能无法安装或性能较低。
模型文件应该放在哪里
常见模型目录
| 模型类型 | 目录 | 用途 |
| Checkpoint / 主模型 | ComfyUI/models/checkpoints | SD1.5、SDXL、FLUX 等主模型文件 |
| VAE | ComfyUI/models/vae | 影响颜色、细节和解码质量 |
| LoRA | ComfyUI/models/loras | 风格、人物、服装、产品图等微调模型 |
| ControlNet | ComfyUI/models/controlnet | 姿态、线稿、深度图、边缘控制 |
| Upscale | ComfyUI/models/upscale_models | 图片超分放大 |
| CLIP / Text Encoder | ComfyUI/models/clip 或 text_encoders | 新模型工作流可能需要 |
如何复用已有模型库
如果你已经使用过 AUTOMATIC1111、Forge 或 Stability Matrix，不建议把模型复制多份。可以通过 extra_model_paths.yaml 指向已有模型目录。
a111:
base_path: D:/stable-diffusion-webui/
checkpoints: models/Stable-diffusion
vae: models/VAE
loras: models/Lora
controlnet: models/ControlNet
提示：YAML 对缩进很敏感。建议使用英文路径和正斜杠，保存为 UTF-8。修改后需要重启 ComfyUI。
ComfyUI 插件安装完整流程
优先安装 ComfyUI Manager
ComfyUI Manager 是最常用的插件管理工具，可以安装、更新、启用、禁用自定义节点，也能帮助识别工作流缺失节点。对于新手来说，它比手动逐个查 GitHub 仓库更省心。
cd ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager comfyui-manager
cd comfyui-manager
pip install -r requirements.txt
提示：新版 ComfyUI 支持通过 –enable-manager 启用 Manager。不同安装路线的 Manager 方式可能不同，Desktop、Portable 和手动安装请以官方说明为准。
通过 Manager 安装插件
1. 启动 ComfyUI。
2. 打开 Manager 面板。
3. 搜索需要的 Custom Node。
4. 点击 Install，等待安装完成。
5. 重启 ComfyUI。
6. 重新打开工作流，确认 Missing Nodes 是否消失。
通过 Git 安装插件
1. 复制插件 GitHub 仓库地址。
2. 进入 ComfyUI/custom_nodes 目录。
3. 执行 git clone。
4. 如果插件有 requirements.txt，用当前 ComfyUI 环境的 Python 安装依赖。
5. 重启 ComfyUI。
cd ComfyUI/custom_nodes
git clone https://github.com/作者名/插件仓库名.git
cd 插件仓库名
pip install -r requirements.txt
通过 ZIP 安装插件
- 适合无法使用 Git 的用户。
- 从 GitHub 点击 Code -> Download ZIP。
- 解压后把插件文件夹复制到 ComfyUI/custom_nodes。
- 不要形成 custom_nodes/插件名/插件名 的套娃目录。
- ZIP 方式失去版本控制能力，不适合长期维护。
跑通第一个工作流
最小测试流程
1. 启动 ComfyUI 并打开 http://127.0.0.1:8188。
2. 加载官方默认文生图模板。
3. 确认 Checkpoint Loader 能看到模型。
4. 输入简单提示词，例如 “a cute cat, studio lighting”。
5. 分辨率先用 512×512 或 768×768，采样步数先用 20。
6. 点击 Queue Prompt，等待出图。
第一次出图失败怎么办
- 看控制台最后 20 行，不要只看浏览器页面。
- 确认模型文件没有放错目录。
- 确认工作流缺失节点已经安装。
- 确认显卡驱动正常，NVIDIA 用户执行 nvidia-smi。
- 降低分辨率和批量，排除显存不足。
常见问题排查
问题 1：Torch not compiled with CUDA enabled
含义：当前环境装的是 CPU 版 PyTorch，或者 CUDA 对应的 PyTorch 包没有装对。
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio –extra-index-url https://download.pytorch.org/whl/cu130
问题 2：CUDA out of memory
- 把分辨率从 1024×1024 降到 768×768 或 512×768。
- batch size 改成 1。
- 关闭不必要的 ControlNet、放大、修复脸节点。
- 尝试低显存启动参数或更轻量模型。
问题 3：Missing custom nodes
- 使用 Manager 的 Install Missing Custom Nodes。
- 如果 Manager 找不到，去工作流作者页面查看依赖节点清单。
- 安装后一定要重启 ComfyUI。
问题 4：Import failed
- 检查插件目录是否套娃。正确结构是 custom_nodes/插件名/__init__.py。
- 进入插件目录安装 requirements.txt。
- 确认插件支持你的系统和 Python 版本。
- 如果多个插件依赖冲突，逐个禁用排查。
问题 5：浏览器打不开 8188
- 先确认控制台是否显示 http://127.0.0.1:8188。
- 检查端口是否被占用。
- 服务器远程访问时不要直接暴露公网，优先 SSH 隧道或反向代理加鉴权。
python main.py –listen 0.0.0.0 –port 8188
提示：–listen 会让服务监听外部地址。只建议在可信局域网、VPN、SSH 隧道或受保护的服务器环境下使用。
维护、更新与备份
建议备份的内容
- ComfyUI/custom_nodes：插件与自定义节点。
- ComfyUI/user 或 workflow 保存目录：你的工作流 JSON。
- extra_model_paths.yaml：模型复用配置。
- models 目录：如果模型不在独立模型盘，也要备份关键模型。
什么时候不要更新
- 正在做客户项目或批量出图时。
- 核心工作流依赖很多插件且没有备份时。
- 刚刚配置好复杂环境，还没有记录安装命令时。
推荐维护习惯
- 安装一个插件后，立刻重启并测试，不要一次装十几个。
- 每次改动环境前先导出或复制工作流。
- 重要工作流旁边写一个依赖说明：模型、插件、版本、输入输出。
- 把模型和工作流分开管理，避免更新软件时误删模型。
FAQ
ComfyUI 和 Stable Diffusion WebUI 有什么区别？
Stable Diffusion WebUI 更像表单式操作界面，适合快速输入提示词出图；ComfyUI 是节点式工作流工具，更适合复杂流程、模型组合、批量复用和可视化调试。
没有 NVIDIA 显卡能用 ComfyUI 吗？
可以，但 CPU 会很慢。AMD、Intel、Apple Silicon 也有路线，但插件兼容性和性能体验通常不如 NVIDIA CUDA 生态稳定。
第一次安装应该选 Desktop 还是 Portable？
Windows 新手都可以。想像普通软件一样安装，选 Desktop；想解压即用、方便迁移和备份，选 Portable。
插件装得越多越好吗？
不是。插件越多，依赖冲突和启动失败概率越高。建议按工作流需要安装，跑通一个装一个。
为什么别人发的工作流打不开？
通常是缺少自定义节点、模型路径不一致，或者模型文件版本不同。先用 Manager 安装缺失节点，再检查模型目录。
ComfyUI Manager 必装吗？
不是必装，但强烈建议新手安装。它能显著降低插件安装、更新和缺失节点排查难度。
模型文件可以放移动硬盘吗？
可以，但速度和稳定性取决于硬盘和接口。长期使用建议放 SSD，并用 extra_model_paths.yaml 统一管理。
ComfyUI 可以做商业图吗？
工具本身不直接决定商用权。是否可商用要看使用的模型、LoRA、素材和平台授权条款。
官方参考来源
| 来源 | 链接 |
| ComfyUI 官方 Windows Desktop 文档 | https://docs.comfy.org/installation/desktop/windows |
| ComfyUI 官方 Windows Portable 文档 | https://docs.comfy.org/installation/comfyui_portable_windows |
| ComfyUI 官方 macOS Desktop 文档 | https://docs.comfy.org/installation/desktop/macos |
| ComfyUI 官方 Linux Desktop 文档 | https://docs.comfy.org/installation/desktop/linux |
| ComfyUI 官方 GitHub 仓库 / README | https://github.com/Comfy-Org/ComfyUI |
| ComfyUI Manager 安装文档 | https://docs.comfy.org/manager/install |
| ComfyUI 自定义节点安装文档 | https://docs.comfy.org/installation/install_custom_node |
| PyTorch 官方网站 | https://pytorch.org/ |
| NVIDIA CUDA Toolkit 下载页 | https://developer.nvidia.com/cuda-downloads |
| Git for Windows 官方下载页 | https://git-scm.com/install/windows |
| Python 官方下载页 | https://www.python.org/downloads/ |
