模型加载失败：找不到、不识别、架构不匹配
ComfyUI 模型加载失败通常分三类：文件找不到、文件不识别、架构不匹配。三类问题的排查方向完全不同，先判断你属于哪一类，再按下面三步走，别一上来就重新下载。开始前建议先过一遍排错总览的 60 秒速检。
症状
对照下面三种表现，确定你的问题类型：
- 节点的模型下拉列表是空的，或看不到刚放进去的模型——多半是路径问题。
- 运行时报
Value not in list: ckpt_name: 'model-name.safetensors' not in []（找不到指定模型）——文件不在搜索路径里。 - 生成时报 tensor 维度、shape 不匹配之类的错误——架构不匹配。
快速检查（60 秒）
- 文件在不在
ComfyUI/models/下对应类型的子目录？checkpoint 放checkpoints/，LoRA 放loras/，VAE 放vae/。 - 扩展名在 ComfyUI 支持列表里吗（最常见
.safetensors/.ckpt）？文件大小和官方发布页对得上吗？ - 点一次界面上的刷新按钮（Refresh）或重启 ComfyUI，再看下拉列表。
排查步骤
第 1 步：确认搜索路径
报错：Value not in list: ckpt_name: 'model-name.safetensors' not in []（找不到指定模型）
解决：把模型放进对应类型的子目录，或让 ComfyUI 读到你的自定义目录。放错类型目录是最常见原因——checkpoint 放进了 loras/，下拉列表里自然找不到。如果你把模型集中放在其他磁盘，需要在 extra_model_paths.yaml 里登记额外搜索路径（配置写法见模型放哪里：models 目录与 extra_model_paths 详解），改完重启 ComfyUI 生效。
第 2 步：确认文件完整且格式正确
报错：Error while deserializing header（模型文件无法识别 / 加载结果为空）
解决：先怀疑文件本身，重新下载并核对文件大小。下载中断会留下损坏文件；确认扩展名在 ComfyUI 的支持列表里（.safetensors、.ckpt、.pt、.pth、.bin 等，完整列表见模型放哪里）；文件名里有特殊字符或中文时，改成纯英文数字再刷新列表 。
第 3 步：处理架构不匹配
报错：The size of tensor a (49) must match the size of tensor b (16) at non-singleton dimension 1（tensor 维度 / shape 不匹配）
解决：这类报错说明模型架构和加载器对不上，不是文件坏了。常见情形有三种：用通用 checkpoint 加载器去加载只含部分权重的模型，应改用对应的专用加载节点（各模型类型对应的 loader 节点见模型放哪里的对照表）；LoRA 和底模架构不一致，换同架构的 LoRA；模型太新，当前 ComfyUI 版本可能还不支持它的架构，更新到最新版再试。VAE 配错也会报通道数不匹配，例如 Flux 模型用了 sdxl_vae.safetensors，换成 Flux 官方发布里的 ae.safetensors 即可。先到模型发布页确认它标注的架构，再选匹配的加载器。
升级条件
出现以下任一情况，别再本地死磕，去 ComfyUI 的 GitHub 仓库提 issue：
- 换了正确的加载器和目录后，仍然报 tensor 维度错误。
- 同一个模型文件在其他工具里能正常加载，只有 ComfyUI 报错。
- 重新下载后问题依旧，怀疑模型文件本身有问题。
提 issue 时附上：完整报错文本、模型名称和下载来源、你的 ComfyUI 版本与启动方式。