1. 项目概述聊聊 ComfyUI 目录这件事最近在折腾 ComfyUI发现好多新手朋友卡在了同一个地方——不是工作流不会搭也不是节点不会连而是根本搞不清楚模型该往哪个文件夹里放。模型下了一堆结果界面上一个都加载不出来或者把 LoRA 丢错了地方训练好的风格死活不生效。这种问题我见得太多了今天就专门写一篇把 ComfyUI 的目录结构彻底讲明白。先说清楚 ComfyUI 是什么。它是一个基于节点式Node-Based界面的 AI 绘画工具和 WebUI 那种表单填写式的操作逻辑完全不同。你把不同的功能模块加载模型、提示词、采样器、解码器像搭积木一样连起来每条连线就是一个数据流。这种设计让高级用户能做非常精细的控制但也意味着——你对文件系统的理解直接决定了能不能玩得转。这篇内容适合所有 ComfyUI 用户尤其是刚从 WebUI 过来、或者刚接触 AI 绘画的新手。我会从根目录开始逐个文件夹讲清楚是干什么用的、可以放什么、不应该放什么然后专门讲模型文件的放置规则最后附上常见问题的排查方法。全文基于 ComfyUI 官方原版目录结构秋叶整合包、改版包基本大同小异个别差异我会单独提。看这篇文章你可以完全跟着路径操作不会迷路。2. ComfyUI 目录结构全景速览2.1 根目录下都有什么先看一张目录总览这是在官方版 ComfyUI 解压之后的完整根目录结构ComfyUI/ ├── main.py ├── requirements.txt ├── pyproject.toml ├── comfy/ ├── comfy_extras/ ├── nodes.py ├── custom_nodes/ ├── models/ ├── web/ ├── web_custom_versions/ ├── input/ ├── output/ ├── user/ ├── temp/ ├── utils/ ├── script_examples/ ├── tests/ └── .github/刚拿到手的 ComfyUI 大概就是这么个布局。不少人第一次打开main.py就直接用 Python 运行其实这没问题——你可以通过python main.py来启动程序关键是要理解整个程序是围绕comfy/这个核心包展开的其他的文件夹各司其职。2.2 官方版与整合包目录差异网络上流行的秋叶一键整合包目录结构会稍有不同常见的区别是多了一个启动器.exe或A绘世启动器.exe用来管理环境Python 运行环境打包在单独的python/目录里有时把models/里的重要模型文件夹单独提取到显眼位置但核心的目录逻辑是一致的——models/下还是那五个标准子目录custom_nodes/还是放插件的地方output/还是出图的位置。所以不管你用的是官方版还是整合包下面要讲的内容都能用上。3. 核心代码目录详解3.1 comfy/ 目录程序的心脏comfy/是整个 ComfyUI 的核心代码库包含了所有底层实现比如数据流图的构建与执行引擎各类采样器Sampler的实现模型加载与缓存机制各种节点Node的基础操作逻辑正常使用 ComfyUI 时你不需要直接动这个目录。尤其是刚入门的朋友千万不要去改这里的代码否则很容易把整个工具搞崩溃。除非你想二次开发或者研究源码不然这里对你来说就是个黑盒。3.2 comfy_extras/ 与 nodes.pycomfy_extras/存放的是一些额外节点实现比如 LayerDiffuse、AnimateDiff 相关的扩展逻辑。nodes.py则是标准节点的定义文件ComfyUI 的核心操作——加载模型、VAE 解码、图像保存等——都在这里面。这两个文件在运行时会被自动加载一般情况也不需要手动修改。你只要知道它们存在就行了属于知道就好的部分。3.3 custom_nodes/ 目录插件的大本营这个目录值得仔细讲。custom_nodes/就是 ComfyUI 的插件目录非常类似于 Stable Diffusion WebUI 里的extensions/目录。你需要额外功能比如 ControlNet 预处理、视频生成、局部重绘增强等就是把插件克隆到这个文件夹里。使用 Git 克隆插件cd custom_nodes git clone https://github.com/某用户/某插件.git装完插件后重启 ComfyUI 才能生效。部分插件还需要安装额外的 Python 依赖通常是在插件目录下执行pip install -r requirements.txt需要注意不是所有插件都兼容最新版 ComfyUI也不是所有插件之间都能和平共处。装得太多、装得太杂经常会出现启动报错、节点加载失败的情况。我的建议是一开始只装你真正需要的几个逐个验证没问题再继续加。3.4 web/ 与 web_custom_versions/ 目录web/是 ComfyUI 的前端资源目录包括界面布局的 HTML/CSS/JavaScript 代码静态资源文件前端组件一般情况下你也不动它。改前端代码属于高阶玩法比如定制界面主题、调整交互逻辑这需要前端开发能力不是普通使用者的范畴。web_custom_versions/是官方留给自定义前端版本的目录。你可以把整个替换掉的前端版本放进去然后在启动时通过参数指定使用哪一套界面。这个功能更适合有开发背景的朋友普通用户基本接触不到。4. models/ 目录重中之重4.1 标准子目录一览进入models/目录你会看到这样一批子文件夹按官方版标准models/ ├── checkpoints/ ├── clip/ ├── clip_vision/ ├── configs/ ├── controlnet/ ├── diffusers/ ├── embeddings/ ├── gligen/ ├── hypernetworks/ ├── loras/ ├── photomaker/ ├── style_models/ ├── unet/ ├── vae/ └── vae_approx/每个文件夹有明确的用途。理解它们才能避免 模型加载不出来 报错找不到文件 之类的问题。4.2 大模型Checkpoint放哪里大模型Checkpoint也叫主模型应该放在models/checkpoints/目录下。这是我们最常说的底模比如 SD 1.5、SDXL、以及各种社区微调模型。在这个目录下你可以直接参考官方默认的加载路径。文件格式通常为.safetensors或.ckpt其中.safetensors更安全加载速度也略快现在绝大多数新模型都是这个格式。在 ComfyUI 界面中通过Load Checkpoint节点加载模型时下拉列表里显示的就是models/checkpoints/目录下的所有模型文件。如果你是从 C 站Civitai或 Hugging Face 下载的大模型直接放到这里就可以。你还可以建子目录比如models/checkpoints/sdxl/下拉列表会加一层层级显示方便管理大批量模型。4.3 VAE 模型放哪里VAE 模型放在models/vae/目录下。VAE变分自编码器负责把潜空间Latent Space数据解码成像素图像。官方原版 ComfyUI 在加载 Checkpoint 时会自动尝试从检查点文件内部提取 VAE所以早期不太需要单独下载 VAE。但如果你用的人物模型、场景模型自带的 VAE 效果不好比如画面发灰、色彩偏淡就需要手动加载一个训练好的 VAE。用法在Load VAE节点中选择models/vae/中的文件即可。有些模型会内置 VAE有时会单独提供 VAE 文件下载后同样扔进vae/目录。4.4 LoRA 模型放哪里LoRA 模型放在models/loras/目录下。LoRA 是一种轻量化的微调模型通常体积在几十到几百 MB 之间用于给大模型附加某种风格、角色特征或者构图偏好。ComfyUI 的Load LoRA节点默认扫描的就是loras/目录所以你下载的.safetensorsLoRA 文件丢进去就好。使用 LoRA 时的常见坑路径正确但界面上没显示 → 没有刷新节点列表重启前端或点刷新按钮。某些 LoRA 是基于特定底模训练的比如只适配 SD 1.5 或只适配 SDXL用错底模容易产生畸变、过曝等情况。LoRA 权重Strength一般设置在 0.5~1.0 之间拉太高容易崩图。4.5 ControlNet 模型放哪里ControlNet 模型放在models/controlnet/目录下。ControlNet 是用来控制构图的模型比如提取线稿、深度图、姿态骨骼等然后引导生成结果遵循你给的结构。在 ComfyUI 中Load ControlNet Model节点会从这个目录读取模型文件。需要注意ControlNet 有很多种版本针对 SD 1.5 的 ControlNet针对 SDXL 的 ControlNet针对不同预处理器的专用模型如 Canny、Depth、OpenPose如果你同时使用多个底模建议在controlnet/下建立子目录比如sd15/、sdxl/方便区分不至于搞混。4.6 Embedding文本嵌入放哪里Embeddingtextual inversion模型放在models/embeddings/目录下。Embedding 是用于给提示词注入特定概念的轻量文件后缀通常为.pt或.safetensors。使用时需要在提示词中以embedding:文件名的方式引用比如embedding:bad_prompt_v2注意不要带后缀名ComfyUI 会自动匹配。Embedding 的实际生效阈值和底模训练时的底模相关挂在完全不同的底模上可能会出现没效果或效果异常的情况这一点新人容易踩坑。4.7 UNET、CLIP、CLIP Vision 等其他目录较新版本的 ComfyUI 支持直接加载单独的 UNET 模型文件大型扩散模型的核心组件放在models/unet/目录下。当显存不够时把 UNET 单独拆出来加载可以显著降低显存占用。CLIP 模型文本编码器放在models/clip/目录用于控制文本理解能力。一般不需要单独管理但加载某些特定工作流时会用到。CLIP Vision 模型放在models/clip_vision/目录主要用于图像提示词Image Prompt、风格迁移等涉及理解图像的工作流。如果你在加载工作流时出现找不到CLIPVisionLoader对应文件就去这里看看有没有对应的.safetensors。4.8 其他模型目录Diffusers、Style Models、GLIGEN、PhotoMaker 等models/diffusers/放 Diffusers 格式的完整模型目录通常是从 Hugging Face 下载的文件夹格式而不是单个文件。models/style_models/放风格化模型比如用于风格迁移的 SD 1.5 风格模型。models/gligen/GLIGEN 模型用于在生成时指定物体在画面中的位置属于比较小众的功能。models/photomaker/PhotoMaker 是最近比较火的一个模型用于把照片中的人脸特征迁移到生成结果中。对应文件放在这里。models/hypernetworks/老牌 WebUI 常用的一种模型类型ComfyUI 也保留了这个目录但用的用户比较少。models/configs/模型配置文件一般用于适配不同结构的模型官方默认有一些配置不需要频繁改动。models/vae_approx/VAE 近似模型用于某些特定场景下的快速解码。这个目录很少需要手动放文件。5. 输入与输出文件目录5.1 input/ 目录放参考图的地方input/目录是 ComfyUI 用来读取外部输入图片的默认目录可以放 ControlNet 的参考图、图生图的源图、局部重绘的蒙版图等等。只要在加载图像节点Load Image里就能从这里的文件列表中做选择。一个细节中文文件名或带空格的文件名可能在部分版本中导致读取异常建议统一用英文加下划线命名比如ref_canny.png。另外不要直接把几十张图全丢进去文件太多会导致选择列表非常卡顿。5.2 output/ 目录出图的默认位置output/是 ComfyUI 默认的图像输出目录。每次生成的图片都会以 PNG 格式保存在这里。当然你可以通过 Save Image 节点修改前缀和子目录。保存格式上官方默认保存 PNG但如果你想要 JPG、WebP也可以通过自定义节点实现。对批量出图、跑测试的朋友来说定期清理output/里的内容非常重要不然积攒几个月几十个 G 的图片就能把一个盘塞满。5.3 temp/ 目录临时文件存放地temp/用于存放程序运行时的临时文件比如预览缩略图、临时缓存的数据等。这个目录可以定期清理程序会在需要时重新生成。不建议把重要内容放这里重启后很可能被清空或覆盖。6. 其他重要文件与目录6.1 main.py 与启动流程main.py是 ComfyUI 的主入口。默认在根目录执行python main.py程序会启动一个本地服务默认监听localhost:8188。打开浏览器访问http://127.0.0.1:8188就能看到 ComfyUI 界面。启动时可以通过参数调整一些行为比如python main.py --port 8189 python main.py --cpu python main.py --lowvram--port修改端口号--cpu强制用 CPU 运行很慢只有测试时才建议--lowvram低显存模式缓解爆显存问题这些参数对排查环境问题会很关键。6.2 user/ 目录你的工作区user/目录保存的是每个用户的前端配置、工作流草稿、设置项等。官方版中默认的 ComfyUI 工作流就存在user/default/workflows/目录下。也就是说你想备份我的工作流需要备份这个user/目录你想重置界面布局和设置删除对应用户目录下的配置或者整个user/目录谨慎操作即可恢复默认。6.3 utils/、script_examples/、tests/ 目录utils/内部工具脚本一般不需要去碰。script_examples/示例脚本展示如何通过 API 调用 ComfyUI适合想写自动化脚本的用户参考。tests/测试代码开发者才会用到。7. 目录管理与实操建议7.1 下载模型后界面看不到的排查流程很多人下载模型后刷新了很多次界面还是看不到模型文件。常见原因有几类模型下载后没放在对应的子目录。比如把 Checkpoint 放到了loras/里那 Load Checkpoint 里当然看不到。模型文件的后缀格式不支持。ComfyUI 主要支持.safetensors、.ckpt、.pt部分特殊格式无法识别。文件名太长了。Windows 系统默认路径长度限制在 260 个字符左右如果你把模型放在很深的目录里再加上超长文件名就容易出现读取失败。这时把模型放到更浅的路径或者缩短目录名问题通常就解决了。没有刷新前端。ComfyUI 的文件列表不会自动刷新加载节点里找不到新文件时点一下刷新按钮通常是节点的刷新图标或重启一下前端。7.2 硬盘空间规划与目录瘦身这里想给你一个重要的建议不要把所有模型都堆在默认目录里。很多朋友下载的时候直接全部放入 ComfyUI 目录最后硬盘爆了、启动变慢、查找困难。更合理的方式使用extra_model_paths.yaml配置文件把模型目录映射到独立的大容量磁盘上。比如把大模型放在 D 盘的一个公共模型库中通过配置文件让 ComfyUI 自动读取。定期用目录大小分析工具查看哪些目录占空间大及时清理不需要的模型。对常用的模型可以多建子目录分类比如checkpoints/写实/、checkpoints/二次元/方便定位。extra_model_paths.yaml的基础格式大致如下基于实践总结my_models: base_path: D:/AI/Models checkpoints: checkpoints loras: loras vae: vae controlnet: controlnet配置好之后ComfyUI 会把D:/AI/Models下的相应子目录也当作模型目录的一部分来扫描。这样一来模型文件不需要复制或剪切到 ComfyUI 目录节省大量重复空间。7.3 云盘同步与多设备协同如果你有 NAS 或者使用同步网盘可以考虑把models/目录单独同步。需要留意的是大文件多、碎文件多的情况下同步容易产生冲突或半成品文件。模型文件常常有几个 G断点续传不到位时经常出现文件大小看起来差不多但实际不完整的情况。加载模型报错文件损坏、Unexpected end of file时大概率是下载不完整优先排查文件大小和哈希值。8. 常见问题与排查技巧8.1 常见问题速查表现象常见原因解决方案加载节点里找不到新模型文件放错目录 / 前端未刷新放入正确目录并刷新或重启 ComfyUI加载 Checkpoint 报错 unexpected key模型文件损坏或后缀错误重新下载文件选用.safetensors格式启动时报缺少自定义节点插件未安装或依赖缺失安装完整插件安装 requirements.txtControlNet 加载失败模型与底模版本不匹配确认模型对应 SD1.5 还是 SDXLLoRA 无效或导致画面崩坏权重过高或底模不适配降低权重换用适配底模出图全黑/全灰VAE 有问题或采样参数不当检查 VAE 加载与采样器设置端口被占用8188 端口有其他程序用--port参数更换端口模型文件存在但下载不完整下载工具断流/文件损坏校验文件哈希重新下载8.2 排查技巧实录在实际操作中我建议大家养成两个习惯。第一个习惯是启动时看控制台日志。ComfyUI 的启动日志会打印当前扫描到了多少模型、哪个目录下加载了哪些文件、插件是否有导入报错。如果你发现模型没有被识别第一时间看日志里有没有相关提示很多时候比盲猜目录快得多。第二个习惯是重命名文件时务必保留后缀名。很多人下载模型后喜欢把文件名改成中文描述但不小心把.safetensors尾部删掉或改成了.safetensors.txt程序自然读不到。Windows 默认隐藏已知文件的扩展名这种情况非常常见也特别容易被忽略。8.3 长文件名与路径过深问题Windows 下文件路径长度上限是 260 个字符较新系统可以开启长路径支持如果你把 ComfyUI 解压到一个很深的目录再把模型放到几层子目录里文件名又比较长就很容易触发系统限制。轻则文件无法访问重则 ComfyUI 扫描时直接崩溃。处理方案很简单把 ComfyUI 放在盘的根目录下比如D:\ComfyUI而不是D:\Downloads\AI Tools\ComfyUI-fixed-version。模型文件名不要超过合理长度中文名过长的也建议简化。8.4 安全与备份建议最后想说一点关于安全的事。AI 绘画圈子里每天都有新模型下载来源鱼龙混杂。务必要注意.ckpt或.safetensors文件本质上是序列化数据存在嵌入恶意代码的可能性虽然.safetensors格式设计上不包含代码执行逻辑相对更安全但依然不能完全掉以轻心。尽量从官方渠道、大型模型站下载模型对来路不明的整合包私密模型保持警惕。对重要的自定义节点和配置文件定期备份新手折腾插件时建议先把user/下的配置目录做个备份避免出现问题后无法恢复。备份我一般这样做把user/和custom_nodes/这两个目录压缩一下放到另外一个磁盘或者使用同步网盘归档。如果插件更新后出了问题直接回滚目录就行。9. 实操总结与我的个人经验写到这里ComfyUI 的目录结构和模型放置规则基本已经覆盖全了。用几句话概括核心大模型 Checkpoint 放models/checkpoints/VAE 放models/vae/LoRA 放models/loras/ControlNet 放models/controlnet/Embedding 放models/embeddings/插件放custom_nodes/参考图放input/出图结果放output/这几个位置记熟ComfyUI 的日常使用就不会再出现文件找不到之类的基础问题。我个人用了 ComfyUI 很长时间最明显的感受是目录管理做得好整个工具用起来会非常舒服目录管理乱糟糟最后连自己都会忘记哪个文件是干什么用的。尤其是模型文件动辄几个 G随手放置到后面整理成本会变得很高。所以从第一天起就给每个模型文件命名清晰、分类存放、及时清理无用文件这个习惯会让你在后续大量试验中省下无数时间和精力。如果你正在规划自己的 ComfyUI 使用环境我还有一个建议留一个专门的目录放实验性模型和待整理模型和稳定使用的模型区分开避免混在一起影响判断。下载新模型之后先在实验目录测试确认效果没问题再正式归类。这套流程看起来简单但长期坚持下来你的模型库会始终整洁有序找模型、换模型、排查问题都会快很多。最后再分享一个小技巧ComfyUI 的配置文件里其实还支持很多高级选项比如修改临时目录位置、设置默认输出路径、调整缓存策略。等你把基础目录弄明白之后可以慢慢尝试这些参数把 ComfyUI 一点点调校成真正顺手的样子。目录不是死的理解每一层的用途之后你可以按照自己的习惯去调整只要逻辑一致用起来顺手就是最好的目录结构。