ComfyUI 插件发布 GitHub Release + Comfy Registry （官方节点商店）完整复盘教程（从零开始）

【实战教程】ComfyUI 插件从 GitHub 仓库到 Comfy Registry 全流程发布指南(附完整踩坑实录)

【笔记】把已有的 ComfyUI 插件发布到 Comfy Registry（官方节点商店）全流程实录

📘 ComfyUI 插件发布完整复盘教程（从零开始）

ComfyUI 插件发布 GitHub Release + Comfy Registry （官方节点商店）完整复盘教程（从零开始）

一、前置准备

二、第一步：搭建标准仓库结构

在你的插件目录里确保有以下文件：

comfyui-sage-guard/ ← 你的插件文件夹
├── __init__.py # 节点代码本体，必须有 NODE_CLASS_MAPPINGS
├── pyproject.toml # ⭐ Registry 核心配置文件
├── README.md # 说明文档
├── LICENSE # 开源协议（MIT 等）
└── .github/
└── workflows/
└── publish_action.yml # ⭐ GitHub Action 自动发布配置

三、第二步：写 pyproject.toml（最容易踩坑！）

[project]
name = "comfyui-sage-guard" # Registry 唯一 ID，不能含"ComfyUI"，创建后不可改
description = "Non-invasive SageAttention compatibility guard…" # 建议包含关键词，方便搜索
version = "1.0.0" # 语义化版本，每次发布必须递增
license = { file = "LICENSE" }
dependencies = ["torch"]

[project.urls]
Repository = "https://github.com/love530love/comfyui-sage-guard"

[tool.comfy]
PublisherId = "love" # ⭐ 必须等于 registry.comfy.org 上的 Publisher 用户名！
DisplayName = "SageAttention Guard"
Icon = "🛡️"

⚠️ 关键踩坑点

四、第三步：推送到 GitHub

cd <你的插件目录>

git init
git add .
git commit -m "init: first version"
git branch -M main

# 先在 GitHub 网站上创建空仓库！
git remote add origin https://github.com/<用户名>/<仓库名>.git
git push -u origin main

⚠️ 踩坑实录

必须先手动在 GitHub 上创建仓库，再 push！ 否则会报：

remote: Repository not found.

五、第四步：注册 Publisher + 生成 API Key

六、第五步：配置 GitHub Action 自动发布

6.1 添加 GitHub Secret

6.2 创建 workflow 文件

.github/workflows/publish_action.yml：

name: Publish to Comfy registry

on:
workflow_dispatch: # 允许手动触发
push:
branches:
– main
paths:
– "pyproject.toml" # 只有 pyproject.toml 变化时才触发

jobs:
publish-node:
name: Publish Custom Node to registry
runs-on: ubuntu-latest
steps:
– name: Check out code
uses: actions/checkout@v4

– name: Publish Custom Node
uses: Comfy-Org/publish-node-action@main
with:
personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}

– name: Extract version from pyproject.toml
id: get_version
run: |
VERSION=$(grep -oP 'version\\s*=\\s*"\\K[^"]+' pyproject.toml)
echo "version=$VERSION" >> $GITHUB_OUTPUT

– name: Create GitHub Release
uses: softprops/action-gh-release@v2
with:
tag_name: v${{ steps.get_version.outputs.version }}
name: Release v${{ steps.get_version.outputs.version }}
body: |
## What's Changed
– Published to Comfy Registry
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

6.3 推送 workflow

git add .github/workflows/publish_action.yml
git commit -m "ci: add auto-publish workflow"
git push origin main

七、第六步：首次手动发布（验证流程）

因为 GitHub Action 是监听 pyproject.toml 变化触发，首次需要手动验证：

# 安装 comfy-cli
pip install comfy-cli

# 进入插件目录
cd <你的插件目录>

# 发布（用你保存的 API Key）
comfy node publish –token <你的API_Key>

如果成功，会看到：

Upload successful.

八、第七步：以后自动发布

以后每次更新只需要：

# 1. 修改代码
# 2. 改 pyproject.toml 里的 version（必须递增！）
version = "1.0.1"

# 3. push
git add pyproject.toml
git commit -m "bump version to 1.0.1"
git push origin main

然后自动完成：

• ✅ 发布到 Comfy Registry
• ✅ 创建 GitHub Release（带 tag）

九、完整踩坑记录汇总

十、验证发布成功

这就是你从零到成功发布的完整路径。最核心的两个坑：

以后更新就是改 version + push 一句话的事。🎉

Publishing Nodes – ComfyUI