导读:本期聚焦于鱼儿创作的《ComfyUI自定义节点安装后菜单不显示怎么办?从__init__.py与节点注册排查》,敬请观看详情。ComfyUI 自定义节点安装完成后,刷新页面却看不到新增菜单,这种情况通常不是插件没装上,而是节点注册环节出了问题。绝大多数自定义节点依赖包内 __init__.py 文件完成导出映射,任何一个导入错误、类名拼写不一致或模块路径缺失都会导致注册静默失败。本文以常见的 NODE_CLASS_MAPPINGS 与 NODE_DISPLAY_NAME_MAPPINGS 为核心,梳理从插件目录识别、__init__.py 注册逻辑到控制台报错排查的完整链路。读者可以跟着检查包结构、注册字典是否被正确加载、导入语句是否触发异常,以及如何利用 ComfyUI 启动日志快速定位是哪个文件阻止了菜单显示。掌握这些检查点,就能处理大多数自定义节点安装后不可见的问题。

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

ComfyUI自定义节点安装后菜单不显示怎么办?从__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

免责声明:已尽一切努力确保本网站所含信息的准确性。网站作品多为原创整理与精心创作,观点力求客观中立。本站旨在免费分享,内容仅供个人学习、研究或参考使用。若引用了第三方作品,版权归原作者所有。如内容涉及您的权益,请联系我们进行处理Email:chomcom@qq.com。
引用或转载本作品时,请注明当前出处:https://www.ipipp.com/html/1103/71669.html,基于非商业用途的前提下,欢迎转载或二创本作品。
内容垂直聚焦
专注技术核心技术栏目,确保每篇文章深度聚焦于实用技能。从代码技巧到架构设计,为用户提供无干扰的纯技术知识沉淀,精准满足专业提升需求。
知识结构清晰
覆盖从开发到部署的全链路。AI、前端、编程、数据库、服务器、建站、系统层层递进,构建清晰学习路径,帮助用户系统化掌握开发与运维所需的核心技术。
深度技术解析
拒绝泛泛而谈,深入技术细节与实践难点。无论是数据库优化还是服务器配置,均结合真实场景与代码示例进行剖析,致力于提供可直接应用于工作的解决方案。
专业领域覆盖
精准对应开发生命周期。从前端界面到后端编程,从数据库操作到服务器运维,形成完整闭环,一站式满足全栈工程师和运维人员的技术需求。
即学即用高效
内容强调实操性,步骤清晰、代码完整。用户可根据教程直接复现和应用于自身项目,显著缩短从学习到实践的距离,快速解决开发中的具体问题。
持续更新保障
专注既定技术方向进行长期、稳定的内容输出。确保各栏目技术文章持续更新迭代,紧跟主流技术发展趋势,为用户提供经久不衰的学习价值。