现在做 AI 绘画本地部署绕不开两个工具一个是 Stable Diffusion WebUI另一个就是 ComfyUI。如果你关注开源社区和自定义工作流ComfyUI 应该是目前热度最高的项目之一它由 Comfy-Org 组织维护开发核心思路是把图像生成过程拆成一张张可拖拽、可连线、可复用的节点图。和 WebUI 那种“填表单式”的操作不同ComfyUI 更接近一个可视化编程工具所有模型加载、采样、VAE 解码、后处理步骤都能看得见、改得动。这篇文章不会只讲概念而是直接带你走完一条完整的本地部署链路从环境准备、启动服务到跑通文生图和图生图再到安装插件、加载视频生成类工作流最后用 HTTP API 完成批量任务。如果你正好在考虑本机部署 ComfyUI或者想把 ComfyUI 接进自己的工具链、自动化流程里这篇可以直接收藏备用。先给一个总览。ComfyUI 的部署方式目前主要三条路线官方 ComfyUI Desktop 一键安装、社区整合包、以及源码安装。源码安装最灵活适合需要二次开发和 API 集成的用户一键包适合想快速出图、不想折腾环境的人。无论哪条路线核心能力都围绕节点式工作流、模型管理、自定义插件和 HTTP API 展开。1. 核心能力速览能力项说明项目类型开源节点式 AI 图像生成工作流引擎支持本地部署与 API 集成开源维护方Comfy-Org 组织GitHub 仓库公开主要功能文生图、图生图、局部重绘、ControlNet、LoRA、VAE、自定义节点并可扩展视频生成工作流工作流方式可视化节点图节点可自由连线、组合、保存复用模型支持覆盖社区主流 Stable Diffusion 系列模型并可通过自定义节点扩展视频等模型推荐硬件优先 NVIDIA 显卡显存越高越好具体阈值需按模型和分辨率实测启动方式命令行启动 / 官方桌面一键包 / 社区整合包默认端口8188可在启动参数中修改API 能力内置 HTTP API可提交工作流、查询状态、获取输出图片批量任务可通过 API 或工作流队列实现批量生成需要自行设计轮询与重试逻辑插件生态支持大量第三方自定义节点可通过 ComfyUI Manager 管理适合场景本地绘画创作、工作流自动化、插件开发、模型效果对比、视频生成实验这里要提醒一句显存占用、生成速度这类数字不同显卡、不同模型、不同分辨率差异很大没有固定的“万能参数”。最稳妥的做法是拿到自己的机器上跑一次默认工作流用nvidia-smi观察实际显存占用再决定要不要调低分辨率或换低显存模式。2. 适用场景与使用边界ComfyUI 适合几类人绘画创作者需要精确控制生成流程比如多模型对比、特定采样器参数、局部重绘区域。自动化工具开发者接 API 批量出图把 ComfyUI 当作图像生成后端服务。AI 工作流研究者拆解别人的 workflow JSON理解每一步的作用再做自己的组合。视频生成实验玩家ComfyUI 社区已经有大量视频生成相关节点Wan 等视频模型的工作流也经常在社区分享。不适合的场景也要说清楚完全零基础、只想一键出图ComfyUI 默认界面比较复杂新手更建议从 WebUI 或整合包自带示例入手。需要高速稳定线上服务ComfyUI 本身没有内置用户鉴权、多租户和任务配额管理直接公网暴露会面临安全风险。低配置电脑跑高分辨率视频视频生成对显存和内存的压力远大于静态图片不要指望 4G 显存能流畅跑长视频。合规使用是必须强调的。ComfyUI 本身是工具但生成内容需要你自己承担责任。涉及真实人物肖像、他人作品、版权图片、品牌元素等内容时必须确认有合法授权。人脸生成、声音克隆、视频换脸类节点尤其要注意不要用于伪造身份、诈骗或损害他人权益。商用之前也要检查输出内容是否包含可识别的真实人物、是否侵犯第三方版权。3. 环境准备与前置条件建议先确认下面几项再开始部署。3.1 操作系统ComfyUI 官方支持 Windows、Linux、macOS。Windows 10/11 是社区最常见的运行环境Linux 主要用于服务器和自动部署macOS 也能跑但模型生态和性能通常不如 NVIDIA 显卡环境。3.2 Python 与 Git源码安装需要 Python 环境。不同版本对 Python 版本要求有差异更稳妥的判断是使用 Python 3.10 或 3.11具体以项目 README 为准。Git 用于拉取仓库代码Windows 下安装 Git for Windows 即可。3.3 显卡驱动与 CUDANVIDIA 显卡用户在安装 PyTorch 时一般会顺带安装对应 CUDA 运行库。建议先用下面的命令确认驱动状态nvidia-smi能看到显卡型号和驱动版本就可以。如果nvidia-smi不存在需要先安装显卡驱动。至于具体显卡型号支持以 PyTorch 官方说明为准不同版本支持范围不同。3.4 磁盘空间ComfyUI 程序本身不大但模型文件很占空间。一个基础 Stable Diffusion 模型 checkpoint 通常是 2GB 到 7GB视频模型可能更大。建议预留 20GB 以上磁盘空间如果打算大量测试模型直接预留 100GB 也不夸张。3.5 端口检查ComfyUI 默认监听 8188 端口。启动前可以先检查端口是否被占用# Windows netstat -ano | findstr 8188 # Linux / macOS lsof -i :8188如果端口被占用后面启动命令可以加--port参数修改。4. 安装部署与启动方式4.1 方案一源码安装推荐可二次开发源码安装是最灵活的方式步骤清晰方便后续更新和调试。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启动后浏览器访问http://127.0.0.1:8188看到默认工作流页面说明安装成功。如果启动过程中提示缺依赖用pip install -r requirements.txt重新装一遍即可。4.2 方案二官方 ComfyUI Desktop 一键包官方提供的桌面版安装包适合不想接触命令行的用户。下载安装后打开程序即可启动。它的优势是自带环境隔离不污染系统 Python缺点是更新节奏跟着官方桌面版走想及时测试新功能还是需要回到源码安装。4.3 方案三社区整合包很多社区维护者会发布整合包比如“秋叶 ComfyUI 整合包”这类一键包。整合包通常会预置常用模型、插件和汉化界面适合快速使用。但要注意几点选择可信来源防止下载到捆绑软件整合包版本可能滞后遇到问题优先看作者发布的说明不要用它替代正式的项目追踪工作流和模型文件要定期备份。4.4 模型文件放置ComfyUI 的模型目录结构如下ComfyUI/ ├── models/ │ ├── checkpoints/ # 大模型如 SD1.5、SDXL、Flux │ ├── loras/ # LoRA 模型 │ ├── vae/ # VAE 模型 │ ├── controlnet/ # ControlNet 模型 │ └── ... ├── input/ # 图生图、局部重绘输入图片 ├── output/ # 生成结果默认输出目录 └── custom_nodes/ # 自定义插件节点模型下载后按类型放到对应目录。加载模型时如果下拉列表为空先检查路径是否正确再点击界面上的“刷新”按钮。4.5 自定义节点与 ComfyUI ManagerComfyUI 的插件机制在custom_nodes目录。最方便的插件管理工具是 ComfyUI Manager它可以在界面里搜索、安装、更新节点。安装方式cd custom_nodes git clone https://github.com/ltdrdata/ComfyUI-Manager.git重启 ComfyUI 后界面会多出 Manager 入口。建议新装的节点暂时不要一次装太多容易产生依赖冲突。装完插件后如果启动报错优先看日志里缺少哪个 Python 包手动安装即可。5. 功能测试与效果验证5.1 文生图测试测试目的确认基础工作流能跑通。操作步骤浏览器打开http://127.0.0.1:8188。默认工作流就是文生图包含Load Checkpoint、CLIP Text Encode、KSampler、VAE Decode、Save Image等关键节点。在Load Checkpoint节点选择已放置的模型。在正向提示词节点输入测试文本例如a cat sitting on a windowsill, soft light, detailed fur设置合适的宽度和高度例如 512x512 或 768x512步数先设 20。点击Queue Prompt。预期结果任务队列出现进度日志输出生成信息output目录生成 PNG 图片。判断标准图片能够正常打开提示词内容体现明显界面没有红色报错节点。失败排查如果提示缺少模型检查models/checkpoints路径如果显示 CUDA 错误确认显卡驱动和 PyTorch 的 CUDA 版本是否匹配。5.2 图生图测试测试目的验证输入图片参与重绘的能力。操作步骤将测试图片放到input目录。添加Load Image节点选择测试图片。把Load Image输出的IMAGE连接到采样器替换原来的空 Latent。调整denoise参数0.3 到 0.6 比较适合轻度重绘。点击Queue Prompt。预期结果输出图片保留原图构图但细节和风格按提示词变化。失败排查如果图片路径报错检查文件名是否包含中文或空格如果出现尺寸不匹配将图片尺寸对齐到采样器输入要求。5.3 局部重绘测试测试目的只修改图片的指定区域。操作步骤使用Load Image with Mask节点加载图片。在图片上涂抹需要重绘的区域。将 Mask 输出连接到采样器的mask输入。填写新的描述词设置合适的denoise执行。预期结果只有遮罩区域发生变化其余区域保持原样。5.4 ControlNet 测试测试目的让生成结果严格跟随姿态、线稿或深度图。操作步骤下载对应 ControlNet 模型放到models/controlnet。在默认工作流中加入ControlNet Loader和ControlNet Apply节点。加载控制图片设置合适的strength一般 0.5 到 0.8 起步。执行生成。预期结果生成结果在构图、姿态或结构上明显受控制图片影响。失败排查ControlNet 模型和主模型不匹配时会出现效果不明显或报错建议先查模型类型说明。5.5 插件安装与视频生成工作流测试ComfyUI 社区这几年最热的方向之一是视频生成。像 Wan 这类视频模型已经有人放出 ComfyUI 工作流你可以把 workflow JSON 直接拖进 ComfyUI 界面加载。不过视频生成对显存和内存压力很大第一次测试建议把分辨率调小、帧数调少先验证链路是否通。操作步骤通过 ComfyUI Manager 搜索并安装视频生成相关节点。从社区获取对应工作流 JSON 文件。将工作流 JSON 拖入浏览器窗口。检查缺失节点或缺失模型按提示补齐。设置小分辨率、少帧数执行生成。预期结果输出视频文件能看到明显动态效果。失败排查节点变红说明模型或依赖缺失中途显存不足会直接中断需要降低分辨率、减少帧数或者换低显存启动模式。6. 接口 API 与批量任务ComfyUI 的价值不只是可视化操作它还内置了一套 HTTP API可以把工作流提交、查询、结果获取全部程序化。这意味着你能把 ComfyUI 当成一个独立的图像生成后端服务来用。6.1 API 地址与核心接口启动 ComfyUI 后API 服务同时监听在 8188 端口。常用的接口有接口作用POST /prompt提交工作流任务GET /history/{prompt_id}查询任务状态和输出信息POST /queue管理任务队列GET /view查看或下载输出图片WebSocket /ws接收任务进度和日志6.2 工作流 API 格式说明ComfyUI 界面里看到的工作流是 UI 格式直接提交 API 需要转换成 API 格式。可以在界面右侧菜单中找到“保存API 格式”选项导出的 JSON 可以直接作为POST /prompt的prompt参数。6.3 Python 调用示例下面是一个通用模板实际使用时需要替换为你导出的工作流 JSON 和图片文件名。import json import time import requests # ComfyUI 服务地址 COMFYUI_URL http://127.0.0.1:8188 # 将导出的 API 格式工作流 JSON 放到 dict 中 workflow { 3: { class_type: KSampler, inputs: { seed: 42, steps: 20, cfg: 7.0, sampler_name: euler, scheduler: normal, denoise: 1.0, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0] } } # 其他节点同理 } def submit_prompt(workflow): response requests.post( f{COMFYUI_URL}/prompt, json{prompt: workflow}, timeout30 ) response.raise_for_status() return response.json() def wait_for_complete(prompt_id, timeout300): start time.time() while time.time() - start timeout: resp requests.get( f{COMFYUI_URL}/history/{prompt_id}, timeout30 ) data resp.json() if prompt_id in data: return data[prompt_id] time.sleep(2) raise TimeoutError(task timeout) # 提交任务 result submit_prompt(workflow) prompt_id result.get(prompt_id) print(prompt_id:, prompt_id) # 等待完成 history wait_for_complete(prompt_id) print(outputs:, history.get(outputs))6.4 curl 调用示例如果你只是快速测试接口是否可用用 curl 也可以curl -X POST http://127.0.0.1:8188/prompt \ -H Content-Type: application/json \ -d {prompt: {3: {class_type: KSampler, inputs: {}}}}注意这个示例里的工作流节点不完整实际调用前要把 JSON 替换成完整工作流。6.5 批量任务设计批量任务的关键是使用循环替换工作流里的seed、提示词或输入图片路径。每次提交后拿到prompt_id利用history接口轮询状态。控制并发数量不要一次性提交太多任务容易把显存打满。为每个任务写日志记录prompt_id、参数、开始时间、结束时间、是否成功。失败任务要有重试机制建议指数退避而不是固定间隔重试。一个简单原则先串行跑通 3 到 5 个任务再考虑并发。批量跑的时候任务队列本身在 ComfyUI 内部是串行执行的并发提交多任务并不是真正的并行只是排队执行。6.6 ComfyUI 与 LLM 是否必须在同一台电脑很多人问“ComfyUI 和 LLM 必须在同一台电脑上吗”。答案是不需要。ComfyUI 提供的是 HTTP API只要网络能通任何调用方都可以远程提交任务。你可以在一台显卡机器上跑 ComfyUI在另一台机器上跑业务服务两者通过接口通信即可。唯一要注意的是默认监听地址是127.0.0.1同一台机器访问没问题跨机器调用需要修改监听地址但不要直接暴露到公网建议放在内网或加一层网关鉴权。7. 资源占用与性能观察7.1 如何观察显存占用生成任务时打开另一个终端运行nvidia-smi -l 2每隔 2 秒刷新一次可以看到进程对应的显存占用和 GPU 利用率。也可以打开任务管理器在性能标签页看 GPU 显存和利用率。无论哪种方式实际数字都取决于你加载的模型、分辨率和批次数建议自己跑 2 到 3 组参数对比。7.2 影响性能的关键参数分辨率分辨率提升后显存占用和耗时都会显著增长。采样步数步数影响速度但对显存影响相对小。批次大小batch_size设为 2 或更大显存占用成倍增加。模型类型SDXL 比 SD1.5 更吃显存Flux 和视频模型压力更大。ControlNet 和 LoRA额外模型加载会占用额外的显存空间。7.3 降低显存的通用手段ComfyUI 启动时提供了一些低显存选项# 低显存模式 python main.py --lowvram # 极低显存模式 python main.py --novram # CPU 推理模式 python main.py --cpu注意--cpu模式速度会很慢适合功能验证不适合日常生成。此外降低分辨率、减少步数、使用低精度模型文件如 FP16、FP8 量化版本也能降低显存压力。这些具体收益需要按本机情况测试不能一概而论。7.4 多显卡支持情况热词里有人提到“ComfyUI 双卡”。这里要分开说ComfyUI 默认会把模型加载到当前可见的一张显卡上并不会自动做多卡并行。跨多卡运行通常需要特定节点或手动指定设备属于进阶玩法。如果你只是单卡用户不用关心这个如果是双卡机器建议先跑通单卡再研究多卡方案。7.5 端口冲突与进程残留如果访问不到 8188 页面可能是启动失败也可能是端口被占。先用netstat检查端口再用ps或任务管理器结束残留 Python 进程然后重新启动。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未启动查看终端日志和端口占用更换端口或重启服务模型下拉列表为空模型文件路径不对检查 models 目录放置模型后点击刷新节点变红报错自定义节点缺失或依赖未装查看终端报错安装依赖或更新节点生成时报 CUDA 错误驱动版本或 PyTorch 版本不匹配nvidia-smi查看驱动更新驱动重新安装 PyTorch 匹配版本显存不足中断分辨率或 batch 过大观察 nvidia-smi降低分辨率、减少批次、开低显存模式API 提交返回 400工作流 JSON 不是 API 格式检查导入导出的格式从 UI 导出 API 格式 JSON批量任务卡住队列中任务异常查看 history 和日志清空队列隔离失败任务重跑Windows Git 提示 unable to set system configGit 安装或全局配置异常查看报错信息按提示检查 Git 配置重设全局配置或重装 Git输出图片质量不稳定参数设置不合理或模型不适合对比不同 seed 和步数固定 seed 排查按模型建议设置参数这里单独说下 Windows 上 Git 提示unable to set system config diff.astextplain.textconv的问题。这是 Windows 下 Git 安装环境配置异常导致的通常出现在使用控制台命令时不是 ComfyUI 本身的 bug。解决办法是先排查 Git 全局配置必要时重新配置 Git 的 textconv 设置。9. 最佳实践与使用建议9.1 先跑最小可运行配置第一次使用不要直接加载完整的大工作流先跑通一个包含最基础节点的文生图工作流确认模型加载、采样、保存链路正常再逐步加入 LoRA、ControlNet、视频生成节点。9.2 目录分级管理建议把模型、工作流、输入、输出分目录管理。模型文件按类型放好工作流 JSON 可以统一放到一个备份目录输入和输出按日期或项目分子目录。批量任务尤其重要避免几十个输出文件堆在一起无法区分。9.3 保留稳定的工作流版本同一个工作流改着改着就坏掉是常见问题。建议在确认某个工作流能稳定出图后保存一份带版本号和参数备注的 JSON例如portrait_v1_2025.json。这样即使后面改坏了也能快速回退。9.4 批量任务加日志和重试批量任务不是简单提交就完了。要记录每个任务的prompt_id、提交参数、输出文件名、状态码、耗时。失败任务要能单独重跑不要因为一个失败任务导致整个队列清空。9.5 接口服务注意访问范围如果只在本机使用保持默认监听127.0.0.1。如果需要让局域网其他机器访问可以修改监听地址但建议只是内网使用。任何暴露到公网的服务都要考虑安全问题ComfyUI 默认没有用户认证机制不要直接放在公网上。9.6 版权与授权合规生成图片、视频之前先确认素材来源。涉及真实人脸、品牌 LOGO、他人作品、商业素材时必须确认授权范围。涉及声音克隆、换脸、数字人相关节点时更要严格限制使用边界不能用于虚假信息制作和传播。10. 总结与下一步ComfyUI 最值得尝试的点有两个一是节点式工作流的透明度和复用性二是 API 接口带来的自动化潜力。对一个 AI 绘画工具来说能把每一步生成逻辑拆开看、改、保存这件事本身就比“填表单点生成”高出一个维度。建议你第一个验证的功能就是文生图。模型放好、默认工作流跑通、看到输出目录出现图片这条主线通了后面的图生图、ControlNet、视频生成都是一样的思路。最容易踩的坑集中在三处模型路径放错、依赖版本不匹配、端口被占用。这三个问题在上面排查表里都有对应解法。接下来可以继续往三个方向扩展一是把常用风格制作成自己的工作流模板二是用 API 把 ComfyUI 接入现有业务比如自动配图、批量素材生成三是研究 ControlNet 和视频生成工作流探索更复杂的图像控制能力。如果你需要批量生成现在已经有了完整的接口调用思路剩下的就是写队列和日志了。建议收藏备用尤其是部署和排查部分实际使用时会反复用到。