ComfyUI-WanVideoWrapper 自定义节点安装问题排查指南

问题现象分析

在使用 ComfyUI-WanVideoWrapper 项目时，用户遇到了自定义节点无法正常加载的问题。从日志分析来看，系统启动时并未显示该节点的加载信息，而其他自定义节点如 ComfyUI-Manager 和 ComfyUI-Impact-Pack 则正常加载。

常见安装问题排查

1. 目录结构验证
   确保克隆的仓库正确放置在 ComfyUI 的 custom_nodes 目录下。正确的路径应为 /workspace/ComfyUI/custom_nodes/ComfyUI-WanVideoWrapper（或本地对应路径）。注意不要保留 GitHub 自动添加的 -main 后缀。

2. 文件权限检查
   在 Linux 环境下，需要确认节点文件具有可执行权限。可以通过 ls -l 命令查看文件权限，必要时使用 chmod 命令调整。

3. 依赖项安装
   某些自定义节点需要额外的 Python 依赖包。虽然本例中未显示相关错误，但建议检查项目文档是否有特殊依赖要求，并通过 pip 安装。

4. 命名冲突排查
   避免节点文件夹名称中包含特殊字符或空格，这可能导致 Python 导入失败。保持名称简洁，仅使用字母、数字和下划线。

解决方案验证

用户最终通过完全重启 ComfyUI 实例解决了问题。这表明：

1. 缓存影响
   ComfyUI 可能缓存了自定义节点列表，重启可以强制重新扫描和加载所有节点。

2. 热重载限制
   某些情况下，直接添加新节点而不重启服务可能导致节点未被正确识别。

3. 环境一致性
   重启确保了所有环境变量和路径设置被正确初始化。

最佳实践建议

1. 标准化安装流程

   • 克隆仓库到 custom_nodes 目录
   • 确认文件夹命名规范
   • 检查并安装所需依赖
   • 完全重启 ComfyUI 服务

2. 日志监控
   启动时关注控制台输出的"Import times for custom nodes"部分，确认目标节点出现在列表中。

3. 测试验证
   安装后立即检查节点是否出现在 ComfyUI 的节点列表中，或尝试通过搜索功能定位。

4. 环境隔离
   考虑使用虚拟环境管理 Python 依赖，避免不同项目间的包冲突。

通过系统化的排查方法和标准化的安装流程，可以显著提高自定义节点部署的成功率。本例也提醒我们，有时最简单的解决方案（如完全重启）可能是最有效的。