规范

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（可选）

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

文件引用：

license = { file = "LICENSE" }     # ✅ 指向 LICENSE 文件
license = { file = "LICENSE.txt" } # ✅ 指向 LICENSE.txt 文件
license = "LICENSE"                # ❌ 格式错误

许可证名称：

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"

repository (必需)

urls（推荐）

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"

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']

要从发布归档中排除文件（与 includes 相反），请参阅发布页面中的 .comfyignore 部分。

完整示例

[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 版本兼容性

ComfyUI APIs

CLI

开发自定义节点

注册表(Registry)

规范

pyproject.toml

规范

[project] 部分

name（必需）

version（必需）

license（可选）

description（推荐）

repository (必需)

urls（推荐）

requires-python（推荐）

前端版本兼容性（可选）

classifiers（推荐）

[tool.comfy] 部分

PublisherId（必需）

DisplayName（可选）

Icon（可选）

Banner（可选）

requires-comfyui（可选）

includes（可选）

完整示例

​规范

​[project] 部分

​name（必需）

​version（必需）

​license（可选）

​description（推荐）

​repository (必需)

​urls（推荐）

​requires-python（推荐）

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

​classifiers（推荐）

​[tool.comfy] 部分

​PublisherId（必需）

​DisplayName（可选）

​Icon（可选）

​Banner（可选）

​requires-comfyui（可选）

​includes（可选）

​完整示例

规范

[project] 部分

name（必需）

version（必需）

license（可选）

description（推荐）

repository (必需)

urls（推荐）

requires-python（推荐）

前端版本兼容性（可选）

classifiers（推荐）

[tool.comfy] 部分

PublisherId（必需）

DisplayName（可选）

Icon（可选）

Banner（可选）

requires-comfyui（可选）

includes（可选）

完整示例