ComfyUI手动安装扩展后无法识别？

Question

在使用ComfyUI时，用户常通过手动复制扩展文件夹至`custom_nodes`目录的方式安装第三方插件。然而，尽管文件已正确放置，重启ComfyUI后界面仍无法识别该扩展，导致功能不可用。此类问题多出现在Windows或Linux系统中，且通常伴随日志中无明显报错信息，使得排查困难。可能原因包括文件权限不足、目录结构错误、缺少`__init__.py`或`node_definitions.json`等关键文件，或主程序缓存未刷新。此外，Git子模块未初始化、Python依赖未安装也会导致加载失败。该问题严重影响工作流扩展能力，需系统性排查解决。

Answer 1

1. 问题现象与初步诊断

在使用ComfyUI进行AI图像生成工作流开发时，用户常通过手动复制第三方插件文件夹至custom_nodes目录实现扩展功能的集成。尽管文件已正确放置，重启ComfyUI后界面仍无法识别该扩展，且控制台日志中无明显错误提示，导致排查陷入僵局。

此类问题广泛存在于Windows 10/11及主流Linux发行版（如Ubuntu 22.04、CentOS Stream）环境中，尤其在非Git方式部署的本地实例中更为常见。典型表现为：

• 扩展文件夹存在于custom_nodes/路径下
• ComfyUI Web界面未显示新节点或菜单项
• 浏览器开发者工具中无相关JS/CSS加载失败记录
• 服务端启动日志未输出“Loading custom node”相关信息

2. 常见原因分类与层级分析

根据实际运维经验，可将加载失败的原因按优先级分为以下四类：

层级	原因类型	发生频率	检测难度
1	目录结构错误	高	低
2	关键文件缺失	高	中
3	权限与缓存问题	中	中
4	依赖与子模块未初始化	中	高

3. 深度排查流程图

```mermaid
graph TD
    A[开始排查] --> B{custom_nodes目录存在?}
    B -->|否| C[创建custom_nodes目录]
    B -->|是| D{子目录命名规范?}
    D -->|否| E[重命名为合法名称]
    D -->|是| F{包含__init__.py?}
    F -->|否| G[检查是否为前端-only节点]
    F -->|是| H[尝试导入模块]
    H --> I{Python异常抛出?}
    I -->|是| J[查看traceback日志]
    I -->|否| K[检查node_definitions.json]
    K --> L{文件存在且格式正确?}
    L -->|否| M[补全定义文件]
    L -->|是| N[验证Web静态资源路径]
    N --> O[完成加载]
```

4. 关键文件校验清单

每个有效ComfyUI扩展必须满足以下文件结构要求：

1. 根级入口文件：__init__.py 必须存在并导出NODE_CLASS_MAPPINGS
2. 节点定义元数据：node_definitions.json（部分插件需要）
3. Python依赖声明：requirements.txt 或 pyproject.toml
4. 前端组件支持：web/ 子目录含JS资源（若为混合型节点）
5. Git子模块引用：.gitmodules 存在时需执行git submodule update --init
6. 可执行权限：Linux下确保.py文件具有读执行权限（chmod +x *.py）
7. 编码一致性：所有文本文件应为UTF-8 without BOM（Windows特别注意）
8. 版本兼容性：检查__init__.py中comfyui_version约束
9. 唯一节点ID：避免与其他插件冲突的CLASS_TYPE
10. 异步加载处理：涉及async函数需正确包装

5. 系统级调试方法论

当常规手段无效时，建议启用深度调试模式：

# 在启动脚本中插入调试钩子
import folder_paths
print("Custom nodes path:", folder_paths.get_folder_paths("custom_nodes"))

# 手动模拟加载过程
import importlib.util
spec = importlib.util.spec_from_file_location("mynode", "/path/to/custom_nodes/my_extension/__init__.py")
module = importlib.util.module_from_spec(spec)
try:
    spec.loader.exec_module(module)
    print("Module loaded successfully")
    print("Registered nodes:", getattr(module, 'NODE_CLASS_MAPPINGS', {}).keys())
except Exception as e:
    import traceback
    traceback.print_exc()

通过上述代码可在独立Python环境中验证模块可导入性，绕过ComfyUI主进程缓存机制干扰。