ComfyUI-Any-Path-Repair
ComfyUI任意模型路径修复工具 | 智能模型路径修复引擎。告别 红框 报错,一键修复 ComfyUI 模型加载器路径错误。
🔧 ComfyUI Any Path Repair
ComfyUI任意模型路径修复工具 | 智能模型路径修复引擎
告别"红框"报错,一键修复 ComfyUI 模型加载器路径错误。
ComfyUI-Any-Path-Repair主题曲.mp3
✨ 核心亮点 (Highlights)
1. 🚀 按需扫描与低开销 (On-Demand Scanning)
这是本插件最引以为傲的设计原则。
- 0 VRAM 占用:本插件仅进行字符串逻辑匹配,绝不加载任何模型到显存。无论你的显卡是 4090 还是集显,使用体验完全一致。
- 按需扫描:模型路径扫描仅在点击"修复"按钮后执行;界面通过低频检查维护按钮位置。
- 后台线程扫描:优先使用节点的真实模型选项,仅在需要时扫描相关类别,不遍历整个模型库,也不在服务器事件循环中执行文件扫描。
2. 🧠 智能路径穿透 (Smart Path Penetration)
不再受限于对方的文件夹整理习惯。
- 文件名指纹匹配:
- 分享的工作流路径:
models/checkpoints/SD1.5/Anime/counterfeit-v3.safetensors - 你的本地路径:
checkpoints/counterfeit-v3.safetensors
- 分享的工作流路径:
- 结果:原生 ComfyUI 会报错丢失模型,本插件能通过文件名指纹自动匹配到你本地的正确文件,并自动更新节点。
3. 🛡️ 常见模型类型支持 (Model Type Support)
支持以下常见模型类型,并为部分第三方加载器提供专属映射:
| 模型类型 | 对应部件名 / 加载器 | 说明 |
|---------|---------------|------|
| 大模型 | ckpt_name | Stable Diffusion 主模型 |
| LoRA/LyCORIS | lora_name | 微调模型、风格模型 |
| VAE | vae_name | 变分自编码器 |
| ControlNet | control_net_name | 控制网模型 |
| CLIP Vision | clip_vision_name | CLIP 视觉编码器 |
| UNet/CLIP | unet_name, clip_name, clip_name1 等 | 扩散模型、文本编码器,支持编号部件 |
| 放大模型 | upscale_model_name | 超分辨率模型 |
| Embeddings | embedding_name | 文本嵌入模型 |
| 音频检查点 | audio_model_name, audio_checkpoint_name | 保存到 audio_checkpoints |
| 音频编码器 | audio_encoder_name / AudioEncoderLoader | 保存到 audio_encoders |
| Wav2Vec | Wav2VecModelLoader | 保存到 wav2vec2 |
| LTX 音频 VAE | LTXVAudioVAELoader | 保存到 checkpoints |
| NLF 姿态模型 | nlf_model / LoadNLFModel | 识别 nlf 目录中的 .torchscript 文件 |
4. 🎨 双 UI 完美适配 (Dual UI Support)
自动适配旧版菜单、新版命令工具栏和 ComfyUI 桌面版。新版界面的“修复路径”按钮与翻译开关、管理扩展功能按钮同排;工具栏延迟加载或界面重绘后会自动恢复位置。
按钮采用 28 px 高、12 px 文字和 SVG 扳手图标,随 ComfyUI 明暗主题显示;有排队、下载中或正在取消的任务时,显示数字徽标。
5. 📋 "三级漏斗"智能补全机制 (Three-Stage Smart Completion)
这是插件最核心的逻辑升级,确保用户在任何情况下都能得到解决方案:
第一优先级(精准匹配):工作流上下文嗅探
- 自动扫描工作流中的 Note 或 ShowText 节点
- 提取作者留下的 Markdown 格式下载链接(
[文件名](URL)) - 优先推荐作者指定的模型版本
第二优先级(快速检索):本地数据库匹配
- 如果在工作流里没找到,会秒查本地的
model_links.json数据库 - 提供你预设的高质量下载源
- 支持自定义扩展下载源数据库
第三优先级(兜底搜索):Hugging Face 智能搜索
- 如果以上都落空,自动生成 Hugging Face 的精准搜索链接
- 在 UI 上提供直达按钮,一键跳转搜索
6. 🧠 智能冲突仲裁 (Smart Conflict Resolution)
当本地有多个同名文件时,插件具备"智能犹豫"能力:
- 唯一解自动修:只有一个有效匹配项 → 自动修复,按钮短暂显示数量;成功及无需修复时不弹窗,右键按钮可查看前后对照和撤销
- 多解用户选:多个匹配项 → 弹出可视化选择界面
- 无解智能导:没有匹配项 → 引导下载或搜索
7. 🕵️♂️ 动态上下文解析 (Dynamic Context Parsing)
- Markdown 链接提取:智能识别
[ModelName](https://...)格式 - 智能分类映射:识别文本标题(如
**vae**,## checkpoints) - 路径提示:自动映射到正确的 ComfyUI 文件夹,提示用户下载后放对位置
8. ⬇️ 可视化后台下载系统 (Visualized Background Download)
告别“盲盒”式下载,全新的下载引擎提供全方位的状态反馈:
- 独立任务列表:显示排队、下载中、完成、失败和取消状态,以及已下载大小、总大小和实际保存位置。
- 进度与恢复:进度条实时更新;页面加载及与 ComfyUI 重新连接后,自动同步任务和数字徽标,清除失效记录。右键“修复路径”按钮可查看任务详情。
- 取消与重试:排队任务可直接取消;正在下载的任务会在读取数据或网络超时后响应取消,并清理临时文件。取消成功后不生成正式模型文件;文件已经保存完成时保留完成状态。失败或取消后可重试。
- 并行下载:同时下载 3 个文件,其余任务排队。同名文件位于不同目录时分别管理,同一目标不会重复启动。
- 运行范围:任务记录保存在当前 ComfyUI 进程内,保留最近 128 条已结束任务;退出或重启 ComfyUI 后不会恢复未完成下载。
9. 🎯 下载目录与文件校验 (Download Paths & Integrity)
- 正确分类:按节点类型、数据库分类和声明的保存目录匹配链接,支持 FLUX ControlNet、T5 等子分类;类型未知时再根据下载地址推断,不跨类型自动修复同名模型。
- 目录分离:使用 ComfyUI 已注册的模型目录;优先保留工作流中的有效相对子目录,否则采用数据库声明的子目录,如
controlnet/FLUX.1、text_encoders/t5,并阻止路径越界。 - 文件校验:拒绝空文件和 HTML 网页响应;服务器提供文件长度时,核对实际下载字节数。
- 临时文件:下载先写入
.part临时文件,成功后才转为正式模型文件;失败和取消会清理本次临时文件。 - 直链解析:支持带查询参数、URL 编码的文件名,以及 Hugging Face、GitHub 文件页面链接转换。
10. 🏗️ 零依赖与纯净架构 (Zero Dependency & Clean Architecture)
为了极致的稳定性和易用性,我们重构了底层架构:
- 无需额外依赖:使用 Python 标准库及 ComfyUI 已有的服务接口,不需要另装
huggingface_hub或modelscope。 - 保存目录可控:按工作流或数据库指定的目录保存文件,不照搬远端仓库中的
split_files等路径。 - 内置镜像:Hugging Face 下载默认使用
hf-mirror.com;实际可用性与速度取决于下载源和网络环境。
11. 🖱️ 人性化交互细节 (Enhanced UX Details)
针对重度用户的贴心优化:
- 一键复制直链:下载按钮旁新增
📋 复制链接,方便习惯使用 迅雷/IDM 的用户手动下载。 - 防溢出滚动设计:当缺失模型过多时,弹窗自动启用垂直滚动条并限制最大高度,防止撑爆屏幕。
- 安全显示与错误反馈:模型名称、路径按纯文本显示;扫描和下载异常会明确提示,不会把失败当成“路径正确”。
- 扫描独立与结果同步:下载任务列表读取失败不影响路径扫描;较晚返回的右键请求不会覆盖较新的扫描结果。
🎯 三大适用场景 (Three Core Use Cases)
场景一:分享工作流,新手零门槛 🚀
"分享的动作流,小白不知道怎么切换,点击即修复"
典型问题:
- 下载了大佬的精品工作流,却因为路径不同满屏红框
- 新手不知道如何逐个修改模型加载器
适用人群:
- 工作流分享者:让你的作品更容易被他人使用
- 初学者:无需研究复杂配置,专注创意实现
- 教学场景:保证学生能100%复现演示效果
场景二:整理模型库,路径一键更新 📁
"自己整理了模型,比如放入子文件夹,模型可以一键修复读取路径"
典型问题:
- 为了管理方便,将模型按类型/版本放入子文件夹
- 整理后发现所有工作流都失效了
- 不想逐个修改几十个保存的工作流
- 分类管理后找不到原来的模型
适用人群:
- 模型收藏家:拥有大量模型需要分类管理
- 专业创作者:建立标准化的工作环境
- 团队协作:统一团队内的模型存储规范
场景三:多版本筛选,避免选择困难 🔍
"文件较多,懒得筛选,比如Wan模型有高噪底噪,看的时候经常眼花"
典型问题:
- 同个模型有多个版本(如Wan的高噪版、底噪版)
- 文件名相似,选择时容易混淆
- 下拉列表太长,找模型像大海捞针
- 不确定哪个版本效果最好
适用人群:
- 版本控:喜欢收集模型的各个版本
- 实验型创作者:需要对比不同模型效果
- 模型测试者:评估多个变体的表现
📊 更新日志 (Changelog)
2026-11-18 v2.5.0
修复部分模型找不到、下载位置错误和取消失效的问题,并让修复结果与下载记录显示更准确。
2026-11-17 v2.4.0
缩小按钮和文字,调整配色与图标,并显示正在下载的任务数量。
2026-10-22 v2.3.0
修正按钮位置,完善路径修复、下载和撤销功能,修复成功或无需修复时不再弹窗。
2026-09-09 v1.5.2
支持更多姿态和人脸模型,补充下载链接,避免把不同模型保存到错误的文件夹。
2026-06-22 v1.5.1
支持背景移除、人脸检测等更多模型的路径修复。
2026-03-11 v1.5.0
支持更多模型的路径修复,并改进下载地址查找。
2026-03-09 v1.4.0
修复部分放大模型找不到的问题,并改进缺失模型提示。
2026-02-01 v1.3.0
支持自动保存到对应文件夹,增加下载进度和多个文件同时下载,并减少安装步骤。
2026-01-29 v1.2.0
更方便地查找模型、复制下载链接,并减少扫描卡顿。
2026-01-28 v1.1.0
增加同名模型选择,改善界面显示并减少内存占用。
2026-01-28 v1.0.0
首次发布,支持按文件名查找模型并修复路径。
🛠️ 安装与使用 (Installation & Usage)
安装方法 (Installation)
方法一:Git Clone(推荐)
# 进入 ComfyUI 自定义节点目录
cd ComfyUI/custom_nodes/
# 克隆仓库
git clone https://github.com/a63976659/ComfyUI-Any-Path-Repair.git
# 重启 ComfyUI
方法二:手动下载
- 点击 GitHub 页面上的 Code → Download ZIP
- 解压到
ComfyUI/custom_nodes/目录 - 重启 ComfyUI
方法三:ComfyUI Manager
# 搜索 ComfyUI-Any-Path-Repair 并安装
# 若管理器未收录,请使用上面的 Git 或 ZIP 方式
💡 安装帮助:如遇 Git 问题,参考视频教程:
https://www.bilibili.com/video/BV1ecMnzQEfc/
使用方法 (Usage)
- 加载工作流 → 发现红色报错节点
- 点击修复按钮:
- 旧版 UI:菜单面板中的 "🔧 修复路径"
- 新版 UI / 桌面版:命令工具栏中的 "🔧 修复路径",与翻译开关、管理扩展功能按钮同排
- 每次扫描前会更新节点模型选项,下载完成后可再次扫描以修复路径
- 查看修复结果:
- ✅无加载模型节点:按钮短暂显示“未发现模型节点”,不弹窗
- ✅加载模型正常:按钮短暂显示“路径正常”,不弹窗
- ✅加载模型路径修复:按钮短暂显示“已修复 N 项”,不弹窗
- ⚠️ 重复模型需选择:弹出选择框,手动选择正确版本
- ⬇️ 缺失模型可下载:显示下载按钮或复制链接使用下载器下载,页面有提示模型保存路径!
- ❓ 未知模型:提供 Hugging Face 搜索链接
- ❌ 扫描失败:显示错误信息,解决问题后重新扫描
- 继续生成:如有需要,完成路径选择或模型下载后再继续。
- 查看记录或撤销:右键“修复路径”按钮打开最近结果与下载任务,再点击“撤销最近一次修复”;插件会保留你在修复之后手动修改的节点值。撤销记录仅在当前页面内有效。
更新后生效:重启 ComfyUI,再按 Ctrl+F5 强制刷新页面。下载任务仅保存在当前 ComfyUI 进程内,重启会停止未完成任务。
⚡ 运行方式与限制 (Runtime & Limits)
| 项目 | 行为 | 说明 | |------|------|------| | 模型加载 | 不加载模型权重 | 路径匹配不占用模型显存 | | 扫描范围 | 当前节点选项与相关模型类别 | 扫描耗时取决于节点数量、磁盘和模型目录 | | 下载并发 | 3 个文件 | 其余任务排队,模型下载仅由用户操作触发 | | 下载校验 | 非空、响应类型、已知长度 | 未提供文件长度时无法仅凭字节数确认完整性 | | 任务恢复 | 当前 ComfyUI 进程内 | 页面加载和连接恢复后自动同步,不支持服务重启后续传 | | 额外依赖 | 无 | 复用 ComfyUI 已有依赖 |
📥 常见问题 (FAQ)
Q1: 插件会修改我的原始工作流文件吗?
A: 插件修改当前工作流中的节点值;保存、自动保存或导出工作流时,这些修改也会被保存。可在结果面板中撤销最近一次修复。
Q2: 我有两个同名模型在不同文件夹,插件怎么处理?
A: 插件会检测到"冲突",弹出选择界面让你手动选择。建议:
- 保持模型文件名唯一性
- 使用子文件夹分类:
checkpoints/SD1.5/、checkpoints/SDXL/ - 在文件名中加入版本标识:
model_v1.safetensors
Q3: 插件支持哪些模型下载源?
A: 支持可直接返回模型文件的 HTTP/HTTPS 链接,包括 Hugging Face、GitHub,以及其他网站提供的文件直链。Hugging Face 和 GitHub 文件页面链接会自动转换;需要登录、授权或网盘确认页的链接,请先取得可用直链,或使用外部下载器手动下载。返回 HTML 网页的链接会提示错误。
Q4: 如何贡献模型链接到数据库?
A: 欢迎加入QQ群202018000 到群在线文档 模型下载链接填写表格,或通过 填写并保存 模型信息,我们会定期更新官方数据库。
Q5: 插件兼容哪些 ComfyUI 版本?
A: 以当前官方 ComfyUI 和 ComfyUI 桌面版为适配目标。第三方加载器的支持取决于节点实际提供的模型选项和类型映射。更新插件后请重启 ComfyUI 并刷新页面。
🤝 贡献与支持 (Contribution & Support)
贡献模型链接
# 加入QQ群202018000
打开群共享文件
打开路径:
群功能-群文件-群在线文档(顶部)-模型下载链接填写表格
# 编辑 模型下载链接填写表格
如果是网盘链接尽量使用永久时限,
注意不要误删除别人的编辑
# 保存
报告问题
- GitHub Issues:
https://github.com/a63976659/ComfyUI-Any-Path-Repair/issues - 反馈模板:
1. ComfyUI 版本: 2. 插件版本: 3. 错误截图: 4. 复现步骤: 5. 期望结果:
🔗 相关资源
- 📖 官方文档:
https://github.com/a63976659/ComfyUI-Any-Path-Repair/wiki - 🎥 视频教程:
https://www.bilibili.com/video/BV1ecMnzQEfc/ - 💬 讨论社区:[QQ群202018000]
- 📦 模型数据库:定期更新于 GitHub Releases
支持开发者
如果这个插件帮你节省了大量时间,欢迎:
- ⭐ Star 项目让更多人看到
- 🐛 提交 Issue 帮助改进
- 📖 分享教程 帮助其他用户
- ☕ 请作者喝咖啡 🔔 关注更新,获取最新功能和模型数据库
作者:a63976659
致谢:感谢所有测试用户和贡献者! 如果你觉得插件还不错可以点个收藏。
请作者喝奶茶可以扫个码😀😀😀
养家版二维码❥(^_-)
📄 许可证 (License)
本项目采用 Apache-2.0 license - 查看 LICENSE 文件了解详情。
ComfyUI Any Path Repair —— 让分享与复现变得简单,让创作不再被技术细节束缚。
"修复的不只是路径,更是创作者之间的连接。🎨✨"