ComfyUI-Manager离线节点安装：本地ZIP包处理方法

你是否遇到过网络不稳定导致ComfyUI节点安装失败的情况？或者需要在无网络环境下部署自定义节点？本文将详细介绍如何通过ComfyUI-Manager的本地ZIP包功能，三步完成离线节点安装，解决网络依赖难题。读完本文后，你将掌握ZIP包验证、手动安装流程以及常见问题排查方法，让节点部署不再受网络限制。

准备工作：了解离线安装原理

ComfyUI-Manager的离线安装功能通过manager_util.extract_package_as_zip方法实现ZIP包解析，核心代码位于glob/manager_util.py。该方法会验证ZIP文件完整性并提取内容至指定目录，整个流程无需网络连接。

必要条件

• 已安装ComfyUI-Manager（init.py）
• 符合规范的节点ZIP包（需包含__init__.py或requirements.txt）
• 本地存储路径可写权限

步骤一：获取并验证ZIP包

1.1 合法ZIP包结构

标准的ComfyUI节点ZIP包应包含以下至少一种文件：

custom-node-example/
├── __init__.py       # 节点核心代码
├── requirements.txt  # 依赖声明文件（可选）
└── README.md         # 节点说明文档（可选）

1.2 完整性检查

通过以下命令验证ZIP包是否损坏（Linux/Mac）：

zip -T your-node-package.zip

Windows用户可使用文件资源管理器直接打开ZIP包查看内容。

步骤二：手动安装流程

2.1 图形界面安装（推荐）

1. 启动ComfyUI，打开ComfyUI-Manager面板
2. 导航至「节点管理」→「本地安装」选项卡
3. 点击「选择ZIP文件」，浏览并选择本地节点包
4. 确认安装路径（默认：ComfyUI/custom_nodes/）
5. 点击「安装」并等待完成提示

2.2 命令行安装（高级用户）

通过cm-cli.py执行离线安装：

python cm-cli.py install-zip --path /path/to/your-node-package.zip

安装日志会保存在prestartup_script.py定义的日志路径中，默认位置：ComfyUI/user/comfyui/ComfyUI-Manager.log

步骤三：验证与故障排除

3.1 安装验证

1. 重启ComfyUI，在节点列表中查找新安装的节点
2. 检查日志文件确认无错误信息：

grep "Extracted zip file" ComfyUI/user/comfyui/ComfyUI-Manager.log

3.2 常见问题解决

问题1：ZIP包解析失败

症状：日志显示BadZipFile错误
解决：

1. 重新下载ZIP包并验证完整性
2. 检查文件权限：

chmod 644 your-node-package.zip

问题2：依赖缺失

症状：节点加载失败，提示ModuleNotFoundError
解决：
手动安装依赖：

pip install -r custom_nodes/your-node-package/requirements.txt

问题3：版本冲突

症状：节点功能异常或ComfyUI启动失败
解决：
使用prestartup_script.py定义的PIP修复工具：

python prestartup_script.py --fix-pip

最佳实践与注意事项

4.1 ZIP包制作规范

• 根目录避免多层嵌套，直接包含节点文件
• 大型模型文件应单独提供，避免包含在节点ZIP中
• 必须声明Python版本兼容性（通过requirements.txt）

4.2 批量安装技巧

创建安装脚本install-offline.sh：

#!/bin/bash
for zip in ./offline-nodes/*.zip; do
  python cm-cli.py install-zip --path "$zip"
done

该方法适合同时安装多个节点包，脚本可参考check.sh的错误处理逻辑。

总结与展望

通过本地ZIP包安装功能，ComfyUI-Manager有效解决了网络限制下的节点部署问题。核心实现依赖glob/manager_util.py的ZIP解析工具和prestartup_script.py的依赖管理系统。未来版本将支持ZIP包签名验证和批量依赖预下载功能，进一步提升离线安装体验。

如果您在使用过程中遇到问题，可参考docs/目录下的官方文档，或提交issue至项目仓库获取支持。

收藏本文，下次遇到网络问题时即可快速查阅离线安装方案！关注我们获取更多ComfyUI实用技巧。