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

love530love2026-06-26 9:14

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

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

0. 这篇文章解决什么问题

你写好了一个 ComfyUI 自定义节点,想让别人能通过 ComfyUI-Manager 直接搜到、装上,而不是手把手教别人 git clone。这就需要把它发布到 Comfy Registry(ComfyUI 官方节点商店)。

本文按真实操作顺序,从零开始走一遍完整流程,并把过程中实际踩到的坑原样保留下来------这些坑比"正确步骤"本身更有参考价值,因为官方文档不会告诉你这些细节会怎么炸。

1. 前置准备

  • 一个 GitHub 账号

  • 一个 registry.comfy.org 账号(可以用 GitHub 账号登录)

  • 安装 comfy-cli(如果想本地手动发布;只走 GitHub Action 自动发布的话可以不装):

    powershell 复制代码 
    pip install comfy-cli

  • 写好的自定义节点代码,放在本地一个独立目录里

2. 第一步:搭建标准仓库结构

一个能发布到 Comfy Registry 的最小仓库结构:

复制代码 
你的插件名/
├── __init__.py                          # 节点代码本体，至少要有 NODE_CLASS_MAPPINGS
├── pyproject.toml                       # Registry 元数据，核心配置文件
├── README.md                            # 说明文档
├── LICENSE                              # 开源协议
└── .github/
    └── workflows/
        └── publish_action.yml           # 自动发布用的 GitHub Action

__init__.py 的内容因插件而异,这里不展开;README.md 和 LICENSE 按你自己项目的实际情况写。重点是后面两个文件。

3. 第二步:写 pyproject.toml

这是整个流程里最容易踩坑的文件,逐字段说明(完整规范见官方文档 pyproject.toml specifications):

[project] 部分

字段 必填 说明
name 是 节点在 Registry 里的唯一 ID,创建后不可修改 。只能用字母/数字/横线/下划线/点,不能以数字或特殊字符开头,且不能包含 "ComfyUI" 这几个字。
version 是 语义化版本号 X.Y.Z(主版本.次版本.补丁)。同一个版本号不能重复发布,哪怕内容一样,改了什么都要往上加号。
description 建议 一句话描述。建议把核心报错关键词写进去(比如具体的异常类名),方便别人直接搜报错文本搜到你的插件。
license 建议 两种写法:{ file = "LICENSE" } 指向文件,或 { text = "MIT" } 直接写协议名。
[project.urls] 里的 Repository 是 指向你的 GitHub 仓库地址。
classifiers 建议 标注操作系统兼容性(Operating System :: OS Independent 等)和加速器类型(Environment :: GPU :: NVIDIA CUDA 等),帮用户筛选。

[tool.comfy] 部分------这里是本次踩的最大的坑

复制代码 
[tool.comfy]
PublisherId = ""    # 必填
DisplayName = ""    # 选填
Icon = ""            # 选填，图标 URL

PublisherId 不是密钥,是身份标识 ,公开可见,出现在你节点的 URL 里。它是账号级别的概念,不是按节点分配的------一个 Publisher 账号下可以挂任意多个插件,所有插件复用同一个 PublisherId,不需要每个插件单独申请。

实操中真实踩到的坑:把 API Key(认证用的密钥)误填进了 PublisherId 这一栏 。这两者长得完全不一样------PublisherId 一般是个短的、人类可读的标识符(常见做法是跟 GitHub 用户名保持一致);API Key/Token 是一长串随机字符或哈希值,专门用来认证"我是这个 Publisher 本人",永远不应该出现在 URL 路径或公开字段里 。如果你发布之后,看到请求 URL 里 publishers/ 后面跟着一长串哈希,基本可以确定就是这个坑。

4. 第三步:推送到 GitHub

powershell 复制代码 
cd <你的插件目录>
git init
git add .
git commit -m "init: first version"
git branch -M main
git remote add origin https://github.com/<你的用户名>/<仓库名>.git
git push -u origin main

踩坑实录 :如果你在 GitHub 网站上还没创建对应的远程仓库就直接 git push,会报:

复制代码 
remote: Repository not found.
fatal: repository '.../xxx.git/' not found

正确顺序是先在 GitHub 网站上手动创建一个空仓库,再执行本地的 push。这个错误信息容易让人以为是权限或者网络问题,实际上单纯就是"仓库还不存在"。

还会看到这类警告,可以忽略,不影响功能:

复制代码 
warning: in the working copy of 'xxx', LF will be replaced by CRLF the next time Git touches it

这是 Git 在 Windows 上的换行符自动转换提示(core.autocrlf 设置导致),纯粹是格式层面的事,不影响代码执行。

5. 第四步:注册 Publisher,创建 API Key

  1. 打开 registry.comfy.org,用 GitHub 账号或 Google 账号登录。
  2. 创建 Publisher account。个人主页 URL 里 @ 后面那一串就是你的 PublisherId------这个一旦创建就不可更改,选的时候慎重一点。
  3. 进入 Publisher 页面,创建一个 API Key,专门用来发布节点(跟付费 Partner Nodes 用的 key 是两套不同的体系,不要搞混)。
  4. 生成后立刻复制保存到密码管理器之类的地方,页面关掉之后就再也看不到原文了,丢了只能重新生成。

6. 第五步:配置 GitHub Action 自动发布

这是让"以后只要 git push 就自动同步到 Registry"这件事成立的关键一步。

先建一个 GitHub Secret:仓库页面 → Settings → Secrets and Variables → Actions → New repository secret。

  • Name 这一栏:必须填 REGISTRY_ACCESS_TOKEN,跟下面 workflow 文件里引用的名字一字不差,大小写也要对应。
  • Secret 这一栏:粘贴上一步拿到的 API Key,前后不要带空格。

这一步只在 GitHub 网页上操作。 不要把这个值贴回任何聊天记录、文档、issue 里------这正是 GitHub Secrets 存在的意义:填进去之后,网页和 Action 日志里这个值都会被自动遮掩,任何人都看不到原文,是目前最安全的存放方式。

然后在仓库根目录添加 .github/workflows/publish_action.yml:

publish_action.yml 内容是官方提供的标准发布 workflow,核心逻辑是监听 main 分支上 pyproject.toml 文件的变化,触发后用 Comfy-Org/publish-node-action@main 这个官方 Action 读取 secrets.REGISTRY_ACCESS_TOKEN 完成发布。

[ .github/workflows/publish_action.yml 完整内容]

bash 复制代码 
name: Publish to Comfy registry
on:
  workflow_dispatch:
  push:
    branches:
      - main
    paths:
      - "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 }}
          ## 这个 secret 需要在 GitHub 仓库 Settings -> Secrets and Variables -> Actions 里手动添加，
          ## 名字必须严格叫 REGISTRY_ACCESS_TOKEN，值是 registry.comfy.org 上为你的 Publisher 生成的 API Key。

提交推送这个文件之后,以后的发布流程就变成:改 pyproject.toml 里的 version 字段 → git push → 自动发布,不需要再手动跑命令行工具。

7. 两条发布路径的对比

本地 comfy node publish GitHub Action 自动发布
触发方式 手动敲命令,带 --token 推送 pyproject.toml 变化自动触发
Token 暴露风险 高------很容易在命令行/历史记录里明文带出 低------Token 全程留在 GitHub Secret 里,不经过本地终端
网络依赖 依赖你本机访问 api.comfy.org 的网络质量 跑在 GitHub 服务器上,不受本地网络波动影响
适合场景 第一次手动验证流程通不通 日常版本迭代的常规路径

实操中真实遇到过本地发布连接中断的情况:

复制代码 
SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol'))

这是 TLS 握手中途被切断,常见于本地网络环境对海外 API 访问不稳定的情况,跟配置是否正确无关。这也是更推荐把 GitHub Action 当作主路径的原因之一------它从根上避开了本地网络这个不稳定因素。

8. 踩坑实录合集(时间线整理)

顺序 现象 原因 解法
1 git push 报 Repository not found GitHub 上还没建对应的空仓库 先在网页端建仓库,再 push
2 comfy node publish 报 UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 pyproject.toml 里写了中文注释,文件是 UTF-8 编码,但 comfy-cli 用 open() 读取时没指定 encoding="utf-8",在 Windows 上走了系统默认的 cp1252 代码页,无法解码 UTF-8 多字节字符 把 pyproject.toml 里的注释/文本全部换成纯英文,规避对系统代码页的依赖
3 发布请求的 URL 里 publishers/ 后面跟着一长串哈希,而不是预期的短标识符 PublisherId 字段被误填成了 API Key/Token 去 Registry 个人主页确认真实的 PublisherId(短标识符),改回正确值
4 comfy node publish 报 SSLEOFError 连接中断 本机访问 api.comfy.org 的网络/TLS 握手不稳定 改用 GitHub Action 路径发布,不受本地网络影响
5 发布报 400 The node version already exists 同一个 version 号已经成功发布过一次,试图重复发布 把 version 往上加号(比如 1.0.0 → 1.0.1)再发
6 工作目录里多出一个未跟踪的 node.zip comfy node publish 本地打包发布时生成的构建产物,没被 .gitignore 排除 加进 .gitignore,避免以后误提交
7 API Key 在终端输出里完整出现,被多次原样贴进聊天记录 comfy node publish --token <真实值> 这种写法,只要复制这条命令就一定会带出明文 token;命令历史也会留存 用 setx COMFY_API_TOKEN "真实值" 存成持久化环境变量,以后统一用 comfy node publish --token $env:COMFY_API_TOKEN,命令本身不再包含明文

第 7 条是这次过程里最值得单独强调的一点,放到下一节展开。

9. 关于 API Key 的安全实践

PublisherId 和 Token 经常被混着用,但性质完全不同,务必分清楚:

PublisherId API Key / Token
性质 身份标识,公开 认证凭证,私密
出现位置 节点 URL、pyproject.toml 的 [tool.comfy] 字段 仅用于认证请求头,绝不应出现在 URL 或公开文件里
泄露后果 无实际风险,本来就是公开的 可能被冒用发布/篡改你名下的节点,泄露后应立刻撤销重新生成

实践建议:

  1. 本地需要长期、反复使用的 Token,用 setx 存成持久化用户环境变量 ,而不是每次手打或从历史记录里复制完整命令:

    powershell 复制代码 
    setx COMFY_API_TOKEN "你的真实token"

    存好之后开一个新终端窗口,统一用 comfy node publish --token $env:COMFY_API_TOKEN 这种写法,命令本身和命令历史里都不会再出现明文。

  2. 日常发布优先走 GitHub Action,Token 全程留在 GitHub Secret 里,不经过本地终端,从根上避免"复制命令时带出明文"这类操作失误。

  3. 一旦怀疑 Token 已经暴露(贴进聊天记录、提交进了 git 历史、截图发出去等),第一反应是去后台撤销重新生成,而不是评估"会不会真的被人看到"------撤销的成本远低于事后处理被冒用的成本。

10. 日常版本迭代的标准流程

走通一次完整流程之后,以后发新版本只需要:

powershell 复制代码 
git add pyproject.toml
git commit -m "chore: bump version to x.y.z"
git push

pyproject.toml 里的 version 改了、推送到 main 分支,GitHub Action 就会自动触发发布,不需要再碰命令行工具或手动管理 Token。去仓库的 Actions 页面能看到每次发布的执行状态,绿勾代表发布成功。

11. 参考链接

  1. Comfy Registry 官方发布文档:https://docs.comfy.org/registry/publishing
  2. pyproject.toml 字段规范:https://docs.comfy.org/registry/specifications
  3. 官方发布 Action 仓库:https://github.com/Comfy-Org/publish-node-action
热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析06飞书长连接_事件订阅（接收消息，审批任务状态变更）07GitHub 镜像站点08【AI总结】2026年6月 主流国内外大模型总结09Trae国际版与国内版深度测评：AI原生IDE的双生花10AI科技热点日报 | 2026年6月1日