ComfyUI 自定义节点安装后菜单不显示,往往不是插件复制位置不对,而是节点注册没有成功。ComfyUI 在启动时会扫描 custom_nodes 目录下的每个插件包,并尝试导入其根目录中的 __init__.py。如果这个文件不存在、导入过程抛异常,或者注册字典没有正确暴露给框架,即使插件文件已经放进目录,前端菜单里也不会出现任何新节点。排查时需要从文件结构、注册字典和控制台报错三个层面依次确认。

一、确认自定义节点包结构与 __init__.py 是否存在
ComfyUI 将 custom_nodes 目录下的每个一级子文件夹视为一个插件候选。启动加载时,它会读取该文件夹根部的 __init__.py 文件,通过导入这个模块来执行节点注册。因此,如果解压时多了一层同名文件夹,例如 custom_nodes/ComfyUI-MyNodes/ComfyUI-MyNodes/__init__.py,框架会认为外层插件包里没有入口文件,从而直接跳过注册。解决方法是把内层真正包含 __init__.py 的目录移动到 custom_nodes 下。
可以执行下面的命令快速查看目录层级。Windows 用户在资源管理器地址栏输入 cmd 后回车,再使用 dir 即可。Linux 或 macOS 直接用 ls。
# 自定义节点根目录
custom_nodes/
YourNodePack/
__init__.py
nodes.py
requirements.txt
如果 __init__.py 不在根目录,菜单一定不会显示。即使文件存在,也要确认文件名拼写正确,前后没有多余空格,并且文件编码为 UTF-8,避免 Windows 记事本默认编码导致导入错误。
二、检查 __init__.py 中的 NODE_CLASS_MAPPINGS 注册字典
ComfyUI 识别节点的核心入口是 NODE_CLASS_MAPPINGS,这是一个 Python 字典,键是节点在菜单中显示的内部标识,值是对应的节点类。框架导入插件后,会读取这个字典并把它合并到全局节点表。如果 __init__.py 里没有定义或导出这个字典,前端菜单自然一片空白。下面是一个最简单的注册示例:
# __init__.py
from .nodes import ExampleNode
NODE_CLASS_MAPPINGS = {
"ExampleNode": ExampleNode,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"ExampleNode": "示例节点",
}
注意 ExampleNode 必须是继承自 ComfyNode 或相关基类的节点类。很多插件会把节点统一写在 nodes.py 里,然后在 __init__.py 中集中导入。如果类名大小写不一致,例如文件中定义的是 examplenode,而注册字典键写成 Examplenode,Python 导入仍然可能成功,但节点类不存在,注册时就会抛出 AttributeError。
还有一种常见写法是直接从模块里引入现成字典:
# __init__.py from .nodes import NODE_CLASS_MAPPINGS from .nodes import NODE_DISPLAY_NAME_MAPPINGS __all__ = ['NODE_CLASS_MAPPINGS', 'NODE_DISPLAY_NAME_MAPPINGS']
这种方式适合节点定义较多、不想在入口文件重复维护字典的插件。但要注意 nodes.py 中字典必须位于模块顶层,不能放在 if __name__ == '__main__' 内部,否则导入时不会执行注册。
三、定位导入错误与依赖缺失导致的静默失败
自定义节点没有显示时,优先查看 ComfyUI 启动时的控制台输出。Windows 用户通过 run_nvidia_gpu.bat 或 run_cpu.bat 启动时,黑窗口会打印插件导入日志。如果在导入某个插件时出现 ImportError、ModuleNotFoundError 或 SyntaxError,该插件的节点注册就会被中止,但 ComfyUI 主程序不会退出,只会在日志里留一条错误。很多用户看到 ComfyUI 正常启动,就以为插件已经加载,实际上菜单里没有任何新增项。
常见的导入错误包括:插件依赖了未安装的第三方库,例如 import cv2 或 import onnxruntime;插件内使用相对导入 from .utils import helper,但 ComfyUI 没有以包模式导入该目录;以及代码中出现不兼容当前 Python 版本的语法。遇到这类问题,可以先在 ComfyUI 的 Python 环境里手动执行导入测试:
# 进入 ComfyUI 虚拟环境后执行 python -c "import sys; sys.path.insert(0, 'custom_nodes/YourNodePack'); import YourNodePack"
这段命令会模拟导入过程,错误信息会直接显示在终端。根据报错安装缺失依赖,或者修正 __init__.py 中的导入语句。如果控制台提示某个 .py 文件编码错误,用 VS Code 或 Notepad++ 另存为 UTF-8 编码即可解决。
四、检查节点是否注册成功与前端缓存问题
即使节点已经成功注册,有时前端页面因为浏览器缓存或 ComfyUI 服务未重启,仍然不会出现新菜单。修改 __init__.py 后必须完全停止 ComfyUI 进程,再重新运行启动脚本。只刷新浏览器不会重新加载 Python 节点定义,因为节点注册发生在后端启动阶段。可以观察控制台是否输出类似 Import times for custom nodes 的信息,这表示自定义节点已经完成加载。
还可以在 ComfyUI 的 Python 环境中运行一小段脚本,确认节点是否进入全局注册表:
import nodes print(nodes.NODE_CLASS_MAPPINGS.keys())
如果字典里能看到你的节点类名,说明注册成功,问题出在前端。此时可以尝试清空浏览器缓存,或者使用浏览器的无痕窗口打开 ComfyUI。部分插件把自己注册到 image、latent 等分类下,如果前端菜单折叠或搜索框过滤条件未清除,也可能造成节点“消失”。在节点搜索框输入类名直接查找,通常能绕过菜单层级问题。
如果查询结果中依然没有目标节点,回到 __init__.py 检查注册字典是否在模块导入后被其他代码覆盖。极少数插件会在最后执行 NODE_CLASS_MAPPINGS = {} 清空操作,或者因为函数缩进错误导致字典定义在某个条件分支内。逐行阅读入口文件是定位这类隐蔽问题的最可靠方式。
ComfyUI自定义节点节点注册__init__.py修改时间:2026-11-03 04:26:28