想在本地跑一套 AI 生图模型ComfyUI 是很值得花时间研究的工具。以前只是照着网上视频一通复制粘贴做完不知道怎么修改后面自己从源码、模型目录、节点图到报错排查走了一遍才慢慢把“能用”和“会调”之间的差距补上。这篇文章会围绕 ComfyUI 本地部署做一次完整梳理覆盖环境准备、安装启动、模型下载与目录放置、默认工作流跑图、LoRA/ControlNet 扩展、常见报错定位以及一些适合长期维护的工程建议。无论是刚接触 AI 绘图的入门玩家还是已经在用 WebUI、想转向 ComfyUI 的开发者都可以直接参考这条路径。1. ComfyUI 是什么为什么要本地部署 AI 生图模型1.1 从“文生图”到“AI 绘图工具链”平时我们常说的 AI 生图模型本质上是根据文本描述生成图像的一类深度学习模型。以前想体验这类模型大多数时候需要依赖在线服务填一段提示词等在线平台返回结果。在线服务的优点是上手快但缺点也比较明显按次计费、排队等待、分辨率受限、不能深度定制底层参数。本地部署 AI 生图模型就是把模型下载到自己的电脑上再用本地推理工具运行。Stable Diffusion 生态里有两套非常主流的前端Stable Diffusion WebUI界面化程度高适合写提示词、调参数、做基础图。ComfyUI采用节点式工作流设计所有处理步骤都可视化为“节点气泡”节点之间通过连线组合成完整流程。ComfyUI 看起来不像普通软件界面更像是一张流程图。它的核心优势在于灵活同一个模型可以接不同采样器可以同时跑多种 ControlNet 控制条件也方便加入批量处理、视频生成等更复杂的自定义流程。1.2 本地部署 ComfyUI 解决了什么问题本地部署带来的直接好处有三个。第一隐私可控。图片描述和生成的图像只在自己的电脑上流转不需要上传到第三方服务器。第二长线成本低。显卡性能足够的情况下可以无限次生成不需要按次付费。第三调试空间大。ComfyUI 的每个节点都能拆开看很多生成过程中的中间状态可以显式保存和传递这让调参、改流程、复现实验结果变得特别方便。如果你之前画图时总是遇到“在线平台结果不可控”“没法精确调整某一步流程”的痛点ComfyUI 值得花时间搭起来。1.3 先认识几个高频关键词在进入部署步骤前先熟悉几个会反复出现的术语术语作用Checkpoint基础模型文件通常是safetensors或ckpt格式决定整体画风VAE负责图像色彩和细节还原缺失会导致图片发灰或出现伪影CLIP文本编码器负责把提示词转成模型能理解的向量LoRA轻量微调模型通过低秩适配给小范围改造画风或人物特征ControlNet用骨架、线稿、深度图等方式控制出图结构实际部署时这几种文件并非每次都要手动处理。ComfyUI 默认会通过 Checkpoint 自动加载对应的 VAE 和 CLIP但如果你使用二次元模型或者经过融合的模型可能需要手动指定 VAE。后面会详细讲到目录放置规则。2. 环境准备与版本说明本地部署 ComfyUI 是一个偏工程化的过程。先把环境整理干净后面会节省大量排错时间。2.1 硬件与驱动前提ComfyUI 的推理过程严重依赖 GPUNVIDIA 显卡是当前最省心的选择。如果你使用的是 AMD 显卡、Intel 显卡或 Apple Silicon Mac启动参数和依赖会有差异这篇文章仅以 Windows 下 NVIDIA 显卡作为主要示例场景。配置方面可以参考以下梯度最低可跑入门图SD 1.5NVIDIA GTX 1060 6GB 或同级显存 6GB 左右。基础流畅SDXLNVIDIA RTX 3060 12GB 或同级能比较舒服地生成 1024x1024 图片。进阶玩法ControlNet 大 batchRTX 4070 / 4080 及以上16GB 以上显存体验更好。需要提前装好对应版本的 NVIDIA 驱动。如果驱动太老PyTorch 可能无法调用 CUDA。检查驱动是否正常的常用命令nvidia-smi该命令会输出显卡型号、驱动版本、显存占用等信息。如果提示找不到命令说明驱动没有正确安装或者没有加入 PATH。2.2 需要提前安装的软件如果是手动源码安装需要准备GitPython 3.10 / 3.11 / 3.12推荐用较新的稳定版本一个代码编辑器推荐 VS Code打开终端逐个确认git --version python --version如果 Python 版本过于陈旧建议安装到 Python 3.11 左右。ComfyUI 的依赖生态会跟随 PyTorch 版本变化太老的 Python 会卡在依赖编译阶段。2.3 官方源码部署还是整合包现在中文社区里常见两类安装方式纯手动源码部署第三方整合包例如“秋叶整合包”等两者并不冲突。手动部署能看清底层结构便于理解模型目录、依赖安装、日志输出整合包适合快速启动把 Python 环境和 Git 仓库都提前准备好开箱即用。如果你之前完全没接触过 ComfyUI第一次体验使用成熟的整合包成本更低。但看教程时要注意一点整合包版本可能比你当前下载的版本旧教程里的界面选项和默认节点可能有差异。对于想长期学习节点图的读者我更建议至少走一遍手动源码部署再决定是否换回整合包。3. 本地部署的三种常见方式ComfyUI 本身的部署复杂度并不可怕核心就是把 Python 环境配置好再把模型文件放到正确位置。下面分别介绍手动源码部署、启动参数、整合包选择。3.1 手动源码部署完整命令打开终端进入希望存放项目的目录例如cd D:\AI克隆 ComfyUI 官方仓库git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI创建虚拟环境。直接在系统全局 Python 里安装依赖容易污染其他项目这里建议始终用虚拟环境python -m venv venvWindows 下激活虚拟环境.\venv\Scripts\activateLinux / macOS 下激活方式则稍有不同source venv/bin/activate激活后终端前缀一般会出现(venv)。ComfyUI 的核心深度学习框架是 PyTorch。安装时一定要选择包含 CUDA 支持的版本。如果直接使用默认的 PyTorch 源很可能会装成 CPU 版导致后续完全无法用显卡推理。以 CUDA 12.1 为例安装指令如下pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121不同的 PyTorch 版本对应不同 CUDA 小版本以 PyTorch 官网给出的最新命令为准。安装完成后检查是否真的启用了 CUDApython -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出True说明显卡调用成功。接着按仓库内的依赖清单安装pip install -r requirements.txt启动 ComfyUIpython main.py启动成功后终端会打印本地访问地址。默认情况下是http://127.0.0.1:8188浏览器打开该地址看到节点编辑界面说明安装已经完成。3.2 常用启动参数说明ComfyUI 默认启动时只监听本机 8188 端口也未必会最大化利用显卡。根据不同需求和硬件情况可以加启动参数。常见完整启动示例python main.py --auto-launch --port 8188 --lowvram--auto-launch启动成功后自动打开浏览器。--port指定访问端口。--lowvram低显存模式适合显卡显存不够的情况。--medvram中等显存模式。--listen允许局域网内其他设备访问示例--listen 0.0.0.0。--disable-auto-launch禁止自动打开浏览器。--lowvram和--medvram并不能把 6GB 显存变成 24GB它们只是让模型权重按需加载减少显存峰值。如果你的显卡只有 8GB 显存建议从默认模式开始测试如果出现显存溢出再依次尝试--medvram和--lowvram。3.3 集成包的适用场景“秋叶整合包”这类第三方工具的典型特点是自带 Python 便携环境预装 ComfyUI 本体一次性配置好常见依赖自带模型目录管理和启动器界面这对刚了解 ComfyUI 的新手来说很省力。但使用整合包需要注意版本来源尽量选择更新频繁、社区口碑好的整合包。不要盲目下载渠道未知的模型包和插件包运行前用杀毒软件查一遍更稳妥。4. 模型文件下载与目录放置ComfyUI 本身不会自带生图模型。安装完成后还需要自己下载模型文件并放到正确目录。4.1 ComfyUI 模型目录结构在 ComfyUI 根目录下有一个models文件夹里面会按模型种类拆分子目录D:\AI\ComfyUI\models ├── checkpoints ├── clip ├── clip_vision ├── configs ├── controlnet ├── diffusers ├── embeddings ├── gligen ├── hypernetworks ├── loras ├── photomaker ├── style_models ├── unet ├── vae └── vae_approx实际用到最多的是checkpoints存放主模型即 Checkpoint。loras存放 LoRA 模型。vae存放独立 VAE 模型。controlnet存放 ControlNet 模型。embeddings存放负面 embeddings 或自定义 word 向量。从网上下载.safetensors或.ckpt文件后如果你不确定该放到哪个目录先看文件名和页面描述。Checkpoint 通常体积巨大常见在 2GB 到 7GB 之间LoRA 和 embedding 通常只有几十到几百 MB。4.2 模型文件格式说明早期很多模型使用.ckpt格式后来社区逐步迁移到.safetensors。两种文件在 ComfyUI 中都能加载。.safetensors是更安全的序列化格式不包含可执行代码加载速度也更快。能选.safetensors就尽量不选.ckpt。下载模型时请尽量保留页面下提供的示例图、触发词、采样器建议、步数建议等信息。这些不是装饰性内容而是模型作者已经跑过大量测试后给出的最佳参数。不同模型的推荐参数差异很大硬套一套参数往往效果并不理想。4.3 示例放置一个基础 Checkpoint假设你下载了一个基础模型文件叫sdxl_base_model.safetensors请把它复制到D:\AI\ComfyUI\models\checkpoints\sdxl_base_model.safetensors重启 ComfyUI 后在 Checkpoint 加载器节点的列表里通常就能看到这个名字。如果没有看到新模型优先检查文件是否放到了checkpoints目录文件名后缀是否完整ComfyUI 是否还开着模型列表一般启动时加载一次新增文件需要刷新5. 跑通第一张图ComfyUI 基础工作流ComfyUI 的界面初看不太好懂但核心逻辑其实很清晰。无论多复杂的工作流都会包含“加载模型 - 处理文本 - 采样生成 - 解码保存”几个环节。5.1 默认工作流里的节点启动 ComfyUI 后如果画布是空白的一般可以先点击界面菜单里的Load Default载入一段默认工作流。默认工作流通常包含这些核心节点CheckpointLoaderSimple加载 Checkpoint 主模型同时暴露 MODEL、CLIP、VAE 三个输出。CLIPTextEncode用正向提示词生成文本条件。CLIPTextEncode用负向提示词生成文本条件。EmptyLatentImage初始化一张空白潜空间图像。KSampler执行采样去噪是真正决定图像质量的核心节点。VAEDecode把潜空间图像解码为像素空间图像。SaveImage保存图像到输出目录。直观理解的话可以把 Checkpoint 看成画师把 CLIPTextEncode 看成画师收到的画作要求把 KSampler 看成反复修改草稿的过程。VAEDecode 则相当于把最终草稿清晰印刷出来。5.2 节点连线结构ComfyUI 是基于连线驱动的。每个节点右侧是输出端口左侧是输入端口。一根连线代表一个中间结果在节点之间传递。从加载器出发典型的连线关系如下CheckpointLoaderSimple 的MODEL输出连到 KSampler 的model输入CheckpointLoaderSimple 的CLIP输出连接到两个 CLIPTextEncodeCLIPTextEncode 的输出分别连到 KSampler 的positive和negativeCheckpointLoaderSimple 的VAE输出连到 VAEDecodeEmptyLatentImage 输出连到 KSampler 的latent_imageKSampler 的LATENT输出连到 VAEDecodeVAEDecode 的IMAGE输出连到 SaveImage新手最容易犯的错误是只连线“看着相关的端口”却忽略了数据类型差异。ComfyUI 端口颜色可以帮你判断MODEL、CLIP、VAE、LATENT、IMAGE 各代表不同类型不能混接。5.3 填写正向提示词与负向提示词在正向提示词节点里输入a cute astronaut cat sitting on Mars surface, digital art, trending on art station, soft lighting, highly detailed这里不需要把每个词都用大括号包起来。ComfyUI 会按整句话理解语义。写提示词时建议把“主体、环境、画风、光照、细节”拆成几个短句中间用半角逗号分隔。负向提示词通常用来描述不想看到的内容。一个通用示例lowres, bad anatomy, bad hands, missing fingers, extra digit, blurry, jpeg artifacts如果你使用专门的 embedding 文件例如某些去模糊或修手的坏词库可以在负向提示词节点中如下调用easynegative, lowres, bad anatomy其中easynegative就是放在models/embeddings目录下某个 embedding 文件的触发名。5.4 设置采样参数并生成默认工作流中 KSampler 节点的参数如下seed随机种子相同种子在相同条件下大概率得到相同结果steps采样步数不是越多越好cfg提示词相关度sampler_name采样算法scheduler调度器denoise去噪强度如果是 SD 1.5 模型可以先尝试steps: 20 cfg: 7 sampler_name: euler scheduler: normal如果是 SDXL 模型很多社区示例建议在采样器和步数上做调整例如steps: 28 cfg: 4 - 7 sampler_name: dpmpp_2m scheduler: karras不同 Checkpoint 的最佳参数都不同更好的方式是以模型作者给出的推荐参数为基准。不要看到某一套参数在别人图上效果好就原封不动套到所有模型中。设置完成后点击右上角Queue Prompt按钮等待出图。如果一切正常图片会出现在预览面板中同时输出目录ComfyUI/output中也会多出一张 PNG 图片。5.5 生成过程中的终端日志怎么看在终端窗口里会输出每一步采样日志。注意类似Requested to load SDXLBase ... model loaded in 2.3s 100%|████████| 20/20 [00:2500:00] Prompt executed in 29.2 secondsRequested to load说明正在加载模型100%表示采样进度Prompt executed表示本次生成总耗时。如果你的模型加载阶段耗时很长可能是磁盘读取速度较慢。如果采样阶段很慢通常是计算资源不足。6. 进阶玩法LoRA、ControlNet 与自定义节点跑通基础文生图后可以尝试进一步控制图像。ComfyUI 的强大之处就在于通过添加节点来扩展功能。6.1 安装 ComfyUI-ManagerComfyUI-Manager 是管理自定义节点的工具强烈建议安装。进入 ComfyUI 根目录下的custom_nodes目录cd D:\AI\ComfyUI\custom_nodes克隆仓库git clone https://github.com/ltdrdata/ComfyUI-Manager.git cd ComfyUI-Manager pip install -r requirements.txt安装完成后重启 ComfyUI。界面中通常会出现一个Manager按钮通过它可以直接浏览和安装大量自定义节点。对于没有网络代理条件的用户如果 Manager 偶尔加载不出节点列表可以检查网络环境或手动通过 Git 克隆需要的节点仓库到custom_nodes目录。6.2 加入 LoRA 后工作流如何变化LoRA 可以理解为“给模型追加一套局部风格记忆”。它不需要重新训练整个大模型文件体积很小适合用来批量尝试不同画风。不使用 LoRA 时流量走向是Checkpoint → KSampler使用 LoRA 后需要插入一个LoraLoader节点Checkpoint MODEL → LoraLoader model Checkpoint CLIP → LoraLoader clip LoraLoader MODEL → KSampler model LoraLoader CLIP → CLIPTextEncodeLoraLoader 参数包括lora_nameLoRA 文件名strength_modelLoRA 对模型的影响权重strength_clipLoRA 对文本编码的影响权重通常strength_model和strength_clip设置为一致的范围例如 0.6 到 0.8。数值过高会导致画面元素裂化数值过低则看不出效果。具体权重需要在生成后对比检查。6.3 ControlNet 的应用思路ControlNet 能进一步控制图像结构例如提取一张照片的人物骨架再让模型按骨架生成新画面。它用起来比 LoRA 复杂核心原因是需要选择合适的预处理器和模型文件。基本工作流通常包含加载参考图用预处理器提取边线或姿态把提取结果输入 ControlNet 模型加载器再把 ControlNet 的输出接到 KSamplerControlNet 的模型文件放在ComfyUI/models/controlnet目录。使用前需要确认 ControlNet 匹配的基础模型。比如 SD1.5 的 ControlNet 不能直接和 SDXL 主模型一起使用。这块属于进阶内容第一次部署先不用急。先把基础文生图跑通再逐步安装 ControlNet 相关自定义节点会顺很多。7. 常见问题与排查思路ComfyUI 使用中最大的拦路虎并不是节点连接而是各类报错。下面整理出高频问题和排查方向。7.1 常见报错与处理建议问题现象常见原因解决思路启动后无法访问 127.0.0.1:8188程序启动失败或端口被占用查看终端报错换端口--port 8189RuntimeError: CUDA out of memory显存不足降低分辨率、开启--lowvram、减小 batch size、关闭其他占用显存的软件torch.cuda.is_available()返回 FalseCUDA 版 PyTorch 未装好重新按 pytorch.org 的 CUDA 命令安装加载 Checkpoint 报错模型文件损坏、不完整删除文件重新下载核对下载文件大小图片整体发灰、很暗缺少合适 VAE给模型指定 VAE 文件出图一团糊、结构崩坏steps 太低、cfg 异常、模型参数不合适先恢复模型作者推荐参数再微调缺少自定义节点工作流使用的自定义节点未安装打开终端查看缺失节点名通过 Manager 安装unable to set system config diff.astextplainWindows Git 工具链配置异常检查是否安装了多个 Git用git config --global重建配置7.2 “节点在执行过程中发生错误”怎么定位搜索词里经常有 ComfyUI 的节点在执行过程中发生错误。 # comfyui error report。这其实是 ComfyUI 在节点执行异常时弹出的通用错误面板通常会有很多英文日志看起来吓人但定位方式是有套路的。当看到这个弹窗时不要急着重装 ComfyUI。按以下顺序排查看面板第一行找到是哪一个节点报错。看 error details 中的异常类型例如RuntimeError、ValueError、IndexError。找到其中包含的文件路径例如comfy/samplers.py或nodes.py里的某一行。区分问题来源如果异常来自自定义节点优先检查该节点是否缺少依赖或版本不兼容。如果异常来自生成过程很可能是显存不足、模型文件问题或者输入数据类型不对。如果异常发生在保存图片节点检查输出路径权限。例如信息中出现了CUDA error: out of memory那问题的答案就非常明确显存不够。如果把batch_size调小还不行就退到--lowvram模式或者换一个分辨率更低的模型方案。7.3 模型下载后为什么列表里看不到这种情况最常见的原因有三个文件后缀不是.safetensors或.ckpt。文件放在了错误目录。Checkpoint 却放进了loras那加载器当然看不到。ComfyUI 没有刷新。新增文件后点击加载器里的刷新按钮或者重启。有时下载工具会把文件名改成.download或中间加随机串也要注意去掉这类不完整的后缀。7.4 请求与显存相关的优化思路在本地生成大图时如果显存不足基本思路是“降低中间峰值”而不是单纯依赖低显存模式。可以尝试这些方式降低单张图片分辨率先生成小图再使用放大节点。减少 KSampler 的 batch 数。关闭浏览器其他标签页避免 GPU 任务互相抢占。在生成过程中不要同时打开多个本地应用。有条件时尽量选择 fp16 格式模型或量化后的模型文件。8. ComfyUI 使用与工程维护的最佳实践部署完成、第一张图出来后很多人会立刻沉迷于各种复杂工作流。但掌握工具的核心价值在于可复用、可复现、可排错。有些工程习惯越早养成越好。8.1 模型文件命名要规范模型下载页面常常自带很长的小作文命名。如果直接保留原文件名很容易出现两个大模型名相似但版本不同的问题。推荐格式[类别]_[画风或用途]_[版本信息]_[分辨率或作者].safetensors实际案例sdxl_fantasy_style_v2.safetensors sdxl_anime_realistic_mix_v1.safetensors也可以在目录里单独放一个README.txt记录模型来源、推荐触发词、推荐采样参数、下载日期。别看这个动作简单过两个月再回来找图时能省下大量考古时间。8.2 工作流的保存与备份ComfyUI 的界面工作流默认被嵌入到输出 PNG 图片中。如果你在某张图上做了满意的节点配置再次把图拖回 ComfyUI 界面通常可以还原工作流。这是它特别适合“复盘”的一个特性。建议做法是每个正式使用的工作流导出一份 JSON 文件放在专门目录。若找不到该目录可用ComfyUI界面的 Save/Export 功能。修改工作流前先复制一份保留旧版本。把“生成参数截图”和“提示词文本”保存到对应工作流说明中。8.3 环境依赖管理建议手动部署时Python 虚拟环境要把项目依赖和全局依赖隔离。不建议反复在同一个环境里“pip install 试一试”。如果自定义节点安装得越来越多环境依赖会慢慢混乱。如果你已经安装了很多自定义节点后出现各种奇怪报错可以创建一个新虚拟环境重新装依赖而不是在一个坏环境中持续修补。8.4 安全与合规边界本地部署不等于可以无限制使用。需要注意几个方面只从可信来源下载模型文件避免打开来源不明的.ckpt、.pt、.pth文件。这类文件理论上可能包含额外代码或漏洞。对下载的模型文件有条件时做一次病毒扫描。不要使用网上未经授权的模型进行商业用途注意模型作者的 License 说明。生成的内容如果用于公开发布或商业场景需要自行确认遵守相关法律法规和平台规范。涉及生成人物图片时要保持必要边界避免生成违法违规内容。8.5 性能与出图效率优化出图速度不仅取决于显卡还取决于模型选择。SDXL 生成 1024x1024 图片通常比 SD1.5 生成 512x512 慢很多。如果只是快速验证构图建议先用低分辨率、低 steps 跑小样确认效果后再用高质量参数跑正式图。如果经常生成相似风格图片还可以维护自己的提示词片段库。很多人以为提示词写得越长越好实际上 ComfyUI 并不依赖“魔法词堆砌”。把模型真正想要的触发词、负面词和画风描述分开管理比每次现场乱写要稳定得多。8.6 学会阅读错误而不是删除重来这是 ComfyUI 学习中最重要的一个思维习惯。看到红色错误、英文日志就慌乱卸载往往是浪费时间。ComfyUI 的错误结构非常有特色只要耐心阅读异常栈前几行大多数问题定位都不难报错节点里包含自定义节点名 → 去安装对应插件。报错里出现 checkpoint 加载路径 → 检查模型路径和后缀。报错里出现 CUDA out of memory → 降低资源占用。报错里出现 import 某个模块失败 → 检查 requirements 是否装全。把错误日志当成导航地图而不是拦路虎排错速度会成倍提升。9. 下一步学习路线当你完成了上述所有步骤并且已经能独立跑通“文生图、LoRA 风格切换、ControlNet 结构控制”三类典型流程后ComfyUI 的大门才算真正打开。接下来可以继续深入的方向包括学习如何导出并复用别人分享的工作流分析别人为什么在某个位置加节点。学习 batch 批量生成和图像放大节点。了解不同采样器和调度器对细节、光影的影响。学习 ComfyUI 的 API 模式结合 Python 脚本调用本地生成能力。尝试把生成结果接入自己的小工具或后端服务完成真正意义上的“模型即服务”。本地部署 AI 生图模型不是一锤子买卖。它更像一套可持续迭代的工具链每一次换模型、加插件、优化参数都会加深你对生成原理和工程实践的理解。如果你正在从 WebUI 转过来或者第一次接触 ComfyUI建议先从简单的 Checkpoint 加载和默认工作流开始。先不用急着下载几十个自定义节点也不用盲目追求复杂的高清修复流程。把一条基础链路吃透后面再加节点时会轻松很多。如果今后在某一层卡住了比如显存溢出、节点缺失、模型文件加载失败记住回到终端看日志回到官方文档查配置回到输入材料确定你的模型文件放在哪里。这套排查逻辑比复制任何一张工作流图片都管用。
