maxczc-comfyui-sora-node/TROUBLESHOOTING.md

ComfyUI 节点不显示 - 故障排除指南

如果节点在 ComfyUI 中没有显示，请按照以下步骤排查：

1. 检查文件结构

确保文件结构如下：

ComfyUI/
└── custom_nodes/
    └── sora/
        ├── __init__.py          ← 必需！
        ├── sora_node.py         ← 必需！
        ├── README.md
        └── ...

2. 检查 __init__.py 文件

确保 __init__.py 文件存在并正确导出了节点映射：

from .sora_node import (
    NODE_CLASS_MAPPINGS,
    NODE_DISPLAY_NAME_MAPPINGS,
)

3. 检查 ComfyUI 日志

启动 ComfyUI 时，查看控制台输出，查找：

• ✅ 成功加载：Loaded custom node: sora
• ❌ 错误信息：Failed to load custom node: sora 或 ImportError

常见错误：

• ModuleNotFoundError: 检查文件路径和文件名
• ImportError: 检查 __init__.py 中的导入语句
• SyntaxError: 检查 Python 语法错误

4. 验证节点注册

在 ComfyUI 启动后，可以在 Python 控制台中验证：

# 在 ComfyUI 的 Python 控制台中运行
from custom_nodes.sora import NODE_CLASS_MAPPINGS
print(NODE_CLASS_MAPPINGS.keys())

应该看到：

dict_keys(['SoraTextToVideo', 'SoraImageToVideo', 'SoraVideoToVideo'])

5. 常见问题

问题 1: 节点完全不显示

可能原因：

• 缺少 __init__.py 文件
• 文件路径错误（不在 custom_nodes/ 目录下）
• Python 语法错误导致导入失败

解决方法：

1. 确认 __init__.py 文件存在
2. 检查 ComfyUI 启动日志中的错误信息
3. 运行 python quick_test.py 验证代码是否正确

问题 2: 部分节点显示，部分不显示

可能原因：

• 节点类定义有错误
• 节点映射不完整

解决方法：

1. 检查 NODE_CLASS_MAPPINGS 是否包含所有节点
2. 检查每个节点类是否有语法错误

问题 3: 节点显示但无法使用

可能原因：

• INPUT_TYPES() 方法有错误
• 返回类型定义不正确

解决方法：

1. 检查节点的 INPUT_TYPES() 方法
2. 检查 RETURN_TYPES 和 RETURN_NAMES 定义

6. 手动测试加载

创建一个测试脚本验证节点是否可以加载：

# test_comfyui_load.py
import sys
import os

# 模拟 ComfyUI 的导入路径
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

try:
    from __init__ import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
    print("✅ 节点加载成功！")
    print(f"已注册的节点: {list(NODE_CLASS_MAPPINGS.keys())}")
    print(f"显示名称: {list(NODE_DISPLAY_NAME_MAPPINGS.values())}")
except Exception as e:
    print(f"❌ 节点加载失败: {e}")
    import traceback
    traceback.print_exc()

运行：

python test_comfyui_load.py

7. ComfyUI 版本兼容性

确保使用兼容的 ComfyUI 版本。自定义节点需要：

• ComfyUI 版本 >= 0.1.0
• Python 3.8+

8. 重启 ComfyUI

修改节点代码后，必须完全重启 ComfyUI（不是刷新页面）：

1. 完全关闭 ComfyUI 进程
2. 重新启动 ComfyUI
3. 清除浏览器缓存（可选）

9. 检查节点菜单

节点应该出现在：

• 右键菜单 → Add Node → Sora
• 或者使用搜索功能搜索 "Sora"

10. 如果仍然无法解决

1. 检查 ComfyUI 的完整启动日志
2. 确认 Python 环境正确
3. 尝试在 ComfyUI 的 Python 环境中直接导入：

   import custom_nodes.sora
   

快速诊断命令

在节点目录下运行：

# 1. 验证代码语法
python -m py_compile sora_node.py __init__.py

# 2. 验证节点注册
python -c "from __init__ import NODE_CLASS_MAPPINGS; print(list(NODE_CLASS_MAPPINGS.keys()))"

# 3. 运行完整测试
python quick_test.py

如果所有测试都通过，但 ComfyUI 仍然不显示节点，请检查 ComfyUI 的启动日志。