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 KeyFailed to validate tokenPublisherId Publisher 用户名如lovePublisherId与 API Key 不匹配Token 验证失败确保 token 是在该 Publisher 下生成的文件含中文但非 UTF-8UnicodeDecodeError保存为 UTF-8 无 BOM四、第三步推送到 GitHubcd 你的插件目录 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打开 registry.comfy.org用 GitHub 登录点击Create Publisher填写Username: 你的 Publisher ID如love—创建后不可更改Display Name: 显示名称进入 Publisher 页面 →API Keys→Create new key⚠️ 立刻复制保存页面关掉后永远看不到原文丢了只能重新生成六、第五步配置 GitHub Action 自动发布6.1 添加 GitHub Secret打开仓库 Settings → Secrets and variables → Actions → New repository secretName:REGISTRY_ACCESS_TOKEN必须严格一致Secret: 粘贴上一步的 API KeyAdd secret6.2 创建 workflow 文件.github/workflows/publish_action.ymlname: 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/checkoutv4 - name: Publish Custom Node uses: Comfy-Org/publish-node-actionmain 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-releasev2 with: tag_name: v${{ steps.get_version.outputs.version }} name: Release v${{ steps.get_version.outputs.version }} body: | ## Whats Changed - Published to Comfy Registry env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}6.3 推送 workflowgit 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 cant decodeWindows 默认 cp1252 编码tomlkit 没指定 UTF-8修改comfy_cli/registry/config_parser.pyopen(path)→open(path, encodingutf-8)首次发布Failed to validate token: 400PublisherId与 API Key 不匹配PublisherId改为 API Key 所属 Publisher 的用户名Git pushRepository not foundGitHub 上还没创建远程仓库先在 GitHub 网站创建空仓库版本更新Version already exists版本号没递增每次发布必须改 versionAPI Key丢失/失效页面刷新后不可见或重新生成去 Registry 重新生成新 key十、验证发布成功检查点链接GitHub 仓库github.com/love530love/comfyui-sage-guardGitHub Releasesgithub.com/love530love/comfyui-sage-guard/releasesComfy Registry 节点页registry.comfy.org/zh/publishers/love/nodes/comfyui-sage-guardComfyUI-Manager 搜索在 ComfyUI 里搜sage-guard这就是你从零到成功发布的完整路径。最核心的两个坑Windows UTF-8 编码问题→ 改 comfy-cli 源码PublisherId 与 API Key 不匹配→ 确保用同一个 Publisher 账号下的 key以后更新就是改 version push 一句话的事。Publishing Nodes - ComfyUI