如果你已经在 Stable Diffusion WebUI 里画了一段时间图大概率会听到两种声音一种是“ComfyUI 太复杂了全是节点看不懂”另一种是“用过 ComfyUI 就回不去了”。这两种说法都有道理但也都没有说到点子上。ComfyUI 真正改变的是“怎么组织一次 AI 生图”这件事。WebUI 把生图封装成“填表单”你看到的是一张页面、几个输入框ComfyUI 把生图拆成“画流程图”每一步数据从哪里来、经过什么处理、输出到哪里去全部摊开在画布上。它的学习曲线确实比 WebUI 陡可一旦你理解了节点和数据流这套逻辑会发现它带来的不是多一个工具而是多了一种控制 AI 生成过程的自由度。这篇文章会用一篇完整的技术长文把 ComfyUI 从核心原理讲到本地部署、从最简单的文生图工作流讲到 API 对接、从常见报错讲到工程化建议。读完你可以做到三件事第一在自己的电脑上把 ComfyUI 跑起来第二能看懂并调通最基础的工作流第三碰到启动失败、显存不足、节点报错这类问题知道从哪里排查。1. ComfyUI 到底是什么为什么值得学ComfyUI 是一个基于节点图Node Graph的 Stable Diffusion 图形界面工具由 comfyanonymous 发起现在由 Comfy-Org 组织维护和迭代。它当然不是第一个也不是唯一一个把 Stable Diffusion 包装成可视化工具的项目但它把“可编程性”做到了一个很突出的位置。传统 WebUI 的思路是“隐藏复杂度”。用户只需要选择模型、输入提示词、设置采样步数、点击生成底层的 UNet、CLIP、VAE 都是封装好的。对新手友好但如果你想精细控制生成过程就会觉得处处受限我想在采样中途换一个 LoRA我想对不同的区域使用不同的提示词我想把中间 latent 拿出来再处理一次WebUI 做不到或者只能用插件曲折实现。ComfyUI 的思路反过来它把 Stable Diffusion 的推理过程拆成一个个节点然后让用户自己连线。一图胜千言加载模型是一个节点正面提示词编码是一个节点负面提示词编码是一个节点采样器是一个节点VAE 解码是一个节点保存图片是一个节点。节点和节点之间通过“数据线”连接。这条线传输的可能是文本向量conditioning、图像张量IMAGE、潜空间张量LATENT或普通数值。你连的线不同生成流程就不同。这意味着 ComfyUI 拥有极强的灵活性。它不只是“Stable Diffusion 的另一个前端”它本质上是一个可视化的推理流程编排引擎。加上 ComfyUI 原生支持多模型加载、队列调度、API 模式它正在从个人画图工具演变为 AIGC 应用的后端推理服务。对技术开发者和重度用户来说这个价值是明确的WebUI 让你“用” AIComfyUI 让你“编排” AI。2. ComfyUI 的核心概念与原理解析2.1 节点Node与数据流Data FlowComfyUI 里每次生图在底层都是一张有向无环图。图中每个节点是一段程序节点接收输入、执行运算、产生输出。数据按你画好的连线方向流动。例如一个经典的“加载检查点 → 文本编码 → 采样 → 解码 → 保存”流程数据流就像一条生产流水线原料模型进场、配方文本注入、机器混合搅拌、烤箱烘烤、包装输出。为什么要理解这个因为 ComfyUI 的“底层其实是一张图”这个事实会直接影响你排查问题的思路。如果出图全黑你要顺着数据流去查是 VAE 没接对还是 latent 在采样前就已经坏了如果是生成图片很慢你要看瓶颈在哪个节点是加载模型耗时还是采样步数太多这和 WebUI“打开页面点按钮”的思维方式完全不同更像是调试一个管道系统。2.2 检查点Checkpoint与三大组件Stable Diffusion 的模型文件比如常见的sd_xl_base_1.0.safetensors通常是一个打包好的“检查点”。它内部包含三个部分UNet / DiT负责去噪的核心网络决定图像的内容和构图CLIP负责把文本变成条件向量让模型“听懂”你的提示词VAE负责在像素空间和潜空间之间转换解决图像的色彩和细节还原问题。所以加载一个 Checkpoint 的节点会有多个输出口MODEL给采样器用、CLIP给文本编码用、VAE给解码用。新手最常见的错误就是只连了 MODEL忘了把 VAE 接到最后的解码节点结果生成出来的图是灰蒙蒙的“潜空间预览”。这里也引出一个工程判断ComfyUI 之所以能比 WebUI 更省显存一个重要原因是你可以在图里自由选择“只加载需要的部分”。如果你只是测试采样效果、不需要最终输出图片那就没必要把 VAE 加载进来。控制权回到了用户手里。2.3 潜空间Latent Space与采样器Stable Diffusion 并不直接在像素空间里生成图片而是先在 VAE 压缩后的潜空间里工作。图片经过 VAE 编码后尺寸会从H x W x 3变成H/8 x W/8 x 4的小张量。采样器KSampler在这个低维空间里逐步去噪最后再用 VAE 解码回像素图。理解潜空间是理解 ComfyUI 的关键。很多节点名字里带 “Latent”比如Empty Latent Image、VAE Encode、VAE Decode它们操作的都是这块“压缩后的画布”。采样器节点上的参数——seed、steps、cfg、sampler_name、scheduler就控制了去噪过程。参数通俗理解太长不看版seed随机数种子固定后同一配置下图片可复现steps去噪步数越大越精细但耗时越长cfg提示词引导强度越大越贴近提示词过大容易过曝sampler_name采样器算法euler / dpmpp_2m / unipc 等scheduler噪声调度方式normal / karras / exponential 等对新手来说这些参数先不用全懂记住一个经验值SD1.5 模型常用 20 步、cfg 7 左右SDXL 可以用 25 到 30 步一些新模型如 SD3.5 或 Flux 对 cfg 的要求差异很大最好查阅模型的推荐参数。2.4 工作流Workflow的两种形态ComfyUI 里“工作流”这个词有歧义。一种理解是你在画布上看到的节点和连线保存为.json文件后可以分享另一种理解是 ComfyUI 内部运行时使用的 API 格式同样是 JSON但结构不同专供 HTTP API 调用。你从别人那里下载的 workflow JSON打开后有两种加载方式直接拖进画布加载UI 格式或者通过 API 提交API 格式。两者字段不一样不能混用。这点放在后面 API 章节会具体讲。3. 环境准备与安装3.1 硬件与操作系统要求ComfyUI 对硬件的需求和 Stable Diffusion 其他方案的底线一致必须有 NVIDIA 显卡显存建议 4GB 起步。SD1.5 系列在 4GB 显卡上可以勉强跑SDXL 建议 8GB 以上SD3.5、Flux 等更大模型则建议 16GB 或 24GB 以上。纯 CPU 模式可以启动但基本只能验证流程不适合实际生成。操作系统上Windows 10/11 使用最多Linux 更适合部署长期服务。macOS 也能运行但大部分模型基于 CUDA 优化Apple Silicon 上的性能与兼容性会打折扣。3.2 两种安装路径整合包还是手动安装很多中文用户第一次接触 ComfyUI是从“秋叶一键整合包”开始的。整合包确实把 Python 环境、PyTorch、ComfyUI 本体、常用插件都打包好了解压就能用。如果你只是想快速体验这是成本最低的路径。但从工程角度看整合包也带来两个问题一是依赖锁定比较死后续想升级 PyTorch 或 ComfyUI 版本可能遇到兼容性问题二是你不太清楚环境里装了什么出了问题不好定位。这里给一个明确建议如果你是新手、只有一块消费级显卡、主要目的是画画图先用整合包跑通如果你打算做二次开发、在服务器上部署、或者长期维护一套自定义节点库建议用 git 手动安装把每个组件掌握在自己手里。3.3 手动安装步骤以下以 Windows 为例Linux 基本同理。第一步安装 Git安装 Git 是为了拉取 ComfyUI 源码和后续更新。这里有个容易踩的坑某些 Windows 环境在安装 Git 之后使用命令行会提示warning: unable to set system config diff.astextplain.textconv这不是 ComfyUI 的问题是 Git 在 Windows 上配置 textconv 时的小问题。不影响使用但如果你看着不舒服可以用下面的命令关闭相关警告git config --global core.autocrlf false git config --global diff.astextplain.textconv false第二步克隆 ComfyUI 源码git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI第三步创建虚拟环境并安装依赖强烈建议使用 venv 或 conda不要直接安装到系统 Python否则后面插件依赖会打架。python -m venv venv venv\Scripts\activate pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 pip install -r requirements.txtCUDA 版本号请根据你自己的显卡驱动选择可以使用nvidia-smi查看驱动支持的 CUDA 版本。如果显卡驱动较新也可以直接安装默认的 torch 版本。第四步放置模型文件创建模型目录并放入模型文件。ComfyUI 默认从models/checkpoints读取检查点文件从models/loras读取 LoRA 文件ComfyUI/ ├─ models/ │ ├─ checkpoints/ # 放 sd_xl_base_1.0.safetensors 等 │ ├─ loras/ # 放 LoRA 文件 │ ├─ vae/ # 放单独的 VAE可选 │ └─ unet/ # 放新的单组件模型SD3.5、Flux 等常用 ├─ custom_nodes/ # 插件目录 ├─ output/ # 生成图片保存目录 └─ main.py第五步启动python main.py看到类似下面的输出说明启动成功Starting server To see the GUI go to: http://127.0.0.1:8188浏览器打开http://127.0.0.1:8188即可进入工作台。3.4 常用启动参数ComfyUI 的命令行参数里有几个在实际使用中非常常用参数作用--listen 0.0.0.0允许局域网访问做服务部署时必用--port 8188修改端口--cuda-device 0多卡机器指定使用哪块 GPU--highvram/--lowvram显存策略一般自动即可--disable-xformers关闭 xformers 加速某些模型下需要关闭--output-directory指定输出目录多卡用户注意ComfyUI 默认只使用一块显卡。如果你有两块卡想让两块卡同时跑不同任务可以把两个 ComfyUI 实例配置到不同端口和不同--cuda-device而不是指望单个实例自动并行。4. 核心流程拆解搭建第一个文生图工作流4.1 认识工作台界面打开 ComfyUI 后你会看到中间一块巨大的画布画布上默认可能有一个基础文生图工作流。左侧竖排的工具栏可以调出节点右下面板可以配置参数。鼠标拖动画布、滚轮缩放、右键可以搜索节点。如果画布空白可以右键选择New Workflow创建新工作流或者把别人分享的 workflow JSON 文件直接拖进浏览器窗口加载。4.2 最小文生图工作流一个可运行的最小文生图工作流至少需要这些节点Load Checkpoint加载检查点模型CLIP Text Encode (Prompt)编码正面提示词CLIP Text Encode (Prompt)编码负面提示词Empty Latent Image创建空潜空间图像KSampler采样去噪VAE Decode解码潜空间Save Image保存图片。连线关系如下Load Checkpoint ├── MODEL → KSampler.model ├── CLIP → CLIP Text Encode (正面) → conditioning → KSampler.positive ├── CLIP → CLIP Text Encode (负面) → conditioning → KSampler.negative └── VAE → VAE Decode.vae Empty Latent Image → latent → KSampler.latent_image KSampler → latent → VAE Decode.samples VAE Decode → image → Save Image.images在操作上你可以右键选择Add Node → loaders → Load Checkpoint然后依次添加其他节点再用鼠标从节点右侧的输出端口拖线到另一个节点的输入端口。连接正确后端口会变成高亮状态。4.3 参数设置建议在Load Checkpoint节点里选择要使用的模型。如果下拉列表为空说明模型没放对位置检查models/checkpoints目录。Empty Latent Image中的width和height决定生成分辨率。SD1.5 建议 512x512 或 768x768SDXL 建议 1024x1024不要随意填非标准尺寸否则容易出现重复构图或畸变。KSampler中seed建议先随机一个数字生成了满意的图后再固定 seed 用于复现。steps和cfg根据模型推荐设置。需要特别提醒不同模型的推荐参数差异很大SDXL 的 cfg 通常在 5 到 7而 SD3.5 和 Flux 这类新模型的建议参数往往和旧模型完全不同。最稳妥的方法是看模型发布页的说明而不是套用记忆中“圣 20 步、7 cfg”的老经验。4.4 点击生成与保存节点全部连接好之后点击面板右侧的Run或Queue按钮任务会进入队列。你会看到节点上出现进度条右下角显示当前正在运行的节点。生成完成后图片会出现在output目录也可以通过画布上方提示点击查看。保存工作流点击 Workflow 菜单选择Export即可保存为 JSON。这个 JSON 文件就是你以后分享或复用工作流的载体。5. 完整示例与代码实践5.1 示例一以 API 模式启动 ComfyUIComfyUI 天生支持作为后端服务运行。假如你要把它集成到自己的应用里推荐以 API 模式启动python main.py --listen 0.0.0.0 --port 8188这样同一台机器上的其他服务或者局域网里的其他机器都可以通过 HTTP 请求调用 ComfyUI。5.2 示例二通过 HTTP API 提交工作流ComfyUI 提供了一个 HTTP 接口/prompt你只需要把工作流的 API 格式 JSON 提交过去就能触发一个生成任务。下面是一个简化示例。先准备一个 API 格式的 workflow JSON保存为workflow_api.json{ 3: { class_type: KSampler, inputs: { seed: 42, steps: 20, cfg: 7, sampler_name: euler, scheduler: normal, denoise: 1, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0] } }, 4: { class_type: CheckpointLoaderSimple, inputs: { ckpt_name: sd_xl_base_1.0.safetensors } }, 5: { class_type: EmptyLatentImage, inputs: { width: 1024, height: 1024, batch_size: 1 } }, 6: { class_type: CLIPTextEncode, inputs: { text: a beautiful landscape, highly detailed, 8k, clip: [4, 1] } }, 7: { class_type: CLIPTextEncode, inputs: { text: blurry, low quality, ugly, clip: [4, 1] } }, 8: { class_type: VAEDecode, inputs: { samples: [3, 0], vae: [4, 2] } }, 9: { class_type: SaveImage, inputs: { filename_prefix: my_workflow, images: [8, 0] } } }注意API 格式的 JSON 并不包含 UI 布局信息节点坐标所以它只能在/prompt接口使用不能直接拖回画布编辑。如果你需要拖回画布编辑应该保存 UI 格式的 workflow。用 Python 提交这个任务import json import requests with open(workflow_api.json, r, encodingutf-8) as f: workflow json.load(f) resp requests.post( http://127.0.0.1:8188/prompt, json{prompt: workflow, client_id: my-client-001} ) print(resp.json())如果返回的 JSON 里有prompt_id说明任务已经进入队列{prompt_id: f1d2a3b4-..., number: 1, node_errors: {}}5.3 示例三轮询任务结果并下载图片通过/history/{prompt_id}可以查看任务状态history requests.get( fhttp://127.0.0.1:8188/history/{prompt_id} ).json()当任务完成后history中会包含输出图片信息。也可以通过 WebSocket 监听任务完成事件这里给一个简化版import requests import json import time prompt_id f1d2a3b4-... # 替换为实际返回的 prompt_id for _ in range(60): history requests.get( fhttp://127.0.0.1:8188/history/{prompt_id} ).json() if prompt_id in history: outputs history[prompt_id][outputs] for node_id, output in outputs.items(): for image in output.get(images, []): img_url ( fhttp://127.0.0.1:8188/view? ffilename{image[filename]} fsubfolder{image[subfolder]} ftype{image[type]} ) print(图片地址:, img_url) break time.sleep(1)这段代码做了三件事轮询 history 接口、判断任务是否完成、拼接图片访问 URL。在实际项目中你可以把“提交 prompt_id → 轮询 → 拿结果 URL”封装成一个标准接口供上层应用调用。5.4 示例四命令行指定 GPU双卡机器上需要显式指定 GPUpython main.py --cuda-device 0 --port 8188 # 第二个实例 python main.py --cuda-device 1 --port 8189这样两个实例互不干扰。如果是一张卡跑不动大模型想用两张卡做模型并行ComfyUI 默认不自动支持需要借助特定自定义节点或外部方案复杂度较高不建议新手尝试。6. 运行结果与效果验证6.1 如何判断启动成功启动成功后浏览器打开http://127.0.0.1:8188能正常看到画布界面说明 Web 服务正常。接着点击Run如果节点执行没有红色报错并且output目录下生成了.png图片就说明整个流程已经跑通。6.2 生成结果出现之前的几个检查点实际使用中失败往往不是“程序崩溃”而是“结果不对”。这里列出几种典型情况现象可能原因检查哪里生成图片全黑或全灰VAE 解码缺失或模型选择错误检查有没有把 VAE 输出接到 VAEDecode图片构图怪异、文字乱码提示词与模型不匹配或分辨率不符合模型预期换模型推荐分辨率检查提示词每次生成图片完全不同seed 没有固定将 KSampler 的 seed 设为固定值图片整体过曝、颜色失真cfg 参数过高降低 cfg比如从 7 降到 5生成速度极慢采样步数过多或模型过大降低 steps开启 xformers6.3 显存不足的验证与处理当你看到类似CUDA out of memory的报错时首先不要慌。ComfyUI 对显存要求相对友好如果依然爆显存检查优先级是分辨率是不是设得太大batch_size是否大于 1是否同时在后台运行其他占用显存的程序系统是否启用了其他模型或外挂节点驻留显存。如果确认是显存不够可以用--lowvram启动让模型分块加载用一点速度换显存空间。7. 常见问题与排查思路7.1 启动阶段常见问题问题现象可能原因排查方式解决方案启动时提示缺少torchPython 虚拟环境未激活或未安装依赖执行pip list查看是否有 torch激活虚拟环境后重新安装 requirements.txt启动时提示CUDA not availablePyTorch 版本与 CUDA 不匹配执行python -c import torch;print(torch.cuda.is_available())重新安装 CUDA 版 PyTorch浏览器打不开 8188 端口服务未启动或端口被占用查看启动日志使用 netstat -anofindstr 8188 检查端口Git 提示 unable to set system configWindows Git 配置问题这通常是警告不影响使用执行git config --global core.autocrlf false忽略7.2 运行阶段常见问题问题现象可能原因排查方式解决方案节点出现红色错误并中断某一节点的输入格式不匹配点击红色节点查看完整报错信息检查连线和节点输入类型“模型文件不存在”模型没有放到正确目录查看 models/checkpoints 目录内容将模型放入正确目录后刷新页面输出图片全是噪点VAE 未接或 cfg 太小检查工作流 VAE 连线接上 VAE 解码提高 cfg生成结果和原图完全无关如 img2imgdenoise 参数过高检查 KSampler 的 denoiseimg2img 时 denoise 建议 0.4 到 0.7CPU 占用拉满但 GPU 不动节点上没有可用的 CUDA 设备查看启动日志确认设备确认 PyTorch 识别 CUDA或检查--cuda-device参数插件安装后不生效插件目录加载失败或依赖缺失查看启动日志中自定义节点加载部分手动安装插件依赖或删除冲突插件7.3 一个很常见的误解ComfyUI 与 LLM 必须同一台电脑吗不少人在做 AIGC 应用时会同时用到 ComfyUI 和 LLM 服务然后问“这两个必须在同一台电脑上吗”。答案是不一定。ComfyUI 通过 HTTP API 对外提供服务任何能访问该端口的客户端都可以调用。如果你有一个 LLM 负责生成提示词ComfyUI 负责出图完全可以让它们跑在不同的机器上。但从工程角度要注意两点一是跨机器调用延迟明显增加如果你的场景需要实时性强尽量部署在同一内网二是如果 LLM 需要通过读取生成图片做下一步决策图片传输会有额外的 I/O 开销。更常规的部署方式是同一台 GPU 服务器上同时跑 ComfyUI 和轻量级 LLM 服务用 127.0.0.1 内网调用避免网络瓶颈。7.4 版本更新的注意点ComfyUI 迭代很快社区中常见的热词如v0.33.1 更新、SD3.5 workflow说明版本变化会带来新的模型支持和节点接口调整。升级前最好先备份当前可用的custom_nodes和 workflow JSON。部分自定义节点在 ComfyUI 升级后可能因为 API 变化而失效升级后第一件事不是画图而是去启动日志确认所有插件是否正常加载。8. 最佳实践与工程建议8.1 模型与目录管理ComfyUI 的项目目录就是它的“状态”。建议从第一天就做好规划检查点文件放在models/checkpoints不要堆在任意文件夹里下载的 LoRA 文件名保持清晰比如lora_sdxl_pixel_style.safetensors避免以后认不出VAE 文件单独放models/vae方便随时换输出目录定期清理或者使用--output-directory指向独立数据盘防止 C 盘被撑爆。8.2 工作流版本管理工作流 JSON 是文本文件天然适合放进 Git 仓库。建议维护一个自己的工作流仓库只保存 UI 格式和 API 格式两种版本并在 README 里注明需要的模型文件、自定义节点和推荐参数。这样你日后换机器或者和同事协作都不需要重新摸索。8.3 API 调用的工程化封装如果要把 ComfyUI 集成进实际业务切勿在业务代码里直接拼接 workflow JSON。更建议封装成一个独立的 SDKclass ComfyUIClient: def __init__(self, base_url): self.base_url base_url def generate(self, workflow_json, waitTrue): resp requests.post( f{self.base_url}/prompt, json{prompt: workflow_json} ) prompt_id resp.json()[prompt_id] if not wait: return prompt_id return self._wait_and_fetch(prompt_id) def _wait_and_fetch(self, prompt_id, timeout120): deadline time.time() timeout while time.time() deadline: history requests.get( f{self.base_url}/history/{prompt_id} ).json() if prompt_id in history: return history[prompt_id] time.sleep(1) raise TimeoutError(fprompt {prompt_id} timeout)这样做的好处是调用方只关心“提交工作流 → 拿结果”不用关心 ComfyUI 具体接口细节。后续如果你换成其他推理后端只需要改 SDK 内部实现。8.4 安全边界与权限控制把 ComfyUI 暴露到公网需要非常谨慎。ComfyUI 本身默认没有复杂的鉴权机制如果直接--listen 0.0.0.0并暴露公网端口任何知道地址的人都可能提交任务、读取生成图片。在生产环境里必须把 ComfyUI 放在内网由你的后端服务统一对外提供 API并做身份认证和限流。对于个人使用尽量保持只监听127.0.0.1或者通过 SSH 隧道访问远程实例。8.5 性能调优建议优先使用 xformers 或 PyTorch 的 SDPA 注意力加速在显存足够时能明显提速SDXL 及以上模型用 FP16 推理如果显存紧张可以尝试 FP8 版本权重输出大图时可以开启 VAE Tiling减少 VAE 解码时峰值显存批量测试时把 seed 固定便于横向对比不同参数的效果不要迷信“步数越多越好”很多模型 20 到 30 步已经收敛继续加步数只增加耗时。8.6 关于视频生成与扩展工作流社区里很热门的“无限生成视频”“Wan 搭建”“LTX-Video”等工作流本质上都是在基础文生图工作流之上加入时间维度的节点用特定的视频模型替换固定模型在采样过程中叠加运动模块再把连续帧编码为视频。这类工作流对显存和工程化要求更高建议先跑通静态图流程再进入视频方向。视频工作流对自定义节点依赖严重安装前务必查看节点仓库对 ComfyUI 版本的要求。9. 总结与后续学习方向这篇内容从 ComfyUI 的核心原理讲到了本地部署从最小文生图工作流讲到了通过 API 把 ComfyUI 作为后端服务。你如果照着操作应该已经能在一个可用的 ComfyUI 环境里生成自己的第一张图并且知道怎么把生成过程编程化、工程化。接下来的学习路径建议按这个顺序推进先玩熟基础工作流掌握 Checkpoint、KSampler、Latent 的连线关系再尝试替换模型理解 SD1.5、SDXL、SD3.5 之间的参数差异然后进入 ControlNet、LoRA、局部重绘等进阶工作流掌握更精确的图像控制如果你想开发应用重点研究 API 格式的 workflow JSON尝试把 ComfyUI 封装成一个服务对视频生成、无限画布这类话题保持关注但不要跳级等基础工作流已经熟练再碰。ComfyUI 真正难的不是某个节点怎么用而是你愿不愿意把生成过程当成一条可控制的数据流。一旦转过这个弯它带给你的自由度是传统 WebUI 给不了的。建议先把这篇收藏起来安装或排查问题时对照着操作。祝你能顺利跑通自己的第一个工作流。