Extensions/ComfyUI-Any-Path-Repair
ComfyUI Extension

ComfyUI-Any-Path-Repair

ComfyUI任意模型路径修复工具 | 智能模型路径修复引擎。告别 红框 报错，一键修复 ComfyUI 模型加载器路径错误。

By a63976659·Created 8 months ago·Updated about 12 hours ago· 12
a63976659/ComfyUI-Any-Path-Repair
Nodes—
On cloudLocal install
Stars12
Updatedabout 12 hours ago
Readme

🔧 ComfyUI Any Path Repair

ComfyUI任意模型路径修复工具 | 智能模型路径修复引擎

告别"红框"报错，一键修复 ComfyUI 模型加载器路径错误。

ComfyUI-Any-Path-Repair主题曲.mp3

Bilibili

✨ 核心亮点 (Highlights)

1. 🚀 极致轻量与零计算负担 (Zero Computation Overhead)

这是本插件最引以为傲的设计原则。

  • 0 VRAM 占用：本插件仅进行字符串逻辑匹配，绝不加载任何模型到显存。无论你的显卡是 4090 还是集显，使用体验完全一致。
  • 被动触发机制：插件不会在后台持续运行或监听，只有当你点击"修复"按钮的那一刻才会执行，执行时间通常在 0.01秒 级。
  • 不影响生成速度：完全独立于生成线程，对 ComfyUI 的生图性能没有任何干扰。

2. 🧠 智能路径穿透 (Smart Path Penetration)

不再受限于对方的文件夹整理习惯。

  • 文件名指纹匹配：
    • 分享的工作流路径：models/checkpoints/SD1.5/Anime/counterfeit-v3.safetensors
    • 你的本地路径：checkpoints/counterfeit-v3.safetensors
  • 结果：原生 ComfyUI 会报错丢失模型，本插件能通过文件名指纹自动匹配到你本地的正确文件，并自动更新节点。

3. 🛡️ 全模型类型覆盖 (Full Model Type Coverage)

全面支持 ComfyUI 生态系统中的所有模型类型：

| 模型类型 | 对应节点部件名 | 说明 | |---------|---------------|------| | 大模型 | 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 | 扩散模型、文本编码器 | | 放大模型 | upscale_model_name | 超分辨率模型 | | Embeddings | embedding_name | 文本嵌入模型 | | 音频模型 | audio_model_name | 音频编码模型 |

4. 🎨 双 UI 完美适配 (Dual UI Support)

无论你是习惯使用旧版侧边栏菜单，还是喜欢 ComfyUI V1 新版顶部栏，本插件都能自动识别并完美融入，提供丝滑的原生级交互体验。

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)

告别“盲盒”式下载，全新的下载引擎提供全方位的状态反馈：

  • 按钮即进度条：点击下载后，UI 按钮会实时变身进度条（如 ⏳ 45%），背景色随进度动态增长。
  • 控制台详情：ComfyUI 控制台实时显示下载速度、已下载大小，让你对大模型下载心中有数。
  • 随时中断：下错文件或网速太慢？按钮变身红色“❌ 中断下载”，一键停止并自动清理残留文件。
  • 后台持久化：关闭弹窗不影响下载！ UI 顶部醒目提示，你可以安心关闭页面继续作图，后台下载依然稳定运行。

9. 🎯 URL 路径嗅探与物理锁定 (Smart Path Sniffing & Physical Locking)

这是解决“模型下错文件夹”的终极杀手锏。

  • 智能嗅探：插件不再盲目依赖 ComfyUI 的默认分类。它会深度分析下载链接，如果链接包含 /diffusion_models/、/text_encoders/ 等关键词，它会无视一切干扰。
  • 物理锁定：直接绕过 ComfyUI 可能存在的注册表误导，强制将文件锁定到硬盘上的物理文件夹中。
  • 解决痛点：彻底修复了 Acestep 等新架构模型被错误下载到 unet 文件夹的问题。

10. 🏗️ 零依赖与纯净架构 (Zero Dependency & Clean Architecture)

为了极致的稳定性和易用性，我们重构了底层架构：

  • 移除重型依赖：完全移除 huggingface_hub 库，改用 Python 原生 urllib。用户无需安装任何额外 Python 库即可使用。
  • 扁平化存储：彻底解决了旧版库自动创建 split_files 等多级子文件夹的烦人问题，下载即用，无需手动移动文件。
  • 内置镜像加速：代码内置强制逻辑，自动将 huggingface.co 替换为 hf-mirror.com，国内用户无需配置代理即可享受满速下载。

11. 🖱️ 人性化交互细节 (Enhanced UX Details)

针对重度用户的贴心优化：

  • 一键复制直链：下载按钮旁新增 📋 复制链接，方便习惯使用 迅雷/IDM 的用户手动下载。
  • 防溢出滚动设计：当缺失模型过多时，弹窗自动启用垂直滚动条并限制最大高度，防止撑爆屏幕。
  • 空文件自动熔断：下载完成后自动校验，如果发现是 0KB 的空文件（如网络错误导致），自动报错并清理，防止损坏的模型污染文件夹。

🎯 三大适用场景 (Three Core Use Cases)

场景一：分享工作流，新手零门槛 🚀

"分享的动作流，小白不知道怎么切换，点击即修复"

典型问题：

  • 下载了大佬的精品工作流，却因为路径不同满屏红框
  • 新手不知道如何逐个修改模型加载器

适用人群：

  • 工作流分享者：让你的作品更容易被他人使用
  • 初学者：无需研究复杂配置，专注创意实现
  • 教学场景：保证学生能100%复现演示效果

场景二：整理模型库，路径一键更新 📁

"自己整理了模型，比如放入子文件夹，模型可以一键修复读取路径"

典型问题：

  • 为了管理方便，将模型按类型/版本放入子文件夹
  • 整理后发现所有工作流都失效了
  • 不想逐个修改几十个保存的工作流
  • 分类管理后找不到原来的模型

适用人群：

  • 模型收藏家：拥有大量模型需要分类管理
  • 专业创作者：建立标准化的工作环境
  • 团队协作：统一团队内的模型存储规范

场景三：多版本筛选，避免选择困难 🔍

"文件较多，懒得筛选，比如Wan模型有高噪底噪，看的时候经常眼花"

典型问题：

  • 同个模型有多个版本（如Wan的高噪版、底噪版）
  • 文件名相似，选择时容易混淆
  • 下拉列表太长，找模型像大海捞针
  • 不确定哪个版本效果最好

适用人群：

  • 版本控：喜欢收集模型的各个版本
  • 实验型创作者：需要对比不同模型效果
  • 模型测试者：评估多个变体的表现

📊 更新日志 (Changelog)

2026-09-09 v1.5.2

  1. 新增对 OnnxDetectionModelLoader（WanAnimate 姿态/人脸检测 ONNX 模型）加载器的支持，修复 ViTPose 与 YOLO 模型路径问题。
  2. 新增对 LoadNLFModel（NLF 姿态估计模型）加载器的支持，修复 MTV Crafter 工作流的 NLF 模型路径问题。
  3. 兼容中文翻译插件：ViT姿态模型、YOLO模型、NLF模型 三个中文部件名（含子图场景）同样可被识别与修复。
  4. 补齐 ViTPose Huge 版（vitpose_h_wholebody_model.onnx 与 vitpose_h_wholebody_data.bin）下载链接，并让 ViTPose、YOLOv10 直链在类型未知时也能正确落到 detection 目录。
  5. 修正 yolo_model、vitpose_model 部件名的跨插件歧义：仅 ONNX 检测加载器与子图节点参与扫描，避免 LayerStyle（models/yolo）、RMBG（models/ultralytics）的同名部件被误判到 detection。

2026-06-22 v1.5.1

  1. 新增对 LoadBackgroundRemovalModel（背景移除模型）加载器的支持，修复背景移除模型路径问题。
  2. 新增对 LoadMediaPipeFaceLandmarker（人脸检测模型）加载器的支持，修复人脸检测模型路径问题。
  3. 新增对 LoadMoGeModel（MoGe几何估计模型）加载器的支持，修复MoGe模型路径问题。

2026-03-11 v1.5.0

  1. 增加更多种类模型加载器检测，一键修复路径。
  2. 优化下载地址匹配方式，确保有地址的模型能够正确下载。

2026-03-09 v1.4.0

  1. 修复Latent放大模型加载器模型路径检测失败的问题。
  2. 优化模型缺少时，且没有下载路径的提醒。

2026-02-01 v1.3.0

  1. 智能路径精准锁定：自动下载到对应的文件夹，无需手动选择。
  2. 可视化后台下载系统：实时下载状态反馈，可多个模型同时下载。 随时中断，关闭了插件弹窗，后台下载依然，再次点击修复按钮可查看状态，直至下载完成。
  3. 增强型交互界面：防溢出滚动设计，顶部醒目提示，消除用户不懂如果使用的顾虑。
  4. 架构重构与零依赖：不需要安装额外 Python 库就能用， 内置将 huggingface替换为 hf-mirror，国内外用户都可满速下载。

2026-01-29 v1.2.0

✨ 核心功能升级

  • 🛡️ 新增"三级漏斗"智能补全机制，解决模型获取难题
  • 🕵️‍♂️ 动态上下文解析，智能提取工作流中的下载链接
  • ⚡ 性能优化：IO读写移至循环外，解决"转圈卡顿"
  • 🛡️ 3秒超时熔断，防止大型工作流扫描卡死
  • 🖱️ 交互升级：新增"📋复制链接"按钮，视觉反馈优化
  • 🎨 界面美化：未知模型黄色警告，下载推荐绿色引导

2026-01-28 v1.1.0

🚀 首次重大更新

  • 🧠 智能冲突仲裁系统，支持多版本模型选择
  • 🖥️ 交互式选择弹窗，可视化冲突解决界面
  • 🔧 性能优化，大幅减少内存占用
  • 📱 UI适配优化，兼容更多ComfyUI版本

2026-01-28 v1.0.0

🎉 初始发布

  • ✅ 基础路径修复功能
  • ✅ 文件名指纹匹配
  • ✅ 支持主流模型类型
  • ✅ 双UI界面适配

🛠️ 安装与使用 (Installation & Usage)

安装方法 (Installation)

方法一：Git Clone（推荐）

# 进入 ComfyUI 自定义节点目录
cd ComfyUI/custom_nodes/

# 克隆仓库
git clone https://github.com/a63976659/ComfyUI-Any-Path-Repair.git

# 重启 ComfyUI

方法二：手动下载

  1. 点击 GitHub 页面上的 Code → Download ZIP
  2. 解压到 ComfyUI/custom_nodes/ 目录
  3. 重启 ComfyUI

方法三：ComfyUI Manager（即将支持）

# 在 ComfyUI Manager 中搜索 "Any Path Repair"
# 一键安装，自动管理更新

💡 安装帮助：如遇 Git 问题，参考视频教程：https://www.bilibili.com/video/BV1ecMnzQEfc/

使用方法 (Usage)

  1. 加载工作流 → 发现红色报错节点
  2. 点击修复按钮：
    • 旧版 UI：右侧菜单面板的 "🔧 修复模型路径"
    • 新版 UI：顶部设置栏附近的 "🔧 修复模型路径"
  3. 查看修复结果：
    • ✅无加载模型节点：当前工作流中未发现可修复的模型节点。
    • ✅加载模型正常：✅ 模型路径正确
    • ✅加载模型路径修复：✅ 成功修复了N个模型路径！
    • ⚠️ 重复模型需选择：弹出选择框，手动选择正确版本
    • ⬇️ 缺失模型可下载：显示下载按钮或复制链接使用下载器下载，页面有提示模型保存路径！
    • ❓ 未知模型：提供 Hugging Face 搜索链接
  4. 关闭提示 → 正常生图！

⚡ 性能技术指标 (Performance Metrics)

| 指标 | 数值 | 说明 | |------|------|------| | 显存占用 | 0 MB | 不加载任何 PyTorch 模型 | | 内存占用 | < 2 MB | 仅存储 JS 逻辑和匹配结果 | | 响应时间 | 10-50ms | 中小型工作流修复时间 | | 扫描超时 | 3000ms | 大型工作流保护机制 | | 硬盘 I/O | 极低 | 仅读取文件列表，不读文件内容 | | 依赖库 | 无 | 纯 Python/JS 原生实现 |

📥 常见问题 (FAQ)

Q1: 插件会修改我的原始工作流文件吗？

A: 不会。插件仅修改当前 ComfyUI 会话中的节点配置值，不会修改硬盘上的任何 .json 或 .png 工作流文件。关闭页面后恢复原始状态。

Q2: 我有两个同名模型在不同文件夹，插件怎么处理？

A: 插件会检测到"冲突"，弹出选择界面让你手动选择。建议：

  • 保持模型文件名唯一性
  • 使用子文件夹分类：checkpoints/SD1.5/、checkpoints/SDXL/
  • 在文件名中加入版本标识：model_v1.safetensors

Q3: 插件支持哪些模型下载源？

A: 支持所有 HTTPS 直链：

  • Hugging Face
  • CivitAI
  • Google Drive
  • 百度网盘（需转直链）
  • 任何提供直接下载链接的网站

Q4: 如何贡献模型链接到数据库？

A: 欢迎加入QQ群202018000 到群在线文档 模型下载链接填写表格，或通过 填写并保存 模型信息，我们会定期更新官方数据库。

Q5: 插件兼容哪些 ComfyUI 版本？

A: 兼容：

  • ✅ ComfyUI 官方版本（所有更新）
  • ✅ ComfyUI-Manager 版本
  • ✅ 多数社区定制版本
  • ❌ 极度老旧版本（2023年以前）

🤝 贡献与支持 (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

  • [小红书：猪的飞行梦]
  • [哔哩哔哩主页：https://space.bilibili.com/2114638644]
  • Bilibili

致谢：感谢所有测试用户和贡献者！ 如果你觉得插件还不错可以点个收藏。

请作者喝奶茶可以扫个码😀😀😀 养家版二维码❥(^_-) 收款二维码

📄 许可证 (License)

本项目采用 Apache-2.0 license - 查看 LICENSE 文件了解详情。

ComfyUI Any Path Repair —— 让分享与复现变得简单，让创作不再被技术细节束缚。

"修复的不只是路径，更是创作者之间的连接。🎨✨"