> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-recommend-assets-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# pyproject.toml

# 规范

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

## \[project] 部分

### name（必需）

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

```bash theme={null}
comfy node install <node-id>
```

**要求:**

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

**最佳实践:**

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

**Examples:**

```toml theme={null}
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 文档](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#name)。

### version（必需）

使用 [语义化版本控制](https://semver.org/) 并包含三个数字的版本号 X.Y.Z：

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

**Examples:**

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

### license（可选）

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

1. **文件引用：**

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

2. **许可证名称：**

```toml theme={null}
license = { text = "MIT License" }  # ✅ 正确格式
license = { text = "Apache-2.0" }   # ✅ 正确格式
license = "MIT LICENSE"             # ❌ 格式错误
```

常见许可证：[MIT](https://opensource.org/license/mit), [GPL](https://www.gnu.org/licenses/gpl-3.0.en.html), [Apache](https://www.apache.org/licenses/LICENSE-2.0)

### description（推荐）

自定义节点的简要描述。

```toml theme={null}
description = "A super resolution node for enhancing image quality"
```

### repository (必需)

相关资源的链接：

```toml theme={null}
[project.urls]
Repository = "https://github.com/username/repository"
```

### urls（推荐）

相关资源的链接：

```toml theme={null}
[project.urls]
Documentation = "https://github.com/username/repository/wiki"
"Bug Tracker" = "https://github.com/username/repository/issues"
```

### requires-python（推荐）

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

```toml theme={null}
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](https://pypi.org/project/comfyui-frontend-package/) 上。

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

* 你的自定义节点使用了特定版本中引入的前端 API
* 你发现了你的节点与某些前端版本之间的不兼容性
* 你的节点需要仅在较新前端版本中可用的特定 UI 功能

```toml theme={null}
[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加速器。这个信息用于帮助用户找到适合他们系统的节点。

```toml theme={null}
[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:**

```toml theme={null}
PublisherId = "john-doe"        # ✅ 匹配 GitHub 用户名
PublisherId = "image-wizard"    # ✅ 唯一标识符
```

### DisplayName（可选）

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

```toml theme={null}
DisplayName = "Super Resolution Node"
```

### Icon（可选）

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

**要求：**

* 文件类型：SVG, PNG, JPG, 或 GIF
* 最大分辨率：400px × 400px
* 长宽比应该是正方形

```toml theme={null}
Icon = "https://raw.githubusercontent.com/username/repo/main/icon.png"
```

### Banner（可选）

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

**要求：**

* 文件类型：SVG, PNG, JPG, 或 GIF
* 长宽比：21:9

```toml theme={null}
Banner = "https://raw.githubusercontent.com/username/repo/main/banner.png"
```

### requires-comfyui（可选）

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

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

```toml theme={null}
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 中。在这种情况下，我们需要强制包含它以用于注册表使用。

```toml theme={null}
includes = ['dist']
```

## 完整示例

```toml theme={null}
[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 版本兼容性
```