​
规范

pyproject.toml 文件包含两个主要的 ComfyUI 自定义节点部分：[project] 和 [tool.comfy]。以下是每个部分的规范。

​
[project] 部分

​
name（必需）

节点 ID 唯一标识自定义节点，并将用于注册表中的 URL。用户可以通过引用此名称来安装节点：

comfy node install <node-id>

要求:

  • 必须小于 100 个字符
  • 只能包含字母、数字、连字符、下划线和句点
  • 不能有连续的特殊字符
  • 不能以数字或特殊字符开头
  • 不区分大小写比较

最佳实践:

  • 使用简短、描述性的名称
  • 不要在名称中包含 “ComfyUI”
  • 使其易于记忆和输入

Examples:

name = "image-processor"      # ✅ Good: Simple and clear
name = "super-resolution"     # ✅ Good: Describes functionality
name = "ComfyUI-enhancer"    # ❌ Bad: Includes ComfyUI
name = "123-tool"            # ❌ Bad: Starts with number

更多详细信息，请参阅官方 Python 文档。

​
version（必需）

使用 语义化版本控制 并包含三个数字的版本号 X.Y.Z：

  • X（MAJOR）：重大更改
  • Y（MINOR）：新功能（向后兼容）
  • Z (PATCH): Bug fixes

Examples:

version = "1.0.0"    # 初始版本
version = "1.1.0"    # 添加新功能
version = "1.1.1"    # 修复错误
version = "2.0.0"    # 重大更改

​
license（可选）

指定自定义节点的许可证。可以以两种方式指定：

  1. 文件引用：
license = { file = "LICENSE" }     # ✅ 指向 LICENSE 文件
license = { file = "LICENSE.txt" } # ✅ 指向 LICENSE.txt 文件
license = "LICENSE"                # ❌ 格式错误
  1. 许可证名称：
license = { text = "MIT License" }  # ✅ 正确格式
license = { text = "Apache-2.0" }   # ✅ 正确格式
license = "MIT LICENSE"             # ❌ 格式错误

常见许可证：MIT, GPL, Apache

​
description（推荐）

自定义节点的简要描述。

description = "A super resolution node for enhancing image quality"

​
urls（推荐）

相关资源的链接：

[project.urls]
Repository = "https://github.com/username/repository"
Documentation = "https://github.com/username/repository/wiki"
"Bug Tracker" = "https://github.com/username/repository/issues"

​
requires-python（推荐）

指定自定义节点支持的 Python 版本：

requires-python = ">=3.8"        # Python 3.8 或更高版本
requires-python = ">=3.8,<3.11"  # Python 3.8 到 3.11 之间（不包括 3.11）

​
前端版本兼容性（可选）

如果你的节点对 ComfyUI 前端版本有特定要求，你可以使用 comfyui-frontend-package 依赖项来指定。该包发布在 PyPI 上。

在以下情况下使用此字段：

  • 你的自定义节点使用了特定版本中引入的前端 API
  • 你发现了你的节点与某些前端版本之间的不兼容性
  • 你的节点需要仅在较新前端版本中可用的特定 UI 功能
[project]
dependencies = [
    "comfyui-frontend-package>=1.20.0"       # 需要前端 1.20.0 或更新版本
    "comfyui-frontend-package<=1.21.6"       # 限制前端版本最高到 1.21.6
    "comfyui-frontend-package>=1.19,<1.22"   # 适用于前端 1.19 到 1.21.x
    "comfyui-frontend-package~=1.20.0"       # 兼容 1.20.x 但不包括 1.21.0
    "comfyui-frontend-package!=1.21.3"       # 适用于任何版本，除了 1.21.3
]

​
classifiers（推荐）

使用分类器指定操作系统的兼容性和GPU加速器。这个信息用于帮助用户找到适合他们系统的节点。

[project]
classifiers = [
    # 适用于所有操作系统的节点
    "Operating System :: OS Independent",

    # 或者对于特定操作系统的节点，指定支持的系统：
    "Operating System :: Microsoft :: Windows",  # Windows specific
    "Operating System :: POSIX :: Linux",  # Linux specific
    "Operating System :: MacOS",  # macOS specific
    
    # GPU 加速器支持
    "Environment :: GPU :: NVIDIA CUDA",    # NVIDIA CUDA 支持
    "Environment :: GPU :: AMD ROCm",       # AMD ROCm 支持
    "Environment :: GPU :: Intel Arc",      # Intel Arc 支持
    "Environment :: NPU :: Huawei Ascend",  # 华为昇腾支持
    "Environment :: GPU :: Apple Metal",    # Apple Metal 支持
]

​
[tool.comfy] 部分

​
PublisherId（必需）

你的唯一发布者标识符，通常与您的 GitHub 用户名匹配。

Examples:

PublisherId = "john-doe"        # ✅ 匹配 GitHub 用户名
PublisherId = "image-wizard"    # ✅ 唯一标识符

​
DisplayName（可选）

你的自定义节点的用户友好名称。

DisplayName = "Super Resolution Node"

​
Icon（可选）

你的自定义节点的图标 URL，将在 ComfyUI Registry 和 ComfyUI-Manager 中显示。

要求：

  • 文件类型：SVG, PNG, JPG, 或 GIF
  • 最大分辨率：400px × 400px
  • 长宽比应该是正方形
Icon = "https://raw.githubusercontent.com/username/repo/main/icon.png"

​
Banner（可选）

URL 指向一个较大的横幅图像，将在 ComfyUI Registry 和 ComfyUI-Manager 中显示。

要求：

  • 文件类型：SVG, PNG, JPG, 或 GIF
  • 长宽比：21:9
Banner = "https://raw.githubusercontent.com/username/repo/main/banner.png"

​
requires-comfyui（可选）

指定你的节点兼容的 ComfyUI 版本。这有助于用户确保他们安装了正确版本的 ComfyUI。

支持的操作符： <, >, <=, >=, ~=, <>, != 和范围

requires-comfyui = ">=1.0.0"        # ComfyUI 1.0.0 或更高版本
requires-comfyui = ">=1.0.0,<2.0.0"  # ComfyUI 1.0.0 到 2.0.0 之间（不包括 2.0.0）
requires-comfyui = "~=1.0.0"         # 兼容版本：1.0.0 或更新版本，但不包括 2.0.0
requires-comfyui = "!=1.2.3"         # 任何版本，除了 1.2.3
requires-comfyui = ">0.1.3,<1.0.0"   # 大于 0.1.3 且小于 1.0.0

​
includes（可选）

指定是否强制包含某些特定文件夹。对于一些情况，例如在 frontend 项目中的自定义节点，最终打包输出的文件夹可能会被包含在 .gitignore 中。在这种情况下，我们需要强制包含它以用于注册表使用。

includes = ['dist']

​
完整示例

[project]
name = "super-resolution-node"
version = "1.0.0"
description = "Enhance image quality using advanced super resolution techniques"
license = { file = "LICENSE" }
requires-python = ">=3.8"
dependencies = [
    "comfyui-frontend-package<=1.21.6"  # 前端版本兼容性
]
classifiers = [
    "Operating System :: OS Independent"  # 适用于所有操作系统
]
dynamic = ["dependencies"]

[tool.setuptools.dynamic]
dependencies = {file = ["requirements.txt"]}

[project.urls]
Repository = "https://github.com/username/super-resolution-node"
Documentation = "https://github.com/username/super-resolution-node/wiki"
"Bug Tracker" = "https://github.com/username/super-resolution-node/issues"

[tool.comfy]
PublisherId = "image-wizard"
DisplayName = "Super Resolution Node"
Icon = "https://raw.githubusercontent.com/username/super-resolution-node/main/icon.png"
Banner = "https://raw.githubusercontent.com/username/super-resolution-node/main/banner.png"
requires-comfyui = ">=1.0.0"  # ComfyUI 版本兼容性