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

相关推荐
一条Go8 小时前
探测规则:为什么它是告警规则的一种,而不是独立的任务体系
后端·架构·github
一条Go8 小时前
开源新生代雷达 · 第 17 期
github
怕浪猫9 小时前
2026 GitHub 最火的 10 个视频制作与剪辑开源项目:AI 出片、代码生视频、无损剪辑怎么选(附实测截图)
github
承渊政道10 小时前
magic-resume简历工具教程:Windows部署、在线编辑与远程访问
windows·远程访问·在线编辑·简历制作·工具教程·magic-resume
智联视频超融合平台11 小时前
视频 AI 的误报之战,正在从调参数卷到改架构
人工智能·大模型·边缘计算·视频监控·安防
水如烟11 小时前
孤能子视角:智能的边界不在算法强弱,在可形式化性——从概率法到因果推理,选择池的边界一直在那里
人工智能
万里侯12 小时前
日志聚类之后别把 noise 扔掉:降噪应该改变视图,不抹掉证据
人工智能·微服务·ai·容器·k8s
澹锦汐13 小时前
纯前端秋日银杏与枫叶落叶色板智能聚类器:基于 K-Means 色彩量化与直方图自动配方提取
前端·人工智能·ai·语言模型·vue·react·k-means
71777720 小时前
国内 AI 研发效能工具怎么选:2026 年基于公开信息的选型框架与 Gitee 实践
人工智能·gitee