Extensions/ComfyUI-Any-Path-Repair

ComfyUI Extension

ComfyUI-Any-Path-Repair

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

By a63976659·Created 9 months ago·Updated 8 days ago· 14

a63976659/ComfyUI-Any-Path-Repair

Nodes—

On cloudLocal install

Stars14

Updated8 days ago

Readme

🔧 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 | 扩散模型、文本编码器 | | 放大模型 | upscale_model_name | 超分辨率模型 | | Embeddings | embedding_name | 文本嵌入模型 | | 音频模型 | audio_model_name | 音频编码模型 |

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

自动适配旧版菜单、新版命令工具栏和 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)

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

独立任务列表：显示排队、下载中、完成、失败和取消状态，以及已下载大小、总大小和实际保存位置。
进度与恢复：进度条实时更新；关闭面板或刷新浏览器后，右键“修复路径”按钮即可重新查看任务详情。
取消与重试：排队任务可直接取消；正在下载的任务会在读取数据或网络超时后响应取消，并清理临时文件。失败或取消后可重试。
并行下载：同时下载 3 个文件，其余任务排队。同名文件位于不同目录时分别管理，同一目标不会重复启动。
运行范围：任务记录保存在当前 ComfyUI 进程内，保留最近 128 条已结束任务；退出或重启 ComfyUI 后不会恢复未完成下载。

9. 🎯 下载目录与文件校验 (Download Paths & Integrity)

正确分类：优先采用节点类型和链接数据库的分类；类型未知时再根据下载地址推断，不跨类型自动修复同名模型。
目录分离：模型类别与相对子目录分别处理，使用 ComfyUI 已注册的模型目录，并阻止路径越界。
文件校验：拒绝空文件和 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-10-22 `v2.3.0`

修复桌面版按钮位置，支持工具栏延迟加载、重绘后自动归位。
统一前后端识别规则，优先使用节点真实选项，限制自动修复类型，并将按需扫描移至后台线程。
修复扫描失败提示正常、子目录下载、带参数链接和不完整下载被判成功的问题。
增加独立下载任务、刷新恢复、排队、取消、失败重试和临时文件校验。
增加修复前后对照、撤销、未知模型搜索和安全文本显示。
清理额外依赖。
修复成功、无需修复及没有模型节点时均不弹窗，仅在按钮上短暂显示结果；右键按钮可查看记录、撤销修复和管理下载任务。

2026-09-09 `v1.5.2`

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

2026-06-22 `v1.5.1`

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

2026-03-11 `v1.5.0`

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

2026-03-09 `v1.4.0`

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

2026-02-01 `v1.3.0`

智能路径精准锁定：自动下载到对应的文件夹，无需手动选择。
可视化后台下载系统：实时下载状态反馈，可多个模型同时下载。随时中断，关闭了插件弹窗，后台下载依然，再次点击修复按钮可查看状态，直至下载完成。
增强型交互界面：防溢出滚动设计，顶部醒目提示，消除用户不懂如果使用的顾虑。
架构重构与零依赖：不需要安装额外 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

方法二：手动下载

点击 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 搜索链接
- ❌ 扫描失败：显示错误信息，解决问题后重新扫描
继续生成：如有需要，完成路径选择或模型下载后再继续。
查看记录或撤销：右键“修复路径”按钮打开最近结果与下载任务，再点击“撤销最近一次修复”；插件会保留你在修复之后手动修改的节点值。撤销记录仅在当前页面内有效。

⚡ 运行方式与限制 (Runtime & Limits)

| 项目 | 行为 | 说明 | |------|------|------| | 模型加载 | 不加载模型权重 | 路径匹配不占用模型显存 | | 扫描范围 | 当前节点选项与相关模型类别 | 扫描耗时取决于节点数量、磁盘和模型目录 | | 下载并发 | 3 个文件 | 其余任务排队，模型下载仅由用户操作触发 | | 下载校验 | 非空、响应类型、已知长度 | 未提供文件长度时无法仅凭字节数确认完整性 | | 任务恢复 | 当前 ComfyUI 进程内 | 支持刷新页面，不支持服务重启后续传 | | 额外依赖 | 无 | 复用 ComfyUI 已有依赖 |

📥 常见问题 (FAQ)

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

A: 插件修改当前工作流中的节点值；保存、自动保存或导出工作流时，这些修改也会被保存。可在结果面板中撤销最近一次修复。

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 桌面版为适配目标。第三方加载器的支持取决于节点实际提供的模型选项和类型映射。更新插件后请重启 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

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

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

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

📄 许可证 (License)

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

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

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

ComfyUI-Any-Path-Repair

🔧 ComfyUI Any Path Repair

✨ 核心亮点 (Highlights)

1. 🚀 按需扫描与低开销 (On-Demand Scanning)

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

3. 🛡️ 常见模型类型支持 (Model Type Support)

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

5. 📋 "三级漏斗"智能补全机制 (Three-Stage Smart Completion)

6. 🧠 智能冲突仲裁 (Smart Conflict Resolution)

7. 🕵️‍♂️ 动态上下文解析 (Dynamic Context Parsing)

8. ⬇️ 可视化后台下载系统 (Visualized Background Download)

9. 🎯 下载目录与文件校验 (Download Paths & Integrity)

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

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

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

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

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

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

📊 更新日志 (Changelog)

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 Manager

使用方法 (Usage)

⚡ 运行方式与限制 (Runtime & Limits)

📥 常见问题 (FAQ)

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

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

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

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

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

🤝 贡献与支持 (Contribution & Support)

贡献模型链接

报告问题

🔗 相关资源

支持开发者

📄 许可证 (License)

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`