)
【实战教程】ComfyUI 插件从 GitHub 仓库到 Comfy Registry 全流程发布指南(附完整踩坑实录)【笔记】把已有的 ComfyUI 插件发布到 Comfy Registry官方节点商店全流程实录ComfyUI-FixFlashAttnSchema0. 这篇文章解决什么问题你写好了一个 ComfyUI 自定义节点,想让别人能通过 ComfyUI-Manager 直接搜到、装上,而不是手把手教别人git clone。这就需要把它发布到 Comfy Registry(ComfyUI 官方节点商店)。本文按真实操作顺序,从零开始走一遍完整流程,并把过程中实际踩到的坑原样保留下来——这些坑比正确步骤本身更有参考价值,因为官方文档不会告诉你这些细节会怎么炸。1. 前置准备一个 GitHub 账号一个 registry.comfy.org 账号(可以用 GitHub 账号登录)安装comfy-cli(如果想本地手动发布;只走 GitHub Action 自动发布的话可以不装):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 # 选填图标 URLPublisherId不是密钥,是身份标识,公开可见,出现在你节点的 URL 里。它是账号级别的概念,不是按节点分配的——一个 Publisher 账号下可以挂任意多个插件,所有插件复用同一个PublisherId,不需要每个插件单独申请。实操中真实踩到的坑:把 API Key(认证用的密钥)误填进了PublisherId这一栏。这两者长得完全不一样——PublisherId一般是个短的、人类可读的标识符(常见做法是跟 GitHub 用户名保持一致);API Key/Token 是一长串随机字符或哈希值,专门用来认证我是这个 Publisher 本人,永远不应该出现在 URL 路径或公开字段里。如果你发布之后,看到请求 URL 里publishers/后面跟着一长串哈希,基本可以确定就是这个坑。4. 第三步:推送到 GitHubcd 你的插件目录 git init git add.git commit-minit: first versiongit 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打开 registry.comfy.org,用 GitHub 账号或 Google 账号登录。创建 Publisher account。个人主页 URL 里后面那一串就是你的PublisherId——这个一旦创建就不可更改,选的时候慎重一点。进入 Publisher 页面,创建一个 API Key,专门用来发布节点(跟付费 Partner Nodes 用的 key 是两套不同的体系,不要搞混)。生成后立刻复制保存到密码管理器之类的地方,页面关掉之后就再也看不到原文了,丢了只能重新生成。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-actionmain这个官方 Action 读取secrets.REGISTRY_ACCESS_TOKEN完成发布。[ .github/workflows/publish_action.yml 完整内容]name: Publish to Comfy registry on: workflow_dispatch: push: branches: - main paths: -pyproject.tomljobs: publish-node: name: Publish Custom Node to registry runs-on: ubuntu-latest steps: - name: Check out code uses: actions/checkoutv4 - name: Publish Custom Node uses: Comfy-Org/publish-node-actionmain 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 publishGitHub 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. 踩坑实录合集(时间线整理)顺序现象原因解法1git push报Repository not foundGitHub 上还没建对应的空仓库先在网页端建仓库,再 push2comfy node publish报UnicodeDecodeError: charmap codec cant decode byte 0x90pyproject.toml里写了中文注释,文件是 UTF-8 编码,但comfy-cli用open()读取时没指定encodingutf-8,在 Windows 上走了系统默认的cp1252代码页,无法解码 UTF-8 多字节字符把pyproject.toml里的注释/文本全部换成纯英文,规避对系统代码页的依赖3发布请求的 URL 里publishers/后面跟着一长串哈希,而不是预期的短标识符PublisherId字段被误填成了 API Key/Token去 Registry 个人主页确认真实的PublisherId(短标识符),改回正确值4comfy 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.zipcomfy node publish本地打包发布时生成的构建产物,没被.gitignore排除加进.gitignore,避免以后误提交7API Key 在终端输出里完整出现,被多次原样贴进聊天记录comfy node publish --token 真实值这种写法,只要复制这条命令就一定会带出明文 token;命令历史也会留存用setx COMFY_API_TOKEN 真实值存成持久化环境变量,以后统一用comfy node publish --token $env:COMFY_API_TOKEN,命令本身不再包含明文第 7 条是这次过程里最值得单独强调的一点,放到下一节展开。9. 关于 API Key 的安全实践PublisherId和Token经常被混着用,但性质完全不同,务必分清楚:PublisherIdAPI Key / Token性质身份标识,公开认证凭证,私密出现位置节点 URL、pyproject.toml的[tool.comfy]字段仅用于认证请求头,绝不应出现在 URL 或公开文件里泄露后果无实际风险,本来就是公开的可能被冒用发布/篡改你名下的节点,泄露后应立刻撤销重新生成实践建议:本地需要长期、反复使用的 Token,用setx存成持久化用户环境变量,而不是每次手打或从历史记录里复制完整命令:setx COMFY_API_TOKEN你的真实token存好之后开一个新终端窗口,统一用comfy node publish --token $env:COMFY_API_TOKEN这种写法,命令本身和命令历史里都不会再出现明文。日常发布优先走 GitHub Action,Token 全程留在 GitHub Secret 里,不经过本地终端,从根上避免复制命令时带出明文这类操作失误。一旦怀疑 Token 已经暴露(贴进聊天记录、提交进了 git 历史、截图发出去等),第一反应是去后台撤销重新生成,而不是评估会不会真的被人看到——撤销的成本远低于事后处理被冒用的成本。10. 日常版本迭代的标准流程走通一次完整流程之后,以后发新版本只需要:git add pyproject.toml git commit-mchore: bump version to x.y.zgit pushpyproject.toml里的version改了、推送到main分支,GitHub Action 就会自动触发发布,不需要再碰命令行工具或手动管理 Token。去仓库的 Actions 页面能看到每次发布的执行状态,绿勾代表发布成功。11. 参考链接Comfy Registry 官方发布文档:https://docs.comfy.org/registry/publishingpyproject.toml字段规范:https://docs.comfy.org/registry/specifications官方发布 Action 仓库:https://github.com/Comfy-Org/publish-node-action 【实战教程】ComfyUI 插件从 GitHub 仓库到 Comfy Registry 全流程发布指南(附完整踩坑实录)
【实战教程】ComfyUI 插件从 GitHub 仓库到 Comfy Registry 全流程发布指南(附完整踩坑实录)【笔记】把已有的 ComfyUI 插件发布到 Comfy Registry官方节点商店全流程实录ComfyUI-FixFlashAttnSchema0. 这篇文章解决什么问题你写好了一个 ComfyUI 自定义节点,想让别人能通过 ComfyUI-Manager 直接搜到、装上,而不是手把手教别人git clone。这就需要把它发布到 Comfy Registry(ComfyUI 官方节点商店)。本文按真实操作顺序,从零开始走一遍完整流程,并把过程中实际踩到的坑原样保留下来——这些坑比正确步骤本身更有参考价值,因为官方文档不会告诉你这些细节会怎么炸。1. 前置准备一个 GitHub 账号一个 registry.comfy.org 账号(可以用 GitHub 账号登录)安装comfy-cli(如果想本地手动发布;只走 GitHub Action 自动发布的话可以不装):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 # 选填图标 URLPublisherId不是密钥,是身份标识,公开可见,出现在你节点的 URL 里。它是账号级别的概念,不是按节点分配的——一个 Publisher 账号下可以挂任意多个插件,所有插件复用同一个PublisherId,不需要每个插件单独申请。实操中真实踩到的坑:把 API Key(认证用的密钥)误填进了PublisherId这一栏。这两者长得完全不一样——PublisherId一般是个短的、人类可读的标识符(常见做法是跟 GitHub 用户名保持一致);API Key/Token 是一长串随机字符或哈希值,专门用来认证我是这个 Publisher 本人,永远不应该出现在 URL 路径或公开字段里。如果你发布之后,看到请求 URL 里publishers/后面跟着一长串哈希,基本可以确定就是这个坑。4. 第三步:推送到 GitHubcd 你的插件目录 git init git add.git commit-minit: first versiongit 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打开 registry.comfy.org,用 GitHub 账号或 Google 账号登录。创建 Publisher account。个人主页 URL 里后面那一串就是你的PublisherId——这个一旦创建就不可更改,选的时候慎重一点。进入 Publisher 页面,创建一个 API Key,专门用来发布节点(跟付费 Partner Nodes 用的 key 是两套不同的体系,不要搞混)。生成后立刻复制保存到密码管理器之类的地方,页面关掉之后就再也看不到原文了,丢了只能重新生成。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-actionmain这个官方 Action 读取secrets.REGISTRY_ACCESS_TOKEN完成发布。[ .github/workflows/publish_action.yml 完整内容]name: Publish to Comfy registry on: workflow_dispatch: push: branches: - main paths: -pyproject.tomljobs: publish-node: name: Publish Custom Node to registry runs-on: ubuntu-latest steps: - name: Check out code uses: actions/checkoutv4 - name: Publish Custom Node uses: Comfy-Org/publish-node-actionmain 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 publishGitHub 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. 踩坑实录合集(时间线整理)顺序现象原因解法1git push报Repository not foundGitHub 上还没建对应的空仓库先在网页端建仓库,再 push2comfy node publish报UnicodeDecodeError: charmap codec cant decode byte 0x90pyproject.toml里写了中文注释,文件是 UTF-8 编码,但comfy-cli用open()读取时没指定encodingutf-8,在 Windows 上走了系统默认的cp1252代码页,无法解码 UTF-8 多字节字符把pyproject.toml里的注释/文本全部换成纯英文,规避对系统代码页的依赖3发布请求的 URL 里publishers/后面跟着一长串哈希,而不是预期的短标识符PublisherId字段被误填成了 API Key/Token去 Registry 个人主页确认真实的PublisherId(短标识符),改回正确值4comfy 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.zipcomfy node publish本地打包发布时生成的构建产物,没被.gitignore排除加进.gitignore,避免以后误提交7API Key 在终端输出里完整出现,被多次原样贴进聊天记录comfy node publish --token 真实值这种写法,只要复制这条命令就一定会带出明文 token;命令历史也会留存用setx COMFY_API_TOKEN 真实值存成持久化环境变量,以后统一用comfy node publish --token $env:COMFY_API_TOKEN,命令本身不再包含明文第 7 条是这次过程里最值得单独强调的一点,放到下一节展开。9. 关于 API Key 的安全实践PublisherId和Token经常被混着用,但性质完全不同,务必分清楚:PublisherIdAPI Key / Token性质身份标识,公开认证凭证,私密出现位置节点 URL、pyproject.toml的[tool.comfy]字段仅用于认证请求头,绝不应出现在 URL 或公开文件里泄露后果无实际风险,本来就是公开的可能被冒用发布/篡改你名下的节点,泄露后应立刻撤销重新生成实践建议:本地需要长期、反复使用的 Token,用setx存成持久化用户环境变量,而不是每次手打或从历史记录里复制完整命令:setx COMFY_API_TOKEN你的真实token存好之后开一个新终端窗口,统一用comfy node publish --token $env:COMFY_API_TOKEN这种写法,命令本身和命令历史里都不会再出现明文。日常发布优先走 GitHub Action,Token 全程留在 GitHub Secret 里,不经过本地终端,从根上避免复制命令时带出明文这类操作失误。一旦怀疑 Token 已经暴露(贴进聊天记录、提交进了 git 历史、截图发出去等),第一反应是去后台撤销重新生成,而不是评估会不会真的被人看到——撤销的成本远低于事后处理被冒用的成本。10. 日常版本迭代的标准流程走通一次完整流程之后,以后发新版本只需要:git add pyproject.toml git commit-mchore: bump version to x.y.zgit pushpyproject.toml里的version改了、推送到main分支,GitHub Action 就会自动触发发布,不需要再碰命令行工具或手动管理 Token。去仓库的 Actions 页面能看到每次发布的执行状态,绿勾代表发布成功。11. 参考链接Comfy Registry 官方发布文档:https://docs.comfy.org/registry/publishingpyproject.toml字段规范:https://docs.comfy.org/registry/specifications官方发布 Action 仓库:https://github.com/Comfy-Org/publish-node-action