这次我们来看一套完整的 ComfyUI 本地部署与使用流程。ComfyUI 是目前社区使用最广的节点式 Stable Diffusion 工作流工具它把提示词、模型加载、采样器、VAE 解码、图像保存这些环节全部拆成可视化的节点用户通过连线把它们拼成一条完整的生成链路。如果你需要固定一套出图流程、批量出图或者想把生成能力接到自己的项目里ComfyUI 会是比传统 WebUI 更合适的选择。这份教程的内容目标是面向 2026 年想系统学习 ComfyUI 的本地部署用户从头到尾覆盖安装、启动、工作流搭建、功能验证、API 批量调用、性能观察和常见报错排查。文中的命令和配置都按通用环境给出实际使用时必须根据你本机的目录结构、Python 版本和 ComfyUI 版本做调整不要照抄一个命令就不管上下文。先给结论ComfyUI 适合有独立显卡的用户显存越大越省心低显存机器也不是不能跑但要在分辨率、步数和批量数上做取舍。它支持文生图、图生图、局部重绘、ControlNet 控制也能通过自定义节点扩展视频生成、OCR、语音等能力。最实用的一点是默认开放 HTTP API也就是说你可以在浏览器里调通一次工作流之后用脚本批量提交生成任务这是它和 WebUI 拉开差距的关键。下面按“核心能力 → 适用场景 → 环境准备 → 安装启动 → 基础概念 → 功能测试 → API 批量 → 性能观察 → 排错 → 最佳实践”的顺序展开。建议新手到第 3 章先把硬件和依赖检查一遍再往下走后面踩的坑会少很多。1. ComfyUI 核心能力速览能力项说明项目类型开源的节点式 AI 图像/视频生成工作流工具核心功能文生图、图生图、局部重绘、ControlNet、LoRA、提示词管理、工作流导入导出、API 调用、批量任务依赖环境Python、PyTorch、CUDA以及对应的大模型文件推荐硬件优先 NVIDIA 独立显卡显存按目标模型评估显存占用与模型类型、分辨率、步数、批量数强相关必须按本机实际测试支持平台Windows 10/11、Linux 常见发行版macOS 需按官方说明另行测试启动方式源码命令行启动、整合包一键启动、WebUI 页面访问、API 服务是否支持 API支持默认监听本地端口可提交工作流任务是否支持批量任务支持可通过 API 脚本循环提交或串行处理适合场景固定工作流复用、批量出图、本地私有化部署、插件/节点开发需要补充一点表格里的“是否支持”都基于 ComfyUI 的通用能力不代表你当前安装的版本一定包含对应插件或模型。如果目标是用 ComfyUI 跑视频生成还要额外装视频类模型和自定义节点这类任务的资源占用通常比普通文生图高很多建议单独开一个环境测试。2. 适用场景与使用边界2.1 这个工具适合谁如果你是已经会用 SD WebUI、但对复杂流程控制不满意的使用者ComfyUI 能让你看清整条生成链路。当你需要固定一套提示词策略、固定一组采样参数并反复出图时节点式工作流比传统界面更容易沉淀成可复用模板。如果你是一名开发者想把图像生成能力接入自己的 Python 服务ComfyUI 的 API 接口能节省不少二次开发时间。团队场景下工作流文件可以直接分享给同事大家用同一份流程出图结果可比性也会更好。2.2 不适合什么场景反过来看如果只是偶尔生成一张图、完全不想接触节点连线ComfyUI 的学习曲线会比 WebUI 陡一些。如果你没有独立显卡并且不能接受很慢的 CPU 推理速度先用在线服务或者 WebUI 会更实际。显存过小且不愿意降低分辨率、步数、批量数的用户跑大型模型也会经常遇到资源不足的报错。ComfyUI 本身是一个框架不是魔法硬件条件是绕不开的。2.3 使用边界与合规要求无论用 ComfyUI 做什么都要守住基本边界涉及人脸、声音、品牌标识、受版权保护素材时必须提前取得合法授权。生成结果不得用于传播违法、虚假、欺诈内容。下载模型文件时确认许可证和来源不要在不可信渠道随意运行来路不明的压缩包。这些不是套话而是实际部署和使用 AI 生成工具时最容易忽略的问题。3. ComfyUI 本地部署环境准备3.1 操作系统与基础工具Windows 10/11 和 Linux 主流发行版都可以跑 ComfyUI。Windows 用户建议把整个安装目录放在不含中文和空格的路径下例如D:\ComfyUI避免部分依赖库在中文路径下出现编码问题。Linux 用户建议先确认系统已安装基础编译工具和 Git。所有用户都需要一个能正常解压压缩包的工具因为不管是源码包还是整合包第一步都是解压到本地。3.2 显卡驱动与 CUDANVIDIA 显卡用户需要先更新显卡驱动再确认驱动能被系统识别。打开终端执行nvidia-smi能看到显卡型号和驱动版本说明驱动状态正常。ComfyUI 底层依赖 PyTorch 和 CUDA具体安装哪个 CUDA 版本要以你安装的 PyTorch 版本为准。这里有两条路一是系统已经装好 CUDA Toolkit二是直接用 pip 安装带 CUDA 支持的 PyTorch后者对新手更友好不用手动改系统环境变量。3.3 磁盘空间与内存模型文件是占用空间的大头。一个基础大模型动辄几个 GB再加上 VAE、LoRA、ControlNet 等文件磁盘要预留充足空间。有条件的话建议放在 SSD 上机械硬盘加载模型会明显偏慢。运行时的内存占用同样不能忽略内存不足时生成任务容易直接崩溃这时可以适当增加系统虚拟内存。这个操作在 Windows 的“高级系统设置 → 性能 → 虚拟内存”里调整后续第 8 章还会再提。3.4 安装包来源校验不管是官方源码还是社区整合包都要先确认来源可信。使用整合包时解压前先检查压缩包完整性解压后确认目录结构是否符合预期。杀毒软件如果对启动脚本报警不要直接选择“信任”或“删除”先判断是误报还是打包文件确实有问题。从材料看社区里常用的整合包方案包括秋叶整合包等但名字只是渠道标识使用前仍然要直接核对文件哈希或来源公告不要因为“大家都用”就放松校验。4. 安装部署与启动方式4.1 整合包方式对新手来说整合包是最省心的方案。这类包一般把 Python 环境、PyTorch、ComfyUI 本体和常用模型整理在一起解压后通过启动脚本就能用。常见的操作流程是解压到非中文路径双击启动脚本进入启动界面选择“启动 ComfyUI”等待控制台输出本地访问地址然后在浏览器打开。整合包的优点是环境隔离好、上手快缺点是包体积大、版本更新依赖整合包作者维护节奏。4.2 源码方式如果后续要深度调试或做二次开发建议用源码方式安装。基本流程是拉取源码、创建虚拟环境、安装依赖、启动服务。下面是一个通用模板实际路径和版本号需要按官方 Readme 调整。# 1. 克隆或下载 ComfyUI 源码 git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI # 2. 创建并激活虚拟环境 # Windows PowerShell python -m venv venv .\venv\Scripts\Activate.ps1 # Linux python3 -m venv venv source venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt # 4. 启动服务 python main.py --port 8188这段命令的--port 8188是常见默认端口如果你的 8188 端口已经被占用可以换成其他端口例如--port 8288。启动完成后不要关闭终端ComfyUI 是在这个前台进程里运行的。4.3 模型文件目录ComfyUI 启动后并不会自己下载模型需要你把模型文件放到正确目录否则加载节点会报错。默认目录结构大致如下ComfyUI/ ├── models/ │ ├── checkpoints/ # 大模型 │ ├── loras/ # LoRA 模型 │ ├── vae/ # VAE 模型 │ ├── controlnet/ # ControlNet 模型 │ └── ... ├── custom_nodes/ # 自定义节点/插件 ├── input/ # 图生图输入素材 ├── output/ # 输出图片 └── main.py新拿到一个模型文件时先看扩展名和说明再放进对应目录。checkpoints 模型放错到 loras 目录虽然不会马上报错但后续节点连线时容易出现类型不匹配的问题。4.4 启动验证启动完成后浏览器访问http://127.0.0.1:8188能看到工作流编辑界面就说明服务正常。第一次打开时界面可能是空白工作流不要慌这是正常的。如果页面打不开回到终端看启动日志端口被占用、依赖缺失、模型加载失败都会在这里体现。日志里没有错误但页面打不开时优先确认防火墙是否拦截了本地端口。5. ComfyUI 基础概念与工作流搭建5.1 节点、连线与工作流ComfyUI 的核心思想是“节点 连线”。一个节点就是一个功能模块节点左侧是输入端口右侧是输出端口数据从左往右流动。用户在画布上拖入节点然后把对应的端口连接起来就形成了一条生成链路。这条链路被保存下来就是工作流。理解这一点后很多报错都变得容易排查某个节点的输入类型不匹配、缺少前置节点、端口没有连上都会直接导致执行失败。5.2 文生图核心节点一个最简文生图工作流通常包含六个节点Load Checkpoint加载主模型同时提供 model、clip、vae 三路输出。CLIP Text Encode把正向提示词和反向提示词分别编码。Empty Latent Image创建空白潜空间图像指定宽高。KSampler采样器设置种子、步数、CFG、采样器名称和调度器。VAEDecode把采样后的潜空间数据解码成图像。Save Image保存图片到 output 目录。对新手来说先认识这六个节点就够了。后续加 LoRA、ControlNet、局部重绘都是在这条链路上插入额外节点。5.3 搭建第一个文生图工作流在 ComfyUI 画布上搭建的连线思路如下拖入 Load Checkpoint选择你要用的主模型。拖入两个 CLIP Text Encode一个写正向提示词一个写反向提示词。拖入 Empty Latent Image设置宽高先用小分辨率测试。把 Load Checkpoint 的 model 输出接到 KSampler 的 model 输入。把两个 CLIP Text Encode 的输出分别接到 KSampler 的 positive 和 negative。把 Empty Latent Image 的输出接到 KSampler 的 latent_image。把 KSampler 的 output 接到 VAEDecode 的 samples再接到 Save Image 的 images。最后点击 Queue Prompt 开始生成。第一次执行时间可能比预期长因为要先把模型加载到显存。生成成功后output 目录里会出现一张图片。5.4 工作流导入与导出工作流可以以两种形式保存。一种是生成的 PNG 图片本身自带工作流信息直接把图片拖回 ComfyUI 画布就能恢复整套节点。另一种是保存为 JSON 文件适合分享和依赖管理。如果后续要通过 API 批量调用一般需要从 UI 里导出 API 格式的 JSON这个文件会比普通工作流 JSON 更精简接口脚本能直接读取。6. ComfyUI 功能测试与效果验证6.1 文生图测试文生图是必须第一个跑通的功能。测试时先输入一组简单的正反向提示词例如正向a cat sitting on a table, high quality反向blurry, bad quality。步数先设为 20CFG 设为 7 左右分辨率先用 512×512 或者更小。点击 Queue 后观察生成日志看模型是否成功加载、采样是否正常。只要底部出现保存的图片文生图链路就算跑通了。6.2 图生图测试图生图测试的目的是验证输入图像能不能被正确编码进潜空间。把要输入的图片放到input目录拖入 Load Image 节点再通过 VAE Encode 节点把图像转成潜空间数据然后接入 KSampler。这里的核心参数是 Denoise值越大输出和原图的差异越大值越小越接近原图。第一次建议把 Denoise 设为 0.5 左右输出的图应该能明显看出原图结构同时又有一定变化。6.3 局部重绘测试局部重绘能验证遮罩和蒙版相关的节点是否正常。它的思路是先加载原图用遮罩节点定义需要修改的区域再把遮罩信息传给采样器让模型只在这个区域重新生成其他区域尽量保留。测试成功的关键是遮罩范围是否准确。如果发现修改范围扩散到了整个图片优先检查遮罩节点和 KSampler 的连线是否正确。6.4 参数对出图的影响测试时要有意识地改变参数观察效果。Steps 越多细节通常越丰富但耗时也越长。CFG Scale 代表提示词对生成的引导强度数值越高画面越贴提示词但超过合理范围容易过曝或色彩失真。分辨率越高显存占用和生成耗时都会明显上涨。Seed 固定后同样的参数可以复现同一张图批量任务里变化 Seed可以得到同一提示词下的多张不同结果。6.5 输出质量判断判断一张图是否成功不只是看“有没有图”。正常测试时输出图应该有清晰的主体、合理的色彩和可辨识的纹理。如果出现全黑图优先检查 VAE 是否加载正确如果出现大量噪点或花屏优先排查显存溢出和模型文件是否损坏。进入正式项目前建议先用一个固定 prompt 和种子跑几次确认输出稳定后再批量操作。7. ComfyUI 接口 API 与自动化批量任务7.1 API 启动方式与工作流导出ComfyUI 启动后本身就带 API 服务不需要额外开一个服务进程。先在 UI 中搭建并测试好工作流然后切换到开发模式导出一份 API 格式的 JSON。这个 JSON 里的每个节点都是可替换的键值结构脚本可以读取后修改其中的提示词、种子、尺寸等字段再提交到任务队列。7.2 提交任务到队列提交任务使用 HTTP POST 请求。下面是一个通用 Python 示例实际节点 ID 要以你导出的 JSON 为准。import json import requests def load_workflow_api(path): with open(path, r, encodingutf-8) as f: return json.load(f) def queue_prompt(workflow, serverhttp://127.0.0.1:8188): url f{server}/prompt payload {prompt: workflow} resp requests.post(url, jsonpayload, timeout30) resp.raise_for_status() return resp.json() workflow load_workflow_api(workflow_api.json) result queue_prompt(workflow) print(result.get(prompt_id))如果返回结果里带有 prompt_id说明任务已经进入执行队列。这个 id 是后续查询任务状态的关键。节点 ID 不是固定的不同版本导出的 JSON 可能完全不同脚本里不要写死具体的6或3要么动态读取要么在导出时手动记录。7.3 查询任务结果提交任务后需要轮询 ComfyUI 的 history 接口来确认任务是否执行完成。简化版代码如下import requests import time def wait_finish(server, prompt_id, timeout300): url f{server}/history/{prompt_id} deadline time.time() timeout while time.time() deadline: resp requests.get(url, timeout10) if resp.status_code 200 and resp.json(): return resp.json() time.sleep(2) raise TimeoutError(任务超时)这个模板的逻辑是每两秒查询一次历史记录直到某个 prompt_id 出现在 history 里。实际生产环境中history 接口返回的数据结构需要结合你的 ComfyUI 版本来解析图片输出路径一般在 outputs 信息里。7.4 批量任务思路批量任务的核心是把“提交”和“等待”拆开管理。先准备一个提示词列表循环里修改工作流 JSON 的文本和种子然后提交任务、记录 prompt_id。每次提交之间不要一次性把几百个任务全塞进队列否则显存和内存都可能被拉满。更稳妥的做法是控制并发窗口例如每提交一个任务后等待它完成再提交下一个如果显存够大也可以同时提交 2 到 3 个任务但要通过日志观察显存余量。下面是一个伪代码级的批量流程prompt_list [...] for i, user_prompt in enumerate(prompt_list): # 修改节点文本具体节点 ID 以导出的 JSON 为准 workflow[6][inputs][text] user_prompt # 修改种子获得多样性 workflow[3][inputs][seed] 1000 i result queue_prompt(workflow) prompt_id result.get(prompt_id) if not prompt_id: print(f第 {i} 个任务提交失败) continue try: history wait_finish(SERVER, prompt_id, timeout300) print(f第 {i} 个任务完成: {prompt_id}) except TimeoutError: print(f第 {i} 个任务超时准备重试)真实环境里还要给脚本加上日志记录和失败重试逻辑。每条任务至少记录 prompt_id、修改后的参数、耗时、输出文件路径方便后续审计和复现。遇到批量任务卡住时不要盲目调高并发先看当前显存占用和日志输出。8. 资源占用与性能观察8.1 观察方法ComfyUI 的资源占用没有统一数字因为它和模型、参数强相关。观察显存可以先看终端日志再看系统工具。Windows 下打开任务管理器的“性能”页可以从 GPU 栏看到专用显存占用Linux 下执行nvidia-smi能看到每张显卡的显存使用情况。建议在启动模型前后各记录一次数据这样能区分“加载模型”和“推理生成”分别占了多少显存。8.2 影响性能的因素分辨率对性能影响最大宽高乘积翻倍显存和耗时基本也翻倍。Steps 影响的是采样耗时步数越高越慢。Batch size 决定一次生成几张图批量数越高显存占用越大。ControlNet、视频生成这类扩展节点会额外增加显存和内存开销。模型本身的推理开销差异也很大不同大模型在相同参数下的速度可能相差明显。8.3 低显存优化思路低显存机器不是不能用而是要把参数控制在合理范围。第一分辨率先用 512×512 甚至更低确认链路稳定后再放大。第二减少步数先用 15 到 20 步测试找到质量和速度的平衡点。第三批量任务改成逐张提交避免多张同时占用显存。第四系统内存不足时增加虚拟内存防止进程直接崩溃。设置虚拟内存时优先放在剩余空间充足的 SSD 分区。8.4 端口冲突与进程残留端口被占用时启动日志会直接报错。一个常见解决方案是换端口例如--port 8288。另一个情况是任务卡死后关闭浏览器但后台 python 进程仍然存在重新启动时会发现端口被占。这时需要先结束残留进程再重新启动 ComfyUI不要反复双击启动脚本否则会产生多个实例。9. ComfyUI 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面打不开服务未启动或端口被占用检查启动日志和端口状态换一个端口或重启服务节点显示红色并报错缺少模型、插件或输入类型不匹配鼠标悬停节点查看具体报错补模型、装插件、检查连线加载 checkpoint 失败模型文件缺失或路径错误检查 models/checkpoints 目录下载正确模型并放入目录提示缺少自定义节点对应插件未安装看界面顶部红色提示安装对应节点插件显存不足分辨率、步数或批量数过高观察任务管理器的显存曲线降低参数或分辨率虚拟内存不足系统内存不够查看内存占用增加虚拟内存出图全黑VAE 缺失或与模型不匹配检查 VAE 节点和模型信息加载配套 VAEAPI 返回 400工作流 JSON 结构错误对照导出的 API 格式 JSON重新导出或修正节点 ID批量任务卡住队列阻塞或显存不足查看日志和显存占用减少并发加超时重试中文路径乱码安装目录含中文或特殊字符检查启动路径移到纯英文目录如果你看到的是“节点在执行过程中发生错误”先不要急着卸载重装。打开开发者模式复制完整报错信息再定位到具体节点。这个报错最常见的三个原因是模型文件没有放到正确目录、某个插件依赖没有装全、节点之间的输入类型不匹配。缩小范围之后单独测试这个节点比反复重启整个服务更有效。10. ComfyUI 最佳实践与使用建议第一次运行先用最小工作流验证环境不要在刚装好的时候直接上复杂视频模型。所谓最小工作流就是一个 checkpoint、一个采样器、一个保存节点参数全默认只要能出图就说明基础环境没问题。跑通之后再逐步加提示词模板、LoRA、ControlNet。工作流文件要分层管理。保留一份“可运行版本”每次修改前复制一份备份不要直接在线上文件里反复改。模型文件、输入素材、输出结果、批量脚本建议分目录存放避免几个月后回来找不到文件。所有模型文件都记录来源和许可证尤其是商用项目这一条不能省。批量任务必须加日志。日志里记录每条任务的 prompt_id、修改参数、开始时间、结束时间、输出路径、是否重试。没有日志的批量任务一旦中间断开很难恢复。接口服务默认监听127.0.0.1是安全的如果要在局域网内使用需要设置好防火墙和访问限制不要直接裸奔暴露给公网。涉及人脸、声音、品牌标识、版权素材时必须确认授权后再跑任务。生成结果不能直接当作事实信息发布尤其是在新闻、医疗、金融等领域要做人工复核。任何时候都不要在不可信渠道运行来历不明的脚本因为 ComfyUI 的插件本质上是可执行代码。11. 总结与下一步如果只选择一件事先验证先跑通文生图工作流。它是后面所有流程的地基也是排查环境问题最直接的入口。最容易踩的坑有三个模型文件缺失、节点连线错误、显存不足这三类问题都能通过小参数测试和看日志解决关键是不要跳过最简验证。跑通基础流程之后值得继续扩展的方向包括引入 LoRA 和 ControlNet 解决风格一致性与构图控制把 ComfyUI 封装成内部后端生成服务尝试视频生成类模型但先做好显存评估以及把常用工作流做成团队模板。后续再有新工具和新插件建议先在最小配置里试运行再投入到正式任务。建议把这篇教程的目录当作部署清单存下来按步骤打勾执行比反复看视频切片更高效。