在 ComfyUI 上跑本地部署的 AI 生图模型难点从来不是“输入一句话然后点运行”而是整条链路是否顺畅环境有没有配好模型文件放没放对位置工作流节点为什么报错显存不够时该怎么降级。这里把 ComfyUI 本地部署从环境准备到模型配置再到底模选择、工作流运行、错误排查写清楚适合第一次接触 ComfyUI、想脱离在线平台在本地跑生图的开发者。ComfyUI 是一套基于节点的 AI 图像生成流程工具核心价值是把“底模加载、提示词编码、采样、解码、保存图片”拆成可视化节点。相比 Stable Diffusion WebUI 那种整体操作页面ComfyUI 更强调流程控制哪些模型参与计算、中间结果如何传递、每一步用什么采样器都可以显式看到和修改。本地部署则是把整个推理链路全部放在自己电脑上执行不依赖远程接口也不会上传图片到第三方服务。1. ComfyUI 本地部署到底在解决什么问题1.1 ComfyUI 的本质节点式流程引擎在 ComfyUI 里一次生图并不是一个黑盒操作而是由若干节点串联组成的有向流程。典型文生图流程包括CLIP 文本编码器把自然语言提示词转换成模型能理解的条件向量。采样器在潜在空间里反复去噪逐步生成图像特征。VAE 解码器把潜在空间的张量还原成像素级图片。图像保存节点把结果写入磁盘。这些节点之间有输入输出连接上游节点的输出会成为下游节点的输入。理解这一点后面调试节点报错就有一个基本思路报错本质上是某个节点的输入类型、形状或依赖环境不满足计算条件而不是“整个软件坏了”。1.2 本地部署与在线 API 的核心差异在线生图工具的优点是开箱即用但存在几个现实问题单张图片按次计费批量实验成本高提示词和生成图片会经过服务端免费额度往往限制分辨率和生成次数无法自由切换底模无法深度定制工作流。本地部署的价值在于生成成本只取决于电费和硬件损耗反复调参没有额外费用。数据不出机器适合处理个人素材或敏感内容。可以自由更换 Checkpoint、LoRA、ControlNet、采样器和 VAE。可以把工作流导出成 JSON 文件在团队内分享复现。代价也很明显需要自己处理 Python 环境、显卡驱动、模型文件下载、内存管理、报错排查。本地部署不是“装完就能一直稳定运行”它需要维护。1.3 一张本地生图请求的完整链路当你在 ComfyUI 界面点击“运行”后实际发生的事情可以拆成五步前端把所有节点和连线序列化成执行图。后端根据节点依赖关系决定执行顺序。加载底模到显存CLIP 模型负责文本编码。采样器按设定步数完成去噪过程期间产生中间张量。VAE 解码得到图片前端展示缩略图后端写入 output 目录。理解这条链路就能知道排查时该看哪一层。例如采样器报错通常是显存不足或参数越界VAE 解码报错往往是 Latent 尺寸与模型不匹配模型加载失败则要检查文件路径和格式。2. 动手前先检查机器硬件与软件基线2.1 显存是本地生图最重要的资源本地生图最先卡住的一定是显存而不是 CPU 或内存。所以选型第一步是确认自己的显卡型号和显存大小。显存大小建议场景需要注意的问题4GB 以下跑早期小底模、极低分辨率测试生成速度慢容易 OOM不建议作为主力6GB 至 8GBSD 1.5 系列底模、简单 LoRA分辨率控制在 512 到 768 附近谨慎开高分修复10GB 至 12GBSDXL 底模、中等分辨率出图大图建议分步生成不要一次性拉满16GB 以上SDXL、较大型号模型、批量实验相对从容但仍要关注显存峰值24GB 及以上部分新架构大模型、复杂工作流适合本地研究受控实验场景这里没有给出具体某款显卡的绝对性能结论因为驱动版本、PyTorch 版本、模型量化方式都会影响结果。但原则是通用的显存决定单次能跑多复杂的图显存不够时首先要降分辨率、减批量而不是换更好的提示词。除了显存内存建议 16GB 起步32GB 会更舒服。模型文件本身会占用磁盘单是底模加 VAE 加 LoRA 就可能超过 10GB所以磁盘剩余空间要留足。2.2 Python、Git 和显卡驱动的版本要求ComfyUI 本体是 Python 项目手动部署时建议使用 Python 3.10 到 3.11 之间的稳定版本。太老的 Python 可能装不上新版依赖太新的 Python 又可能遇到部分依赖尚未适配的情况。如果用的是社区整合包通常已经内置了对应版本不建议再手动改。显卡驱动要能支持你安装的 CUDA 版本。更务实的做法是先装好显卡驱动再用 PyTorch 官方提供的安装命令安装对应 CUDA 版本的 torch。不必单独安装完整 CUDA Toolkit除非你确实需要编译自定义扩展。Git 用于拉取 ComfyUI 源码和部分插件Windows 上安装 Git 后要确认命令行里能直接输入 git 而不报错。如果安装 Git 时没有把目录加入 PATH后续克隆仓库会提示找不到命令。2.3 部署前环境检查清单检查项检查方法通过标准显卡驱动nvidia-smi能显示显卡型号和驱动版本Pythonpython --version版本在推荐范围内Gitgit --version能正常输出版本号磁盘空间查看系统盘和工作盘剩余至少预留 20GB 以上网络能访问模型下载源或使用可用镜像模型下载不中断这个清单不止在首次安装时有用。每次升级版本、更换模型、迁移机器时都建议重新核对一遍很多莫名其妙的报错源头就是环境基线漂移。3. 两条安装路线社区整合包与手动部署3.1 路线一社区整合包五分钟跑通社区常见的“秋叶一键整合包”本质上把 Python 环境、ComfyUI 本体、常用插件、模型下载工具和启动脚本打包在一起。好处是安装门槛低适合刚接触本地生图、不想折腾环境的人。启动包内程序后通常会自动打开浏览器进入 ComfyUI 页面。使用整合包要注意几点别把模型文件夹和整合包本体放在系统盘狭窄路径路径中尽量别有中文或空格。整合包版本会持续更新下载前确认版本说明不要盲目追求最新。整合包方便跑通但遇到环境级报错时内部结构不透明排查难度会高一些。整合包适合用来验证“我到底要不要入坑本地生图”。如果已经确定要长期使用并且需要自定义依赖、二次开发节点建议逐步转向手动部署。3.2 路线二手动部署掌握细节和排错能力手动部署并不是更高级而是让你理解每个依赖存在的意义。先把 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)后再安装 PyTorch。第一次装环境最容易错的地方就在这里直接执行pip install -r requirements.txt会默认安装 CPU 版或依赖源不匹配的 torch。推荐先按 PyTorch 官方命令安装 GPU 版本比如pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121这里的 cu121 对应 CUDA 12.1实际操作前要确认自己的驱动支持的 CUDA 版本并访问 PyTorch 官网获取当前推荐命令。装完 torch 后再装 ComfyUI 的其余依赖pip install -r requirements.txt依赖安装完成后Windows 下可以直接运行python main.pyLinux 或 macOSpython main.py默认情况下 ComfyUI 会在 127.0.0.1:8188 启动服务。注意虚拟环境创建后每次使用都要先激活。如果提示找不到 torch优先检查是不是忘记激活虚拟环境而不是怀疑安装命令写错。3.3 启动 Web 界面并进行首次自检启动后浏览器打开 http://127.0.0.1:8188 能看到画布式界面说明服务正常。可以再做两个自检看控制台日志有没有明显异常例如导入节点失败、缺少依赖。暂时不上传模型先点一下默认工作流的执行按钮。此时会因为没有底模而报错但这本身是一种验证说明前端到后端已经连通错误能正确回传。如果浏览器打不开页面优先检查端口是否被占用再用python main.py --port 8189指定其他端口测试。4. 模型文件目录、类型和底模选择4.1 模型目录结构与文件类型ComfyUI 能识别的模型文件放在 models 目录下不同用途的模型要放进对应子目录。目录放错是新手最常见的“模型找不到”原因。模型类型默认目录文件格式举例底模 CheckpointComfyUI/models/checkpoints.safetensors、.ckptLoRAComfyUI/models/loras.safetensorsVAEComfyUI/models/vae.safetensors、.pt文本编码器相关ComfyUI/models/clip.safetensorsControlNetComfyUI/models/controlnet.safetensorsEmbeddingComfyUI/models/embeddings.pt、.safetensors自定义节点辅助模型ComfyUI/models/ultralytics 等按插件说明放置完整目录结构的简化示意ComfyUI/ ├─ models/ │ ├─ checkpoints/ │ ├─ loras/ │ ├─ vae/ │ ├─ controlnet/ │ └─ embeddings/ ├─ output/ ├─ custom_nodes/ └─ main.py4.2 如何选择合适底模和文件格式选择底模要考虑三点自己显卡显存、想要的内容风格、模型社区生态。常见选择逻辑如下显存不大、追求稳定、生态成熟选 SD 1.5 系底模资源多、LoRA 丰富。显存 10GB 以上、追求细节和提示词理解选 SDXL 系底模或基于其微调的版本。想要最强文本理解能力和超高画质同时显存足够大可以尝试新架构大模型。模型文件优先下载 .safetensors 格式。它和 .ckpt 相比没有 Python pickle 反序列化风险安全边界更清晰。下载时还要确认文件名和实际底模是否一致。很多模型站会把修复版、fp16 版、分开的 VAE 放在同一页面新手容易下载错文件。注意不要只看文件名大小判断模型行不行也不要因为某个帖子热度高就下载来源不明的模型文件。模型下载尽量选择官方仓库或可信的模型托管平台避免文件在传输过程中被篡改。4.3 验证模型被 ComfyUI 识别的两种方式第一种方式最简单刷新浏览器页面后双击空白处打开节点搜索框搜索 Load Checkpoint在节点下拉列表里能看到刚放入的底模文件名。第二种方式更精确点击界面右侧的刷新按钮如果没有生效则重启 ComfyUI 进程。如果你刚放模型时服务还开着文件列表不会自动更新。如果模型列表始终看不到文件检查文件是否真的放在 checkpoints 目录还是误放到了 output 目录。文件后缀是否正确ComfyUI 是否能识别该后缀。当前运行的是不是整合包自带的另一套 ComfyUI 路径。5. 跑通第一张图文生图工作流5.1 默认工作流里的核心节点ComfyUI 自带一个最基础的工作流包含以下节点Load Checkpoint加载底模同时输出模型、CLIP、VAE 三路结果。CLIP Text Encode正向提示词输入你想画的内容。CLIP Text Encode负向提示词输入你想避免的内容。Empty Latent Image定义生成图像的宽高和批量数量。KSampler执行采样去噪是出图质量的关键节点。VAE Decode把采样结果的潜在张量还原成像素图片。Save Image保存图片到 output 目录。默认界面里 Load Checkpoint 节点已经连接到后续节点。双击画布空白处可以调出节点搜索框手动新增节点后把对应输出口拖到目标输入口即可完成连线。5.2 关键参数的调整思路以 KSampler 为例最主要参数如下参数含义调整建议seed随机种子固定后可复现同一构图换值可换构图steps采样步数一般 20 到 30过多不一定更好cfg提示词引导强度常见 5 到 8过高画面会过饱和sampler_name采样器算法不同采样器风格不同需要实测scheduler调度器和采样器配套使用不要随意组合每张图生成前先固定 seed方便对比不同参数带来的效果。修改参数时一次只改一个变量否则无法判断是哪个参数影响了结果。Empty Latent Image 里的宽高直接决定显存占用。同一底模下1024x1024 的显存占用会明显高于 512x512。出现 OOM 时第一步就是缩小这里的宽高。CLIP Text Encode 的正向提示词不要只写一堆风格化形容词建议包含主体内容、环境、材质、构图和光影方向。负向提示词用于排除常见质量问题类似“模糊、低质量、变形”这类描述但不同底模对负向提示的敏感程度不同。5.3 运行和验证生成结果点击界面上的“运行”按钮后节点边框会变亮控制台会输出进度信息。等 KSampler 和 VAE Decode 执行完画布上会出现预览图同时图片会自动保存到 output 目录。生成第一张图的预期结果没有红色报错节点。控制台没有 Exception 或 Error 关键字。output 目录里出现新的 PNG 文件。图片内容和正向提示词相关而不是纯随机噪点。如果图片是纯色块或明显花屏优先检查 VAE 是否被加载正确以及底模是否损坏。部分底模下载不完整时也能加载但解码出来就是废图。6. 本地生图常见报错排查从节点错误报告入手6.1 节点在执行过程中发生错误先看 error reportComfyUI 在节点出错时会在前端弹出错误面板内容类似下面这种格式节点在执行过程中发生错误。 # ComfyUI Error Report ## Error Details - Node Type: KSampler - Exception Type: RuntimeError - Exception Message: CUDA out of memory.这段报错其实已经给出了关键信息是哪个节点出错、什么异常类型、具体消息是什么。不要只看到红色界面就慌先按顺序做三件事看 Node Type确定是哪一类节点。看 Exception Message判断是显存、类型还是路径问题。看控制台完整堆栈把出错行附近的上下文读出来。错误现象优先检查方向KSampler 执行时 CUDA out of memory显存不足降分辨率或减批量CLIP Text Encode 提示类型不匹配检查模型输出端口连接是否正确模型文件加载失败检查路径、文件名、目录和下载完整性VAE Decode 报形状错误检查 Latent 分辨率与 VAE 是否匹配多数节点错误不是 ComfyUI 本身坏了而是工作流连接或参数没有满足节点约束。6.2 CUDA out of memory 的降载方案CUDA out of memory 是本地生图最高频错误。产生原因不只是“显存小”还包括当前分辨率和批量一次吃太多显存以及后台其他程序占用显存。按代价从低到高的处理顺序关闭占用显存的其他程序例如浏览器硬件加速、其他 AI 工具、录屏软件。把 Empty Latent Image 的宽高从 1024x1024 降到 768x768 或 512x512。把 batch_size 降回 1。重启 ComfyUI 进程释放被缓存占用的显存。使用低显存运行模式启动。低显存模式下启动的命令示例python main.py --lowvram这个参数会把部分模型放在内存中按需加载到显存牺牲速度换取不爆显存。但是低显存模式不适合所有场景如果后续要快速迭代还是建议优先从分辨率入手。6.3 模型加载失败与配置不生效模型加载失败时控制台通常提示类似Ckpt Not Found或 model not found。这时检查顺序文件是否在 models/checkpoints 目录下。文件名带中文或特殊符号时ComfyUI 有时可识别但为了减少问题建议统一改成英文小写文件名。文件是否下载完整半截文件实际大小为 0 或明显小于模型页面标注大小。是否把 LoRA 文件误放到了 checkpoints 目录然后试图用 Load Checkpoint 加载。另一个容易忽略的问题是修改了配置或替换了模型后不重启 ComfyUI某些缓存不会自动刷新。遇到“配置不生效”类问题先重启进程再试。6.4 环境安装阶段的 git 与 pip 报错手动部署时常见一类环境报错例如安装 Git 后在 Windows 命令行执行 git 时提示unable to set system config diff.astextplain.textconv ...这是因为安装了某些 Git 工具包时系统级配置里指向了不存在的组件。处理方式通常是重装 Git 时选择默认组件或在 Git 安装目录里补齐缺失文件后重新配置。严格来说这不是 ComfyUI 的报错而是 Git 环境问题却会挡住后面的 composer 步骤。pip 安装依赖时常见问题是网络超时或下载源较慢。可以在 pip 后加参数指定镜像源pip install -r requirements.txt -i https://pypi.org/simple如果所处网络环境访问官方 PyPI 不稳定可以换成国内公开 pip 镜像。这类镜像地址写在自己的项目说明里即可不涉及额外工具。注意看到安装报错时先读完整报错行。很多新手被红色文本吓到直接把最后两行复制到聊天工具里提问但真正的原因往往在报错中间位置的依赖包名或文件路径上。7. 从能出图到长期稳定的工程化建议7.1 工作流文件如何保存、分享与迁移ComfyUI 的每个工作流都可以保存为 JSON 格式。点击界面保存按钮后会得到包含节点结构、参数、连线关系甚至部分提示词信息的文件。保存工作流时有几个建议分业务保存不要把所有实验都堆在一个工作流里。文件名里带日期、底模名称和主题例如portrait_sdxl_20250120.json。首次分享给他人前确认对方机器上是否有对应模型和自定义节点。迁移到新环境时先安装工作流依赖的自定义节点再打开 JSON。很多“工作流分享后打不开”的问题不是 JSON 损坏而是加载者缺少对应节点插件或模型文件。ComfyUI 在加载时会提示缺失节点按提示安装后再重新加载即可。7.2 插件、ControlNet 与 LoRA 的扩展方向跑通文生图后扩展方向通常有三个。第一个方向是 LoRA。LoRA 是小型可插拔风格或人物适配层文件小、切换快。ComfyUI 里有专门加载节点不改变底模效果只增加特定风格。如果在社区看到喜欢的 LoRA下载后放入 loras 目录在正向 CLIP Text Encode 之前串联 LoRA 加载节点。第二个方向是 ControlNet。它可以锁定构图、姿势、深度或边缘信息配合底模做可控生成。ControlNet 文件更大、加载更占显存对新手来说建议先把基础文生图稳定跑通再试。第三个方向是保存并模板化自己的常用工作流。等到某套参数能稳定输出自己满意的图就把它保存为基础模板后续调参都从这个模板出发。7.3 本地部署的维护与备份清单本地部署使用时间越长越需要维护。建议留存一份发布前检查清单检查项说明磁盘剩余空间output 目录写满前及时清理或归档模型文件记录记录已下载模型名称、来源、用途避免重复下载自定义节点版本升级前确认新版本是否和当前 ComfyUI 兼容备份工作流 JSON重要工作流存储到独立目录并纳入备份启动日志遇到问题时先看启动日志定位依赖加载失败的原因显存与温度长时间批量跑图时留意显卡温度和功耗生产或长期使用场景还应该考虑把模型文件从系统盘迁移到大容量数据盘避免同时装多个底模把系统盘写满。output 目录也应定期清理或用脚本按日期归档防止图片文件越来越庞大。对于学习阶段的新手最有价值的练习是手动部署一遍 ComfyUI然后从默认工作流开始逐个修改 KSampler 参数观察输出变化。不要一上来就下载几十个插件和高复杂工作流那样既难排查问题也难以真正理解每个节点在做什么。等到能熟练分析黄色报错条和 error report 里的节点类型后再进入 ControlNet、LoRA 和更复杂模型的扩展阶段本地部署这条路才算真正走稳了。