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

【实战教程】ComfyUI 插件从 GitHub 仓库到 Comfy Registry 全流程发布指南(附完整踩坑实录)
【笔记】把已有的 ComfyUI 插件发布到 Comfy Registry（官方节点商店）全流程实录

---

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

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

一、前置准备

需要	说明
GitHub 账号	github.com 注册
Comfy Registry 账号	registry.comfy.org，用 GitHub 登录
本地插件代码	写好的自定义节点，至少包含 __init__.py

---

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

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

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 = "🛡️"

⚠️ 关键踩坑点

坑	后果	正确做法
name 包含 "ComfyUI"	命名违规，发布失败	去掉前缀，如 comfyui-sage-guard ✅
PublisherId 填成 API Key	Failed to validate token	PublisherId = Publisher 用户名（如 love）
PublisherId 与 API Key 不匹配	Token 验证失败	确保 token 是在该 Publisher 下生成的
文件含中文但非 UTF-8	UnicodeDecodeError	保存为 UTF-8 无 BOM

---

四、第三步：推送到 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

1. 打开 registry.comfy.org，用 GitHub 登录
2. 点击 Create Publisher
3. 填写：
   • Username : 你的 Publisher ID（如 love）--- 创建后不可更改！
   • Display Name: 显示名称
4. 进入 Publisher 页面 → API Keys → Create new key
5. ⚠️ 立刻复制保存！页面关掉后永远看不到原文，丢了只能重新生成

---

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

6.1 添加 GitHub Secret

1. 打开仓库 Settings → Secrets and variables → Actions → New repository secret
2. Name : REGISTRY_ACCESS_TOKEN（必须严格一致）
3. Secret: 粘贴上一步的 API Key
4. Add 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）

---

九、完整踩坑记录汇总

阶段	错误	原因	解决
首次发布	UnicodeDecodeError: 'charmap' codec can't decode	Windows 默认 cp1252 编码，tomlkit 没指定 UTF-8	修改 comfy_cli/registry/config_parser.py：open(path) → open(path, encoding="utf-8")
首次发布	Failed to validate token: 400	PublisherId 与 API Key 不匹配	PublisherId 改为 API Key 所属 Publisher 的用户名
Git push	Repository not found	GitHub 上还没创建远程仓库	先在 GitHub 网站创建空仓库
版本更新	Version already exists	版本号没递增	每次发布必须改 version
API Key	丢失/失效	页面刷新后不可见，或重新生成	去 Registry 重新生成新 key

---

十、验证发布成功

检查点	链接
GitHub 仓库	github.com/love530love/comfyui-sage-guard
GitHub Releases	github.com/love530love/comfyui-sage-guard/releases
Comfy Registry 节点页	registry.comfy.org/zh/publishers/love/nodes/comfyui-sage-guard
ComfyUI-Manager 搜索	在 ComfyUI 里搜 sage-guard

---

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

1. Windows UTF-8 编码问题 → 改 comfy-cli 源码
2. PublisherId 与 API Key 不匹配 → 确保用同一个 Publisher 账号下的 key

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

Publishing Nodes - ComfyUI