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"
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 支持
]
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 中。在这种情况下,我们需要强制包含它以用于注册表使用。
完整示例
[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 版本兼容性