很多第一次接触 ComfyUI 的人不是被节点式界面吓退的就是被各种报错卡死的。明明下载了整合包也把模型放进去了点击运行却弹出一句“节点在执行过程中发生错误”然后整个流程停在那里只剩下红色错误提示和一堆看不懂的日志。这种挫败感几乎是每一位本地部署玩家的必经之路。我的一个判断是ComfyUI 本地部署的难度从来不在于“安装”本身而在于你把它当成一个普通软件来用却没有理解它背后的工作流思维方式。它和传统 WebUI 类的绘图工具不一样和在线生图网站更不一样。它本质上是一个“可视化图像生成流水线”一旦理解了节点图、数据流、模型目录这三件事你会发现它比想象的简单得多而且上限高得多。这篇文章会从零开始讲清楚为什么要在本地部署 ComfyUI、需要准备什么环境、模型该放哪里、基础文生图工作流怎样跑通最后再到如何用 API 方式做批量出图。内容尽量避开那些“复制一堆代码但不知道什么意思”的教程写法每一段都会解释原因和容易踩坑的地方。1. 本地部署ComfyUI解决什么问题谁最需要1.1 本地部署与在线绘图的核心差异先说底层逻辑。在线生图网站本质上是把图片生成任务提交到云端服务器你获得的是最终图片但控制权非常有限。本地部署 ComfyUI 后模型权重、推理代码、甚至采样参数都掌握在自己手里所有计算都发生在你的电脑上。这意味着三个非常实际的变化第一隐私性。很多设计师或内容创作者会有不便上传到第三方平台的工作素材本地推理不需要把图片上传到任何地方模型推理过程完全离线运行。第二可变成本趋近于零。在线平台通常按生成次数收费本地部署只需要一次性支付硬件和电费成本。对于那些每天生成几百张图做构图探索的人来说两者成本差距会非常明显。第三可扩展性。ComfyUI 的价值不只在于“文生图”它是支持自定义节点的你可以把 ControlNet、LoRA、局部重绘、视频生成模块都组合到同一条流水线里。这种扩展能力是在线平台和传统 WebUI 工具很难给的。1.2 适合与不适合的人群本地部署不是万金油。先说适合的人希望能系统学习 AI 生图原理的开发者。ComfyUI 的节点图很接近扩散模型的真实推理流程跑通一个基础工作流你会自然理解模型编码器、采样器、VAE 解码分别做了什么。有明确批量出图或自动化需求的工程人员。自己部署后可以调用本地 API把生成环节接入流程系统。有一定动手能力愿意折腾环境问题的创作者。再说暂时不适合的人。如果你完全不想接触任何命令行也接受不了版本冲突或模型路径报错那本地部署 ComfyUI 的体验会有点痛苦。这种情况下先使用配置更简单的 WebUI 整合包或者继续使用在线绘图服务或许是更合适的选择。学习工具要讲究性价比不能为了“本地”而本地。1.3 学习 ComfyUI 的核心认识很多教程会一上来就扔出几十个节点的工作流让人误以为 ComfyUI 很复杂。实际上绝大多数复杂工作流都建立在一条基础链路上模型 - 文本条件 - 采样 - 解码 - 输出图片。想明白这一点非常关键。如果你能亲手把这条链路搭出来再去看社区分享的复杂工作流大脑就不会被密密麻麻的连线吓到反而会下意识地把它们拆解成不同的功能块。这也是本文后面实操部分要严格推进的逻辑。2. ComfyUI核心概念与运行原理2.1 节点式工作流到底是什么ComfyUI 的界面里没有传统的“参数表单”而是一块无限画布上面放了各种节点节点之间用连线连接起来。每一个节点代表一个功能单元比如加载模型、编码提示词、执行采样、解码图片、保存图片。连线则代表数据在网络中的流动方向。从一个节点拉出来的每根线都被标记了数据类型。比如 Load Checkpoint 节点会输出 MODEL、CLIP、VAE 三种数据其中 MODEL 是扩散模型主干CLIP 负责文本编码VAE 负责把潜空间数据解码成可见图像。你需要把这些数据接到对应的节点上才能完成一次推理。这和地方画的 WebUI 最大的不同在于WebUI 把整条流程固化成了界面表单你只能在文本框和滑块之间操作ComfyUI 则把流程的控制权完全交给使用者。你可以像拼积木一样自由组合甚至可以创造出一些界面工具中很难实现的高级流程。2.2 模型、VAE与目录管理本地部署 ComfyUI 后你会面对一个 models 目录下面又有多个子目录。新手最容易搞混的就是 checkpoint、vae、lora 这几个文件夹。checkpoints 目录放置“主模型”也叫大模型。这类文件体积通常在 2GB 到 7GB 不等包含文本编码器、扩散模型主体和图像解码能力。常见格式是 safetensors 或 ckpt。loras 目录放置低秩微调模型体积很小通常在几十MB到几百MB。它的作用是给主模型注入特定风格、角色或画风。vae 目录放置独立的 VAE 文件。部分模型作者会把 VAE 打进主模型文件内但也有不少模型没有内置如果生成出来的图像整体发灰、对比度异常就要考虑手动加载 VAE 文件。controlnet、upscale_models、embeddings 等目录则分别服务于姿态控制、图像放大和提示词嵌入。提前理解这些目录的作用后续下载模型时才不会出现“文件明明在但节点里找不到”的情况。很多人刚接触时把 lora 文件放进了 checkpoints 目录加载的时候当然怎么都找不到。2.3 ComfyUI 的几种执行顺序ComfyUI 的执行顺序和普通流程图不完全一样。虽然你在画布上看到节点从左到右排列但前端提交任务时后端会先分析所有节点之间的依赖关系然后按拓扑排序依次执行。例如KSampler 节点依赖 Load Checkpoint 输出的 MODEL 和 CLIP也依赖 Empty Latent Image 输出的空图像张量。后端必须保证这些上游节点先执行完后KSampler 才会运行。因此即使你把节点位置摆得很乱ComfyUI 也能自动找出正确的顺序。新手之所以经常感到困惑是因为多数工作流模板里的排布方式会影响阅读体验但不会影响计算逻辑。这种设计也带来一个很好的调试习惯出现报错时不用看整张图从头到尾只需要定位报错提到的那个节点检查它缺少哪个输入或者它输出的数据格式是否匹配就能快速缩小问题范围。3. 环境准备与硬件条件开始本地部署之前最好先对自己的电脑情况做一个判断。很多安装失败并不是操作问题而是硬件或系统版本不够匹配。3.1 显卡与显存要求AI 生图模型在本地推理时最消耗资源的是显卡显存。显存大小直接决定你能跑多大的模型、多大的图片分辨率以及生成速度。如果是 NVIDIA 显卡建议显存至少 8GB 起步这样运行 SD 1.5 系列模型会相对顺畅也能勉强尝试小分辨率的 SDXL 模型。如果显存容量在 12GB 及以上体验会好很多能比较从容地使用 SDXL 系列并且有空间同时挂载 ControlNet、放大模型等附加模块。AMD 显卡和 Apple Silicon 设备也可以运行 ComfyUI但没有那么省心。Apple Silicon 设备上通常使用 MPS 后端有一些节点或自定义插件可能不支持。纯 CPU 环境虽然也能启动 ComfyUI但一张 512x512 的图可能要跑几分钟实际意义不大不建议作为主要硬件方案。3.2 操作系统与基础软件ComfyUI 是跨平台项目Windows、Linux、macOS 都能运行。不同系统的差异主要在环境配置这一步。Windows 上常见的是通过整合包或 Git 安装Linux 服务器通常用于部署生产环境macOS 则多用于本地创作测试。软件层面需要提前准备 Git 和 Python。Python 版本建议使用较新的 3.10 或 3.11太旧的版本会导致很多第三方依赖无法安装太新的版本有时会出现某些自定义节点兼容问题。安装 Git 后建议顺手配置好用户信息否则后续更新或下载插件时可能出现配置类的提示。如果在 Windows 上使用 NVIDIA 显卡还需要提前安装显卡驱动。可以打开命令行执行如下命令看到显卡信息说明驱动正常nvidia-smi如果提示找不到命令就需要先去安装或更新显卡驱动再考虑后面的部署步骤。3.3 磁盘空间本地生图模型占用的空间比很多人预期的大。一个主模型文件可能就有 2GB 到 7GB再算上 LoRA、ControlNet 模型积累几个月后轻松超过 50GB。建议给 ComfyUI 单独规划一个磁盘分区或目录并预留至少 30GB 的可用空间。不要把所有模型随意堆放在系统盘的用户下载目录里否则后期整理成本极高。4. 本地部署ComfyUI的两条可行路线ComfyUI 的安装方式大致分成两类第一类是手动 Git Python 部署适合希望理解运行原理、将来做二次开发的人第二类是使用社区一键整合包适合希望快速开始画图、不想折腾环境的人。两条路线不冲突很多人的路径是先手动画图后期再回到手动部署来接入 API 服务。4.1 方案一手动部署进入准备放置项目的目录打开终端执行git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI python -m venv venv这里先创建虚拟环境。不同系统激活虚拟环境的命令不同# Windows PowerShell .\venv\Scripts\Activate.ps1 # Windows CMD venv\Scripts\activate.bat # Linux / macOS source venv/bin/activate激活虚拟环境后安装依赖pip install -r requirements.txt如果你所在网络环境访问默认源比较慢可以临时使用国内 pip 镜像pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple命令执行完成后在项目根目录运行python main.py看到类似路径的提示后浏览器访问http://127.0.0.1:8188就进入 ComfyUI 界面了。4.2 方案二社区一键整合包很多入门用户会直接选择社区维护的整合包比较常见的是网络上讨论度较高的“秋叶 ComfyUI 整合包”。这类整合包通常把 Python、依赖、ComfyUI 主体和常见插件打包好解压后运行启动脚本就能自动打开浏览器。使用整合包的优点是省去环境配置的时间适合想快速看效果的人。但有两个坑必须提醒一是不要下载来源不明的版本尽量选择可溯源、讨论度较高且更新时间较新的资源二是整合包可以帮你起步但不要因此完全放弃命令行后面安装自定义节点或排查错误时你依然需要知道项目文件在哪里、日志在哪里看。此外整合包更新往往滞后于官方项目。如果你想使用新版 ComfyUI 功能最终还是要回到手动部署或者在整合包内通过 Git 手动更新到官方最新主分支前提是你对更新失败的风险有接受能力。4.3 启动后的健康检查无论哪种方式第一次启动后建议先做三个检查第一浏览器能否正常打开界面。如果页面打不开优先检查启动窗口是否报错。第二模型列表是否为空。在画布中双击搜索“Load Checkpoint”如果下拉列表是空的只说明模型还没下载不代表安装失败。第三能否保存工作流。ComfyUI 默认支持把工作流保存为 JSON 文件也可以直接保存为 PNG 图片。如果生成图片时提示权限问题需要检查输出目录是否可写。5. 下载AI生图模型并完成模型连接环境启动之后最重要的事情是往本地放入模型。整个 ComfyUI 界面上没有任何“下载模型”的功能按钮模型获取需要你自己完成。5.1 常见模型类型与获取渠道本地生图使用的模型种类很多最常接触的是 Stable Diffusion 1.5 系列、SDXL 系列以及更新的一些架构模型。对新手来说建议从 SD 1.5 或 SDXL 这类资料最丰富的模型开始因为社区教程多、踩坑案例多遇到问题时容易搜索到解决方式。模型的常见下载源主要是 Hugging Face 和 ModelScope。如果你在国内网络环境下访问 Hugging Face 遇到超时现象可以优先在 ModelScope 上搜索同名或同系列模型的镜像仓库。需要注意下载模型时优先选择 safetensors 格式它不包含可执行代码安全性高于老式 ckpt 格式。对于来源不明的模型文件不要因为好奇就直接部署恶意模型可能尝试在推理过程中执行异常行为。尽量选择模型作者官方发布渠道及社区广泛验证过的资源。5.2 通过 ModelScope 下载模型比较稳妥的下载方式是先打开模型搜索页面找到对应模型仓库 ID然后使用命令行工具下载。例如在 ModelScope 上搜索一个主模型页面后复制仓库 ID再执行下载命令。安装 ModelScope SDKpip install modelscope然后写一个 Python 脚本下载模型。# 文件名download_model.py from modelscope import snapshot_download # 替换成你在 ModelScope 模型页看到的真实仓库 ID repo_id 你的模型仓库ID local_dir ./models/checkpoints/ model_dir snapshot_download(repo_id, local_dirlocal_dir) print(模型已下载到, model_dir)注意不同模型仓库的目录结构不完全一样。有些仓库里既有主模型又有 VAE 和 LoRA下载后需要把文件整理到 ComfyUI 对应的模型子目录中而不是把所有文件堆在同一个文件夹里。5.3 接入 ComfyUI下载完成后回到 ComfyUI 界面找到画布上的 Load Checkpoint 节点点击模型名称下拉框右侧的刷新按钮。如果节点还没有出现该模型选择下拉框中的任意一个项目模型列表会重新加载。常见的失败场景是模型已经下载到了本地但放错了目录。例如把模型放到了文件夹的根目录而不是models/checkpoints/下这时候界面自然不会显示。ComfyUI 不会自动扫描整个磁盘它只读取约定目录下的模型文件。6. 搭建基础文生图工作流并验证效果从一个空白工作流开始搭建时第一种方式是双击空白画布唤起节点搜索面板输入节点名称后逐个添加。第二种更高效的方式是直接在菜单栏选择 Load DefaultComfyUI 会加载一个官方预设的文生图工作流通常包含完整的节点链路。6.1 基础工作流包含哪些节点一个最基本的文生图工作流至少包含 6 类节点节点名称作用关键输出Load Checkpoint加载主模型文件MODEL、CLIP、VAECLIP Text Encode将提示词编码为条件向量CONDITIONINGEmpty Latent Image创建空白潜空间图像LATENTKSampler对潜空间图像进行采样去噪LATENTVAE Decode将采样结果解码为像素图像IMAGESave Image保存图像文件到输出目录无在默认工作流中正负提示词分别使用独立的 CLIP Text Encode 节点两个节点的 CONDITIONING 输出分别接到 KSampler 的 positive 和 negative 输入。Empty Latent Image 为采样器提供一个初始噪声图像尺寸。KSampler 输出的 LATENT 要先经过 VAE Decode 变成正常图片再由 Save Image 保存。6.2 关键参数如何设置对新手来说KSampler 的参数最容易引起困惑。seed随机种子。固定同一个种子配合相同提示词和参数可复现同一张图。steps采样步数。SD 1.5 模型常用 20 到 30 步SDXL 模型有时会高一些。并不是越大越好过大只会增加耗时。cfg提示词引导强度。常用范围在 6 到 8 之间。数值过高会导致画面过饱和、对比异常。sampler 和 scheduler采样算法组合。新手可以先用默认配置熟悉后再尝试不同组合。denoise去噪强度。文生图时通常保持 1代表从纯噪声开始生成图生图时设置小于 1保留原图一定结构。另一个常见问题是对提示词语言的误解。Stable Diffusion 底模和大部分派生模型训练数据以英文为主中文提示词能力非常有限。想要稳定输出内容先给自己准备好一套英文提示词模板。想要实际理解每个词对应画面中的哪个元素最好的方式是固定 seed每次只修改一个提示词段落对比输出变化。6.3 点击运行后如何判断成功工作流没有明显连线错误后点击 Queue 按钮等待进度条在节点上依次推进。首次运行会经历模型加载过程在 CPU 较弱、机械硬盘较慢的机器上可能要多等一段时间。正常运行结束时Save Image 节点上会多出一张预览缩略图。图片文件默认保存在项目根目录的output/文件夹下文件名为时间戳组合。如果运行中途报错常见现象是某个节点右上角出现红色背景并在 Control 窗口中显示错误摘要。7. 工程化用Python API批量提交生成任务如果只在画布中手动点击 Queue做几张图和几十张图还可以接受当生成需求达到几百张或者想把它嵌入到业务系统时就要把目光转到 ComfyUI 的 API 能力上。7.1 API模式的核心思路ComfyUI 启动后本身就是一个本地 HTTP 服务默认监听 8188 端口。画布中执行的每一个生成任务其实都是把“工作流描述”发送到后端。做 API 调用的标准流程是第一步在画布中把工作流调整到满意状态点击菜单中的 Save (API Format)导出为 API JSON 格式。第二步用 Python 读取这个 JSON 文件并将其发送到http://127.0.0.1:8188/prompt。第三步通过/history接口查询任务执行状态和输出文件。这种方式很适合批量生成或程序化调用。你不需要理解 JSON 里每个字段的含义只要把导出内容作为固定模板在程序里动态修改提示词、seed 等字段再提交就可以了。7.2 Python提交任务示例# 文件名submit_workflow.py import json import random import urllib.request SERVER_ADDRESS 127.0.0.1:8188 def randomize_seed(obj): 递归处理如果遇到 seed 字段则替换成随机值 if isinstance(obj, dict): for key, value in obj.items(): if key seed and (value is None or value ): obj[key] random.randint(0, 2**32 - 1) else: randomize_seed(value) elif isinstance(obj, list): for item in obj: randomize_seed(item) def queue_prompt(api_workflow): randomize_seed(api_workflow) payload json.dumps({prompt: api_workflow}).encode(utf-8) req urllib.request.Request( fhttp://{SERVER_ADDRESS}/prompt, datapayload, headers{Content-Type: application/json}, ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read()) return result.get(prompt_id) def check_history(prompt_id): with urllib.request.urlopen( fhttp://{SERVER_ADDRESS}/history/{prompt_id}, timeout30 ) as resp: return json.loads(resp.read()) if __name__ __main__: # 请先在 ComfyUI 界面中通过 Save (API Format) 导出该文件 with open(api_workflow.json, r, encodingutf-8) as f: workflow json.load(f) prompt_id queue_prompt(workflow) print(任务已提交prompt_id:, prompt_id) # 实际使用中建议轮询等待任务完成 # import time # time.sleep(10) # print(json.dumps(check_history(prompt_id), ensure_asciiFalse, indent2))这段代码的用途不是替代图形界面而是告诉你一种可复用的工程思路。你可以把它封装成脚本循环修改不同的提示词达到批量生成的目的。7.3 API调用过程中的注意点API 调用并不是任何工作流都能直接提交。你必须在界面菜单里导出 API 格式的 JSON而不是普通的 UI 工作流 JSON。两者结构不同普通保存的文件里包含节点坐标、连线信息等界面元素后端不一定能正确解析。另一个常见错误是服务端返回 400 错误。多数情况下是因为修改 JSON 时破坏了某个节点输入数据的结构比如把整数改成了字符串或把数组层级弄错。出现这种情况时先不要从自己的 Python 脚本找问题用原始的 api_workflow.json 不带任何修改地提交一次如果成功再去逐步检查你在代码里改了哪些字段问题定位会快很多。8. 常见问题排查表下面整理了本地部署 ComfyUI 过程中出现频率较高的问题如果你是新手遇到报错可以先对照排查。问题现象可能原因排查方式解决方案启动时提示端口被占用8188 端口已被其他进程占用或上次 ComfyUI 未正常退出查看启动日志中的端口报错提示更换端口启动python main.py --port 8189或关闭占用进程浏览器打开 127.0.0.1:8188 无响应ComfyUI 进程未启动成功或防火墙拦截查看启动窗口是否有报错堆栈根据日志定位错误一般先检查 Python 依赖是否安装完整Load Checkpoint 节点找不到刚下载的模型模型放错目录确认文件是否在 models/checkpoints/ 下把文件移动或复制到正确目录后点击刷新按钮执行时报错CUDA out of memory显存不足以跑当前模型和分辨率观察报错信息里的剩余显存大小降低图片分辨率或使用python main.py --lowvram降低显存占用生成图整体发灰、对比度异常模型未内置 VAE或需要额外加载 VAE 文件检查 Load Checkpoint 输出是否有 VAE 节点单独下载匹配的 VAE 文件并加载到 VAE Decode 前节点报错Error occurred when executing KSampler采样器输入条件不匹配或模型类型不支持当前节点组合双击报错节点查看错误详情中的具体提示检查正向条件与负向条件是否都已连接提示词编码与模型是否匹配自定义节点安装后画布上找不到custom_nodes 插件未正确安装或依赖缺失重启 ComfyUI查看启动日志中插件是否加载失败按插件说明安装依赖或在项目设置中重新启用插件提示无法下载某个依赖包网络源访问失败或没有使用虚拟环境查看 pip 错误信息使用国内 pip 镜像源或切换到虚拟环境后重新安装这张表只覆盖高频问题不同环境、不同模型版本还会衍生出更多报错。遇到陌生错误时第一原则是看输出窗口里的完整日志ComfyUI 的客户端错误提示通常已经很清晰地给出了异常类型和发生节点不要盲目去改模型或重装整个软件。9. 工程最佳实践与后续学习建议9.1 工程实践建议把 ComfyUI 当作日常工具使用时有几个习惯值得从一开始就养成。第一个建议是规范目录结构。主模型的大小动辄好几个G下载后不要乱放。建议用有明显含义的目录例如models/checkpoints/sd15_base/和models/checkpoints/sdxl_base/并在文本文件中记录模型来源与使用方式。遇到生成结果异常时这份记录能帮你快速回忆对比环境。第二个建议是重视 seed 和参数快照。ComfyUI 保存 PNG 图时默认会把工作流参数写入图片元数据拖回 ComfyUI 画布就能还原。这个特性建议充分利用把每次出图的工作流保存在图像文件中比单独保存 JSON 更直观。团队协作时把已生成的图片连同配套工作流一起归档能有效避免沟通时信息丢失。第三个建议是谨慎更新。ComfyUI 更新速度较快官方主分支的变动有时会破坏自定义节点。如果你的工作流依赖较多第三方节点不要在生成重要内容的中途随意更新。先将完整项目目录备份再更新并运行默认工作流测试全部通过后再投入日常使用。第四个建议是安全边界。只从可信渠道下载模型和节点不轻易运行来源不明的脚本。虽然本地部署是离线环境但第三方自定义节点可能包含额外代码逻辑盲目把网上下载的文件夹复制到custom_nodes/目录里相当于给未知代码开了执行权限。谨慎些不丢人。9.2 后续学习方向当你已经能把基础工作流稳定跑通下一步大致会分成几个方向。第一个方向是学习精准控制。熟悉 ControlNet 节点后可以通过骨骼、深度图、线稿约束生成结果这是从“抽盲盒”走向“可控创作”的关键。第二个方向是学习风格定制。LoRA 是对底层模型做局部能力扩展的低成本手段在 ComfyUI 中训练和调用 LoRA 都有成熟的流程。如果想要生成某个固定角色、固定画风低成本的 LoRA 是合理的起点。第三个方向是学习更完整的生产链路。本地出图只是第一步实际项目还需要接入工作流管理、模型审核、安全过滤乃至与其它内部系统联动。这时会用到 Docker 化部署、多实例并发以及模型微调等工程能力。你会发现ComfyUI 仅仅是一个很好的入口真正的深度在于如何把模型能力变成稳定的产品能力。先把基础链路跑通。环境、模型、节点这三件事理顺之后再逐步添加更多功能块你会在本地部署中得到比在线服务更大的掌控感。希望这份梳理能帮你避开那些“自己硬踩”的坑也欢迎在评论区聊聊你跑通 ComfyUI 时遇到的第一个报错。
从零开始本地部署ComfyUI：掌握节点工作流与模型管理
很多第一次接触 ComfyUI 的人不是被节点式界面吓退的就是被各种报错卡死的。明明下载了整合包也把模型放进去了点击运行却弹出一句“节点在执行过程中发生错误”然后整个流程停在那里只剩下红色错误提示和一堆看不懂的日志。这种挫败感几乎是每一位本地部署玩家的必经之路。我的一个判断是ComfyUI 本地部署的难度从来不在于“安装”本身而在于你把它当成一个普通软件来用却没有理解它背后的工作流思维方式。它和传统 WebUI 类的绘图工具不一样和在线生图网站更不一样。它本质上是一个“可视化图像生成流水线”一旦理解了节点图、数据流、模型目录这三件事你会发现它比想象的简单得多而且上限高得多。这篇文章会从零开始讲清楚为什么要在本地部署 ComfyUI、需要准备什么环境、模型该放哪里、基础文生图工作流怎样跑通最后再到如何用 API 方式做批量出图。内容尽量避开那些“复制一堆代码但不知道什么意思”的教程写法每一段都会解释原因和容易踩坑的地方。1. 本地部署ComfyUI解决什么问题谁最需要1.1 本地部署与在线绘图的核心差异先说底层逻辑。在线生图网站本质上是把图片生成任务提交到云端服务器你获得的是最终图片但控制权非常有限。本地部署 ComfyUI 后模型权重、推理代码、甚至采样参数都掌握在自己手里所有计算都发生在你的电脑上。这意味着三个非常实际的变化第一隐私性。很多设计师或内容创作者会有不便上传到第三方平台的工作素材本地推理不需要把图片上传到任何地方模型推理过程完全离线运行。第二可变成本趋近于零。在线平台通常按生成次数收费本地部署只需要一次性支付硬件和电费成本。对于那些每天生成几百张图做构图探索的人来说两者成本差距会非常明显。第三可扩展性。ComfyUI 的价值不只在于“文生图”它是支持自定义节点的你可以把 ControlNet、LoRA、局部重绘、视频生成模块都组合到同一条流水线里。这种扩展能力是在线平台和传统 WebUI 工具很难给的。1.2 适合与不适合的人群本地部署不是万金油。先说适合的人希望能系统学习 AI 生图原理的开发者。ComfyUI 的节点图很接近扩散模型的真实推理流程跑通一个基础工作流你会自然理解模型编码器、采样器、VAE 解码分别做了什么。有明确批量出图或自动化需求的工程人员。自己部署后可以调用本地 API把生成环节接入流程系统。有一定动手能力愿意折腾环境问题的创作者。再说暂时不适合的人。如果你完全不想接触任何命令行也接受不了版本冲突或模型路径报错那本地部署 ComfyUI 的体验会有点痛苦。这种情况下先使用配置更简单的 WebUI 整合包或者继续使用在线绘图服务或许是更合适的选择。学习工具要讲究性价比不能为了“本地”而本地。1.3 学习 ComfyUI 的核心认识很多教程会一上来就扔出几十个节点的工作流让人误以为 ComfyUI 很复杂。实际上绝大多数复杂工作流都建立在一条基础链路上模型 - 文本条件 - 采样 - 解码 - 输出图片。想明白这一点非常关键。如果你能亲手把这条链路搭出来再去看社区分享的复杂工作流大脑就不会被密密麻麻的连线吓到反而会下意识地把它们拆解成不同的功能块。这也是本文后面实操部分要严格推进的逻辑。2. ComfyUI核心概念与运行原理2.1 节点式工作流到底是什么ComfyUI 的界面里没有传统的“参数表单”而是一块无限画布上面放了各种节点节点之间用连线连接起来。每一个节点代表一个功能单元比如加载模型、编码提示词、执行采样、解码图片、保存图片。连线则代表数据在网络中的流动方向。从一个节点拉出来的每根线都被标记了数据类型。比如 Load Checkpoint 节点会输出 MODEL、CLIP、VAE 三种数据其中 MODEL 是扩散模型主干CLIP 负责文本编码VAE 负责把潜空间数据解码成可见图像。你需要把这些数据接到对应的节点上才能完成一次推理。这和地方画的 WebUI 最大的不同在于WebUI 把整条流程固化成了界面表单你只能在文本框和滑块之间操作ComfyUI 则把流程的控制权完全交给使用者。你可以像拼积木一样自由组合甚至可以创造出一些界面工具中很难实现的高级流程。2.2 模型、VAE与目录管理本地部署 ComfyUI 后你会面对一个 models 目录下面又有多个子目录。新手最容易搞混的就是 checkpoint、vae、lora 这几个文件夹。checkpoints 目录放置“主模型”也叫大模型。这类文件体积通常在 2GB 到 7GB 不等包含文本编码器、扩散模型主体和图像解码能力。常见格式是 safetensors 或 ckpt。loras 目录放置低秩微调模型体积很小通常在几十MB到几百MB。它的作用是给主模型注入特定风格、角色或画风。vae 目录放置独立的 VAE 文件。部分模型作者会把 VAE 打进主模型文件内但也有不少模型没有内置如果生成出来的图像整体发灰、对比度异常就要考虑手动加载 VAE 文件。controlnet、upscale_models、embeddings 等目录则分别服务于姿态控制、图像放大和提示词嵌入。提前理解这些目录的作用后续下载模型时才不会出现“文件明明在但节点里找不到”的情况。很多人刚接触时把 lora 文件放进了 checkpoints 目录加载的时候当然怎么都找不到。2.3 ComfyUI 的几种执行顺序ComfyUI 的执行顺序和普通流程图不完全一样。虽然你在画布上看到节点从左到右排列但前端提交任务时后端会先分析所有节点之间的依赖关系然后按拓扑排序依次执行。例如KSampler 节点依赖 Load Checkpoint 输出的 MODEL 和 CLIP也依赖 Empty Latent Image 输出的空图像张量。后端必须保证这些上游节点先执行完后KSampler 才会运行。因此即使你把节点位置摆得很乱ComfyUI 也能自动找出正确的顺序。新手之所以经常感到困惑是因为多数工作流模板里的排布方式会影响阅读体验但不会影响计算逻辑。这种设计也带来一个很好的调试习惯出现报错时不用看整张图从头到尾只需要定位报错提到的那个节点检查它缺少哪个输入或者它输出的数据格式是否匹配就能快速缩小问题范围。3. 环境准备与硬件条件开始本地部署之前最好先对自己的电脑情况做一个判断。很多安装失败并不是操作问题而是硬件或系统版本不够匹配。3.1 显卡与显存要求AI 生图模型在本地推理时最消耗资源的是显卡显存。显存大小直接决定你能跑多大的模型、多大的图片分辨率以及生成速度。如果是 NVIDIA 显卡建议显存至少 8GB 起步这样运行 SD 1.5 系列模型会相对顺畅也能勉强尝试小分辨率的 SDXL 模型。如果显存容量在 12GB 及以上体验会好很多能比较从容地使用 SDXL 系列并且有空间同时挂载 ControlNet、放大模型等附加模块。AMD 显卡和 Apple Silicon 设备也可以运行 ComfyUI但没有那么省心。Apple Silicon 设备上通常使用 MPS 后端有一些节点或自定义插件可能不支持。纯 CPU 环境虽然也能启动 ComfyUI但一张 512x512 的图可能要跑几分钟实际意义不大不建议作为主要硬件方案。3.2 操作系统与基础软件ComfyUI 是跨平台项目Windows、Linux、macOS 都能运行。不同系统的差异主要在环境配置这一步。Windows 上常见的是通过整合包或 Git 安装Linux 服务器通常用于部署生产环境macOS 则多用于本地创作测试。软件层面需要提前准备 Git 和 Python。Python 版本建议使用较新的 3.10 或 3.11太旧的版本会导致很多第三方依赖无法安装太新的版本有时会出现某些自定义节点兼容问题。安装 Git 后建议顺手配置好用户信息否则后续更新或下载插件时可能出现配置类的提示。如果在 Windows 上使用 NVIDIA 显卡还需要提前安装显卡驱动。可以打开命令行执行如下命令看到显卡信息说明驱动正常nvidia-smi如果提示找不到命令就需要先去安装或更新显卡驱动再考虑后面的部署步骤。3.3 磁盘空间本地生图模型占用的空间比很多人预期的大。一个主模型文件可能就有 2GB 到 7GB再算上 LoRA、ControlNet 模型积累几个月后轻松超过 50GB。建议给 ComfyUI 单独规划一个磁盘分区或目录并预留至少 30GB 的可用空间。不要把所有模型随意堆放在系统盘的用户下载目录里否则后期整理成本极高。4. 本地部署ComfyUI的两条可行路线ComfyUI 的安装方式大致分成两类第一类是手动 Git Python 部署适合希望理解运行原理、将来做二次开发的人第二类是使用社区一键整合包适合希望快速开始画图、不想折腾环境的人。两条路线不冲突很多人的路径是先手动画图后期再回到手动部署来接入 API 服务。4.1 方案一手动部署进入准备放置项目的目录打开终端执行git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI python -m venv venv这里先创建虚拟环境。不同系统激活虚拟环境的命令不同# Windows PowerShell .\venv\Scripts\Activate.ps1 # Windows CMD venv\Scripts\activate.bat # Linux / macOS source venv/bin/activate激活虚拟环境后安装依赖pip install -r requirements.txt如果你所在网络环境访问默认源比较慢可以临时使用国内 pip 镜像pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple命令执行完成后在项目根目录运行python main.py看到类似路径的提示后浏览器访问http://127.0.0.1:8188就进入 ComfyUI 界面了。4.2 方案二社区一键整合包很多入门用户会直接选择社区维护的整合包比较常见的是网络上讨论度较高的“秋叶 ComfyUI 整合包”。这类整合包通常把 Python、依赖、ComfyUI 主体和常见插件打包好解压后运行启动脚本就能自动打开浏览器。使用整合包的优点是省去环境配置的时间适合想快速看效果的人。但有两个坑必须提醒一是不要下载来源不明的版本尽量选择可溯源、讨论度较高且更新时间较新的资源二是整合包可以帮你起步但不要因此完全放弃命令行后面安装自定义节点或排查错误时你依然需要知道项目文件在哪里、日志在哪里看。此外整合包更新往往滞后于官方项目。如果你想使用新版 ComfyUI 功能最终还是要回到手动部署或者在整合包内通过 Git 手动更新到官方最新主分支前提是你对更新失败的风险有接受能力。4.3 启动后的健康检查无论哪种方式第一次启动后建议先做三个检查第一浏览器能否正常打开界面。如果页面打不开优先检查启动窗口是否报错。第二模型列表是否为空。在画布中双击搜索“Load Checkpoint”如果下拉列表是空的只说明模型还没下载不代表安装失败。第三能否保存工作流。ComfyUI 默认支持把工作流保存为 JSON 文件也可以直接保存为 PNG 图片。如果生成图片时提示权限问题需要检查输出目录是否可写。5. 下载AI生图模型并完成模型连接环境启动之后最重要的事情是往本地放入模型。整个 ComfyUI 界面上没有任何“下载模型”的功能按钮模型获取需要你自己完成。5.1 常见模型类型与获取渠道本地生图使用的模型种类很多最常接触的是 Stable Diffusion 1.5 系列、SDXL 系列以及更新的一些架构模型。对新手来说建议从 SD 1.5 或 SDXL 这类资料最丰富的模型开始因为社区教程多、踩坑案例多遇到问题时容易搜索到解决方式。模型的常见下载源主要是 Hugging Face 和 ModelScope。如果你在国内网络环境下访问 Hugging Face 遇到超时现象可以优先在 ModelScope 上搜索同名或同系列模型的镜像仓库。需要注意下载模型时优先选择 safetensors 格式它不包含可执行代码安全性高于老式 ckpt 格式。对于来源不明的模型文件不要因为好奇就直接部署恶意模型可能尝试在推理过程中执行异常行为。尽量选择模型作者官方发布渠道及社区广泛验证过的资源。5.2 通过 ModelScope 下载模型比较稳妥的下载方式是先打开模型搜索页面找到对应模型仓库 ID然后使用命令行工具下载。例如在 ModelScope 上搜索一个主模型页面后复制仓库 ID再执行下载命令。安装 ModelScope SDKpip install modelscope然后写一个 Python 脚本下载模型。# 文件名download_model.py from modelscope import snapshot_download # 替换成你在 ModelScope 模型页看到的真实仓库 ID repo_id 你的模型仓库ID local_dir ./models/checkpoints/ model_dir snapshot_download(repo_id, local_dirlocal_dir) print(模型已下载到, model_dir)注意不同模型仓库的目录结构不完全一样。有些仓库里既有主模型又有 VAE 和 LoRA下载后需要把文件整理到 ComfyUI 对应的模型子目录中而不是把所有文件堆在同一个文件夹里。5.3 接入 ComfyUI下载完成后回到 ComfyUI 界面找到画布上的 Load Checkpoint 节点点击模型名称下拉框右侧的刷新按钮。如果节点还没有出现该模型选择下拉框中的任意一个项目模型列表会重新加载。常见的失败场景是模型已经下载到了本地但放错了目录。例如把模型放到了文件夹的根目录而不是models/checkpoints/下这时候界面自然不会显示。ComfyUI 不会自动扫描整个磁盘它只读取约定目录下的模型文件。6. 搭建基础文生图工作流并验证效果从一个空白工作流开始搭建时第一种方式是双击空白画布唤起节点搜索面板输入节点名称后逐个添加。第二种更高效的方式是直接在菜单栏选择 Load DefaultComfyUI 会加载一个官方预设的文生图工作流通常包含完整的节点链路。6.1 基础工作流包含哪些节点一个最基本的文生图工作流至少包含 6 类节点节点名称作用关键输出Load Checkpoint加载主模型文件MODEL、CLIP、VAECLIP Text Encode将提示词编码为条件向量CONDITIONINGEmpty Latent Image创建空白潜空间图像LATENTKSampler对潜空间图像进行采样去噪LATENTVAE Decode将采样结果解码为像素图像IMAGESave Image保存图像文件到输出目录无在默认工作流中正负提示词分别使用独立的 CLIP Text Encode 节点两个节点的 CONDITIONING 输出分别接到 KSampler 的 positive 和 negative 输入。Empty Latent Image 为采样器提供一个初始噪声图像尺寸。KSampler 输出的 LATENT 要先经过 VAE Decode 变成正常图片再由 Save Image 保存。6.2 关键参数如何设置对新手来说KSampler 的参数最容易引起困惑。seed随机种子。固定同一个种子配合相同提示词和参数可复现同一张图。steps采样步数。SD 1.5 模型常用 20 到 30 步SDXL 模型有时会高一些。并不是越大越好过大只会增加耗时。cfg提示词引导强度。常用范围在 6 到 8 之间。数值过高会导致画面过饱和、对比异常。sampler 和 scheduler采样算法组合。新手可以先用默认配置熟悉后再尝试不同组合。denoise去噪强度。文生图时通常保持 1代表从纯噪声开始生成图生图时设置小于 1保留原图一定结构。另一个常见问题是对提示词语言的误解。Stable Diffusion 底模和大部分派生模型训练数据以英文为主中文提示词能力非常有限。想要稳定输出内容先给自己准备好一套英文提示词模板。想要实际理解每个词对应画面中的哪个元素最好的方式是固定 seed每次只修改一个提示词段落对比输出变化。6.3 点击运行后如何判断成功工作流没有明显连线错误后点击 Queue 按钮等待进度条在节点上依次推进。首次运行会经历模型加载过程在 CPU 较弱、机械硬盘较慢的机器上可能要多等一段时间。正常运行结束时Save Image 节点上会多出一张预览缩略图。图片文件默认保存在项目根目录的output/文件夹下文件名为时间戳组合。如果运行中途报错常见现象是某个节点右上角出现红色背景并在 Control 窗口中显示错误摘要。7. 工程化用Python API批量提交生成任务如果只在画布中手动点击 Queue做几张图和几十张图还可以接受当生成需求达到几百张或者想把它嵌入到业务系统时就要把目光转到 ComfyUI 的 API 能力上。7.1 API模式的核心思路ComfyUI 启动后本身就是一个本地 HTTP 服务默认监听 8188 端口。画布中执行的每一个生成任务其实都是把“工作流描述”发送到后端。做 API 调用的标准流程是第一步在画布中把工作流调整到满意状态点击菜单中的 Save (API Format)导出为 API JSON 格式。第二步用 Python 读取这个 JSON 文件并将其发送到http://127.0.0.1:8188/prompt。第三步通过/history接口查询任务执行状态和输出文件。这种方式很适合批量生成或程序化调用。你不需要理解 JSON 里每个字段的含义只要把导出内容作为固定模板在程序里动态修改提示词、seed 等字段再提交就可以了。7.2 Python提交任务示例# 文件名submit_workflow.py import json import random import urllib.request SERVER_ADDRESS 127.0.0.1:8188 def randomize_seed(obj): 递归处理如果遇到 seed 字段则替换成随机值 if isinstance(obj, dict): for key, value in obj.items(): if key seed and (value is None or value ): obj[key] random.randint(0, 2**32 - 1) else: randomize_seed(value) elif isinstance(obj, list): for item in obj: randomize_seed(item) def queue_prompt(api_workflow): randomize_seed(api_workflow) payload json.dumps({prompt: api_workflow}).encode(utf-8) req urllib.request.Request( fhttp://{SERVER_ADDRESS}/prompt, datapayload, headers{Content-Type: application/json}, ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read()) return result.get(prompt_id) def check_history(prompt_id): with urllib.request.urlopen( fhttp://{SERVER_ADDRESS}/history/{prompt_id}, timeout30 ) as resp: return json.loads(resp.read()) if __name__ __main__: # 请先在 ComfyUI 界面中通过 Save (API Format) 导出该文件 with open(api_workflow.json, r, encodingutf-8) as f: workflow json.load(f) prompt_id queue_prompt(workflow) print(任务已提交prompt_id:, prompt_id) # 实际使用中建议轮询等待任务完成 # import time # time.sleep(10) # print(json.dumps(check_history(prompt_id), ensure_asciiFalse, indent2))这段代码的用途不是替代图形界面而是告诉你一种可复用的工程思路。你可以把它封装成脚本循环修改不同的提示词达到批量生成的目的。7.3 API调用过程中的注意点API 调用并不是任何工作流都能直接提交。你必须在界面菜单里导出 API 格式的 JSON而不是普通的 UI 工作流 JSON。两者结构不同普通保存的文件里包含节点坐标、连线信息等界面元素后端不一定能正确解析。另一个常见错误是服务端返回 400 错误。多数情况下是因为修改 JSON 时破坏了某个节点输入数据的结构比如把整数改成了字符串或把数组层级弄错。出现这种情况时先不要从自己的 Python 脚本找问题用原始的 api_workflow.json 不带任何修改地提交一次如果成功再去逐步检查你在代码里改了哪些字段问题定位会快很多。8. 常见问题排查表下面整理了本地部署 ComfyUI 过程中出现频率较高的问题如果你是新手遇到报错可以先对照排查。问题现象可能原因排查方式解决方案启动时提示端口被占用8188 端口已被其他进程占用或上次 ComfyUI 未正常退出查看启动日志中的端口报错提示更换端口启动python main.py --port 8189或关闭占用进程浏览器打开 127.0.0.1:8188 无响应ComfyUI 进程未启动成功或防火墙拦截查看启动窗口是否有报错堆栈根据日志定位错误一般先检查 Python 依赖是否安装完整Load Checkpoint 节点找不到刚下载的模型模型放错目录确认文件是否在 models/checkpoints/ 下把文件移动或复制到正确目录后点击刷新按钮执行时报错CUDA out of memory显存不足以跑当前模型和分辨率观察报错信息里的剩余显存大小降低图片分辨率或使用python main.py --lowvram降低显存占用生成图整体发灰、对比度异常模型未内置 VAE或需要额外加载 VAE 文件检查 Load Checkpoint 输出是否有 VAE 节点单独下载匹配的 VAE 文件并加载到 VAE Decode 前节点报错Error occurred when executing KSampler采样器输入条件不匹配或模型类型不支持当前节点组合双击报错节点查看错误详情中的具体提示检查正向条件与负向条件是否都已连接提示词编码与模型是否匹配自定义节点安装后画布上找不到custom_nodes 插件未正确安装或依赖缺失重启 ComfyUI查看启动日志中插件是否加载失败按插件说明安装依赖或在项目设置中重新启用插件提示无法下载某个依赖包网络源访问失败或没有使用虚拟环境查看 pip 错误信息使用国内 pip 镜像源或切换到虚拟环境后重新安装这张表只覆盖高频问题不同环境、不同模型版本还会衍生出更多报错。遇到陌生错误时第一原则是看输出窗口里的完整日志ComfyUI 的客户端错误提示通常已经很清晰地给出了异常类型和发生节点不要盲目去改模型或重装整个软件。9. 工程最佳实践与后续学习建议9.1 工程实践建议把 ComfyUI 当作日常工具使用时有几个习惯值得从一开始就养成。第一个建议是规范目录结构。主模型的大小动辄好几个G下载后不要乱放。建议用有明显含义的目录例如models/checkpoints/sd15_base/和models/checkpoints/sdxl_base/并在文本文件中记录模型来源与使用方式。遇到生成结果异常时这份记录能帮你快速回忆对比环境。第二个建议是重视 seed 和参数快照。ComfyUI 保存 PNG 图时默认会把工作流参数写入图片元数据拖回 ComfyUI 画布就能还原。这个特性建议充分利用把每次出图的工作流保存在图像文件中比单独保存 JSON 更直观。团队协作时把已生成的图片连同配套工作流一起归档能有效避免沟通时信息丢失。第三个建议是谨慎更新。ComfyUI 更新速度较快官方主分支的变动有时会破坏自定义节点。如果你的工作流依赖较多第三方节点不要在生成重要内容的中途随意更新。先将完整项目目录备份再更新并运行默认工作流测试全部通过后再投入日常使用。第四个建议是安全边界。只从可信渠道下载模型和节点不轻易运行来源不明的脚本。虽然本地部署是离线环境但第三方自定义节点可能包含额外代码逻辑盲目把网上下载的文件夹复制到custom_nodes/目录里相当于给未知代码开了执行权限。谨慎些不丢人。9.2 后续学习方向当你已经能把基础工作流稳定跑通下一步大致会分成几个方向。第一个方向是学习精准控制。熟悉 ControlNet 节点后可以通过骨骼、深度图、线稿约束生成结果这是从“抽盲盒”走向“可控创作”的关键。第二个方向是学习风格定制。LoRA 是对底层模型做局部能力扩展的低成本手段在 ComfyUI 中训练和调用 LoRA 都有成熟的流程。如果想要生成某个固定角色、固定画风低成本的 LoRA 是合理的起点。第三个方向是学习更完整的生产链路。本地出图只是第一步实际项目还需要接入工作流管理、模型审核、安全过滤乃至与其它内部系统联动。这时会用到 Docker 化部署、多实例并发以及模型微调等工程能力。你会发现ComfyUI 仅仅是一个很好的入口真正的深度在于如何把模型能力变成稳定的产品能力。先把基础链路跑通。环境、模型、节点这三件事理顺之后再逐步添加更多功能块你会在本地部署中得到比在线服务更大的掌控感。希望这份梳理能帮你避开那些“自己硬踩”的坑也欢迎在评论区聊聊你跑通 ComfyUI 时遇到的第一个报错。
