使用Git管理ComfyUI工作流：从JSON结构到团队协作实战

实际使用 ComfyUI 时最有价值的东西往往不是模型文件而是你已经调通的工作流。一个打磨好的文生图工作流包含合适的采样器、正确的 VAE 处理、合理的 LoRA 权重可能比单独的 checkpoint 更值得保存和复用。但如果只是把 json 文件丢在本地过两周再打开你很可能记不清它和另一份 json 有什么区别也不记得它依赖哪些自定义节点。把工作流交给 GitHub 管理是解决这类问题的常见做法。本文会从 ComfyUI 工作流的文件结构讲起给出一个可在 GitHub 上维护的仓库结构同时覆盖插件缺失、版本回退、多人协作和提交前检查。无论你是个人爱好者还是在团队里统一维护推理模板这套方法都能直接落地。1. 先搞清楚 ComfyUI 工作流到底为什么需要 Git1.1 工作流默认是 JSON 文件天然适合文本版本管理ComfyUI 的工作流本质上是 JSON 文件。你在画布上拖入的每个节点、连接节点的每根线、填写的每个参数都会被序列化成结构化的 JSON 字段。这意味着它具备文本文件的所有优点体积小、可读、可以放进 Git 仓库做差异对比也可以复制给其他人复用。从 ComfyUI 前端保存工作流时通常会得到一个.json文件。这个文件既可以在 ComfyUI 里重新打开也可以作为文本直接阅读。你不需要理解全部字段但至少要知道它保存了三类信息有哪些节点节点的类型是什么。节点与节点之间如何连线数据流从哪个输出端到哪个输入端。每个节点的参数值比如 checkpoint 文件名、正向提示词、采样步数、CFG 值、图片尺寸。Git 管理文本文件的能力非常成熟。使用git diff可以看到两份工作流之间的具体差异哪个节点的参数被改过提示词发生了什么变化哪条连线被删除都会显示成可读的变更记录。这是“把工作流文件复制一份然后改名”完全做不到的。1.2 只用 .json 文件管理会遇到哪些问题很多人的工作流管理方式很简单生成满意的图之后把 json 文件下载到本地按日期或者按效果重命名。这个做法在前几个文件时还能用一旦文件超过几十个问题就会集中出现。第一个问题是版本覆盖。同一个工作流被反复调整时你很容易同时保存v1、v2、v3、最终版、最终版2。一周后你根本分不清哪个版本成功哪个版本是失败尝试。如果某次改动导致效果变差也很难找到上一次能用的版本到底在哪里。第二个问题是协作困难。你把自己调好的工作流发给同事对方打开后可能提示缺少自定义节点或者模型路径不一致。你只能靠聊天记录反复确认“你用的是哪个插件版本”“模型文件从哪里下载”。如果工作流背后有一份明确的依赖清单这类沟通成本会大幅下降。第三个问题是缺少变更说明。单独的 json 文件不会记录“为什么把采样器从 Euler 改成 DPM 2M”。等你回头再看你会忘记当时的决策依据。Git 的 commit message 恰好可以承载这类说明。1.3 GitHub 管理带来的具体收益把工作流放进 GitHub 仓库本质上是用工程化方式管理 AI 绘图资产。你仍然需要理解 ComfyUI 的节点逻辑但流程可以变得更可控。每次修改都能形成 commit可以随时回退。可以通过分支保留探索性实验主分支保持可用状态。可以写 README 说明工作流用途、依赖模型、适用场景。多人协作时别人可以先看说明再拉取工作流。GitHub 提供 Issue 和 Pull Request 机制适合团队内做工作流评审。需要强调的是GitHub 只是载体核心思想是让工作流文件处于版本管理之下。如果团队网络策略不方便使用 GitHub换成 GitLab 或内网 Git 服务命令和目录结构基本不变。2. 打开一个工作流 JSON搞懂它保存了什么2.1 三种常见格式编辑器工作流、API 格式、PNG 内嵌元数据ComfyUI 工作流在流传过程中至少有三种形态很多人在分享时容易搞混。第一种是编辑器工作流格式也就是在 ComfyUI 前端按保存后得到的文件。它包含节点坐标、分组、展示信息等前端布局内容适合重新加载到画布里继续编辑。第二种是 API 格式。ComfyUI 可以通过菜单导出 API 格式的 JSON这种格式剔除了大部分前端布局信息保留的是可直接提交给 ComfyUI 后端的执行结构。在需要调用 ComfyUI 的 HTTP API 时通常使用这种格式。如果你用 Python 代码驱动 ComfyUI会发现 API 格式更接近服务端理解的数据结构。第三种是 PNG 内嵌元数据。ComfyUI 在生成图片时会把工作流信息写入 PNG 的元数据里。你保存图片后直接把图片拖回 ComfyUI 画布工作流会被还原出来。这也是社区分享工作流最方便的方式。对 GitHub 管理来说主体应该保存编辑器工作流格式因为它的可读性和可编辑性最好。API 格式可以作为副产品保留供自动化流程使用。2.2 工作流 JSON 核心字段速览下面是一份简化后的工作流 JSON只保留三个节点加载 checkpoint、正向提示词、采样。这份示例用于说明结构实际 ComfyUI 生成的内容会包含更多字段。{ last_node_id: 3, last_link_id: 2, nodes: [ { id: 1, type: CheckpointLoaderSimple, pos: [40, 120], size: [320, 100], flags: { collapsed: false }, order: 0, mode: 0, inputs: [], outputs: [ { name: MODEL, type: MODEL, links: [1], slot_index: 0 }, { name: CLIP, type: CLIP, links: [2], slot_index: 1 }, { name: VAE, type: VAE, links: null, slot_index: 2 } ], properties: { Node name for SR: CheckpointLoaderSimple }, widgets_values: [my-model.safetensors] } ], links: [ [1, 1, 0, 2, 0, MODEL], [2, 1, 1, 2, 1, CLIP] ], groups: [], config: {}, extra: {}, version: 0.4 }重点看几个字段。nodes是节点数组每个节点有唯一 id 和 type。type 决定这个节点是加载模型、写提示词、采样还是解码图片。widgets_values保存的是节点面板上填写的参数顺序与前端控件顺序一致。links保存连线信息每条线用数组表示例如[1, 1, 0, 2, 0, MODEL]含义是连线 id 为 1从节点 1 的第 0 个输出端连到节点 2 的第 0 个输入端数据类型是 MODEL。groups是画布上的分组框不影响执行只影响展示。extra可能保存标题、作者信息用来记录工作流来源。version字段会随 ComfyUI 版本变化不同版本打开同一份工作流兼容性可能有差异。2.3 为什么说从 ComfyUI 保存的 JSON 不适合无脑合并工作流 JSON 适合做版本跟踪但并不适合像普通代码那样频繁合并修改。原因在于ComfyUI 保存的节点 id 和连线 id 由前端自动分配两个人在不同分支上同时修改同一份原始工作流生成的节点 id 可能完全不一致。例如甲在分支 A 给采样器增加了一个 LoRA 节点乙在分支 B 把基础模型从 SD1.5 换成了 SDXL。两个人改的都是同一个逻辑区域但 Git 合并时看到的可能是两段完全不同的节点 id 区域冲突会很有迷惑性。此时手动解决冲突的难度远高于普通 Java 或 JavaScript 代码。所以推荐的做法是核心人员维护一份主分支其他成员通过新建文件或明确分工的方式避免同时修改同一个工作流文件。如果团队确实需要并行实验宁可让每个人在工作流副本上做实验再由负责人把最终效果合并回主工作流也不要直接在同一个 json 上做复杂的 Git 合并。3. 把工作流放进 GitHub 仓库的完整落地步骤3.1 设计仓库目录工作流、说明、依赖清单分开创建仓库之前先设计目录结构。常见问题是把所有 json 平铺在根目录再加一两个 README短时间内还好工作流数量到 20 个以上后根本分不清类别。下面是一套适合个人和团队使用的目录结构comfyui-workflows/ ├── README.md ├── .gitignore ├── custom_nodes.manifest ├── workflows/ │ ├── text-to-image/ │ │ ├── basic-sdxl.json │ │ ├── sdxl-with-lora.json │ │ └── README.md │ ├── image-to-image/ │ │ └── img2img-refine.json │ └── video-generation/ │ └── wan-test.json ├── models/ │ └── README.md └── assets/ └── workflow-screenshots/workflows目录按用途或任务类型分子目录。每个子目录下除了工作流 json还放一个 README说明每份工作流的输入、输出、预期效果和依赖模型。models/README.md用于记录模型文件名、下载来源和哈希值。assets目录保存工作流的截图方便别人在仓库里快速看到效果。custom_nodes.manifest是自定义节点清单可以直接写成纯文本记录每个插件仓库的地址、安装目录名称和固定 commit。3.2 初始化仓库并提交第一个版本目录准备好后进入项目目录执行下面的命令。cd comfyui-workflows git init然后把工作流文件复制到对应目录检查当前文件状态。git status第一次提交前先确认.gitignore的内容。如果这个仓库只保存工作流推荐忽略以下内容models/* input/ output/ temp/ .DS_Store *.logmodels/*用来避免把大型模型文件提交进仓库。ComfyUI 的模型文件经常是几个 GB 甚至十几个 GB放进 Git 仓库会导致仓库体积失控别人克隆时也会非常痛苦。模型文件应该通过说明文档记录下载地址而不是直接提交。确认忽略规则后添加全部文件并提交。git add . git commit -m chore: 初始化工作流仓库加入基础文生图工作流然后在 GitHub 上创建一个空仓库并把本地仓库关联到远端。具体仓库地址以你实际创建为准示例使用占位地址git remote add origin gitgithub.com:your-name/comfyui-workflows.git git branch -M main git push -u origin main这里需要留意GitHub 的认证方式一直在调整。如果使用 SSH需要提前配置好公钥如果使用 HTTPS第一次推送时可能会要求输入账号或使用令牌。不要在 git 命令里明文写入账户密码更不要把令牌写进代码仓库。3.3 添加说明文件和版本记录仓库骨架搭好后补充 README。README 不要只写“这是工作流仓库”要写清楚三件事仓库里有什么、每份工作流怎么用、模型和插件从哪里获取。# comfyui-workflows 个人 ComfyUI 工作流仓库所有工作流基于 ComfyUI 2026 年版本测试。 ## 目录说明 - workflows/text-to-image文生图工作流 - workflows/image-to-image图生图工作流 - custom_nodes.manifest自定义节点依赖清单 ## 快速开始 1. 安装 ComfyUI 并确认版本与工作流版本兼容。 2. 按 custom_nodes.manifest 安装自定义节点。 3. 关闭 ComfyUI 后将 json 拖入前端画布。 4. 根据 README 提示检查模型文件是否齐全。提交说明文件后就可以打第一个标签。标签非常适合标记“这个版本可用”或“这个版本搭配了特定模型集”。git add README.md custom_nodes.manifest git commit -m docs: 添加仓库说明与依赖清单 git tag v0.1.0 git push origin main --tags打标签的意义在于工作流 json 本身不会记录自己是否完整可用但标签可以。每当你确认一个版本能够在当前环境下稳定执行就打个 tag。以后回退到某个成功版本时只需要查 tag。4. 多人协作时如何管理分支与版本4.1 单人使用标签和回退单人使用时Git 最有价值的能力是回退。假设你准备把文生图工作流从 SD1.5 升级到 SDXL但不确定效果是否更好。你可以在当前可用版本上打一个标签git tag v0.1.0-sd15-stable然后继续修改工作流提交新版本。如果新版本效果不满意你可以快速回到旧版本查看。git checkout v0.1.0-sd15-stable -- workflows/text-to-image/basic-sdxl.json这个命令会把旧版本文件恢复到当前工作区等于在保留新版本 commit 的前提下把文件内容还原到了可用的状态。单人环境下不要害怕提交。每完成一个有效调整就提交一次。提交信息写清楚改动意图例如“把采样步数从 20 调整到 30测试细节提升效果”或者“新增 IPAdapter 节点用于风格迁移”。4.2 多人协作分支与 Pull Request多人协作的重点不是让所有人都能改主分支而是通过分支协作减少互相干扰。推荐流程如下负责人从main分支拉出本次实验分支。分支上调整工作流或新增文件。验证效果后提交代码。创建 Pull Request在描述里写清楚改动内容、测试结果、依赖的模型。负责人评审后合并。创建分支和切换分支的命令git switch -c feature/sdxl-lora-test提交后推送分支git add workflows/text-to-image/sdxl-with-lora.json git commit -m feat: 新增 SDXL LoRA 文生图工作流 git push -u origin feature/sdxl-lora-test在 Pull Request 评审时可以在评论区附上生成效果图。这比单纯在聊天工具里发文件更容易追溯。合并进 main 前确认 custom_nodes.manifest 也同步更新否则别人拿到工作流后同样会因为缺少节点而无法运行。4.3 锁定自定义节点版本避免“换个电脑就报错”工作流放在 GitHub 上别人克隆下来后最常遇到的就是自定义节点版本不一致。同一个插件旧版本提供的节点类型可能已经改名或者节点参数结构和当前工作流不匹配。为了让工作流可复现必须把自定义节点版本记录下来。在custom_nodes.manifest中可以按固定格式记录CustomListNode | https://github.com/example/ComfyUI-ExampleNode | a1b2c3d4e5f6列出的三项分别是插件目录名、插件仓库地址、验证通过的 commit hash。安装时进入 ComfyUI 的custom_nodes目录按清单克隆并切换到对应 commitcd custom_nodes git clone https://github.com/example/ComfyUI-ExampleNode.git cd ComfyUI-ExampleNode git checkout a1b2c3d4e5f6如果你的团队使用插件管理面板来安装节点也可以把清单内容作为参考但最终仍要确认实际安装的 commit 和验证通过的 commit 一致。锁定 commit 是比“安装最新版”可靠得多的方式。5. 出现“缺失插件/缺失节点/请安装缺失的包”时怎么排查5.1 先判断是缺少自定义节点还是缺少模型文件GitHub 管理工作流后最常见的错误发生在别人拉取仓库拖入 json然后看到类似下面的提示请安装缺失的包以使用此工作流。 要安装缺失的节点请先在你的 python 环境中运行...这句话只说明了一个事实ComfyUI 当前环境里缺少某种依赖。但具体缺什么需要进一步判断。常见情况有两类处理方式完全不同。第一类是缺少自定义节点。比如工作流里使用了 IPAdapter 节点但当前 ComfyUI 的custom_nodes目录里没有对应插件。前端会提示某个 node type 不存在工作流加载后显示为红色节点标记为 missing。第二类是缺少模型文件。比如CheckpointLoaderSimple节点的widgets_values里填写了my-model.safetensors但新环境的models/checkpoints目录里没有这个文件。此时节点本身存在加载不会报缺少节点但执行到模型加载时会失败日志会提示文件不存在。排查时先看提示发生在加载阶段还是执行阶段。加载阶段弹窗提示缺失节点通常指向插件缺失执行阶段才报文件路径错误通常指向模型缺失。5.2 按顺序排查的步骤遇到缺失节点或缺失包时不要直接下载最新版插件按下面的顺序排查。第一步确认 ComfyUI 版本。工作流里的节点类型和参数结构受 ComfyUI 版本影响旧版 ComfyUI 无法支持新版节点特性。第二步打开custom_nodes目录检查清单里记录的插件是否已经存在如果存在确认 commit 是否一致。第三步查看缺少节点的对应插件仓库找到该节点所属插件安装到custom_nodes目录。第四步安装完成后重启 ComfyUI。很多插件需要在启动时注册节点热刷新不一定生效。第五步如果安装的是 Python 插件检查插件目录下的requirements.txt并安装 Python 依赖。第六步重新加载工作流观察报错是否消失如果仍报错查看 ComfyUI 启动日志里的 Python traceback。下面用表格总结这条排查链路排查步骤操作确认方式1确认 ComfyUI 版本启动页或稳定标签说明2检查 custom_nodes 目录目录下是否有插件目录3检查插件 commitgit log 与 manifest 对照4检查 Python 依赖安装 requirements.txt5重启 ComfyUI前端不再提示 missing6查看日志日志里无 traceback5.3 用依赖锁定文件复现环境排查一次缺失节点后应该把结论沉淀到仓库里避免下一个人重新踩坑。最直接的方式是执行下面两条命令把环境信息保存到仓库pip freeze requirements-frozen.txt然后把这份文件提交到仓库。需要说明的是ComfyUI 本身可能有独立的虚拟环境或整合包环境直接pip freeze会把整套 Python 包都列出来文件会很长。更精细的做法是只记录插件目录下的requirements.txt或只记录与当前工作流直接相关的包。python -c import torch; print(torch.__version__) python -c import transformers; print(transformers.__version__)将输出交给工作流使用者也很有帮助。问题排查完成并不代表结束应该在仓库里补一条提交更新custom_nodes.manifest和 README说明这次缺失产生的原因。6. 一套可持续使用的仓库规范6.1 提交前检查清单为了避免出现“工作流提交了但别人跑不起来”的情况可以固定一套提交前检查流程。下面这份清单可以直接改造成团队规范。检查项检查方式不通过时的处理工作流能正常加载在干净环境拖入 json补齐缺失节点工作流能正常执行跑通一次生成修复报错并重测模型文件有说明查看 models/README.md补充文件名和来源自定义节点有清单比对 custom_nodes.manifest更新清单提交信息能说明改动git log 查看补充 commit message敏感信息未入库搜索 token、路径删除并刷新凭据检查清单看起来简单但在多人协作时非常有效。尤其“工作流能正常执行”这一条很多人会想当然认为“能加载就是能跑”实际上工作流加载成功只代表节点类型存在模型路径、显存占用、插件参数都可能成为执行失败的原因。建议在本地准备一个专门用来验收的 ComfyUI 测试环境这个环境不装多余插件只装工作流需要的最小依赖。每次提交前在这个环境里跑通一次能大大减少团队协作中的返工。6.2 常用 Git 命令速查表使用 GitHub 管理 ComfyUI 工作流实际上只需要掌握少量 Git 命令。下面这张表列出高频命令和用途。场景命令说明查看改动git status查看工作区状态查看差异git diff查看未提交的改动提交git commit -m docs: ...提交到本地仓库推送到远端git push提交到 GitHub恢复文件git checkout tag -- file从历史版本恢复文件打标签git tag v0.1.0标记可用版本创建分支git switch -c feature/xxx创建并切换分支合并分支git merge feature/xxx合并到当前分支不要把 GitHub 客户端选项背熟作为目标真正重要的是理解这几种操作背后的状态变化。工作流文件提交前是未暂存状态git add后变成暂存状态git commit后进入本地仓库git push后进入远端仓库。这四个状态理解了日常使用基本就够。6.3 进一步可以做的自动化方向仓库稳定运行后可以继续扩展一些自动化能力。第一个方向是 JSON 语法检查。在 GitHub Actions 里安装一个简单脚本读取所有 json 文件并执行json.load能提前发现手误造成的语法错误。这个检查虽然简单但能避免坏文件污染主分支。第二个方向是依赖差异提醒。如果custom_nodes.manifest有固定格式可以写一个小脚本比较当前环境和清单中的 commit 是否一致输出差异。这样在本地运行就能提前知道哪些插件版本不匹配。第三个方向是生成工作流索引。可以写脚本扫描workflows目录把每份 json 的标题、节点类型、模型文件提取出来生成一份INDEX.md。配合 GitHub 的页面展示团队就能快速检索到可复用的工作流。第四个方向是结合模型文件哈希。在models/README.md中记录模型的 SHA256 哈希写一个验证脚本检查本地模型文件是否和仓库记录一致。这样换机器时不用等到执行阶段才暴露模型损坏或版本错误。这些自动化不需要一开始就做建议先把基础仓库跑通等团队的工作流数量超过 20 份、协作频率变高后再按需引入。对于刚入手 ComfyUI 的开发者建议从今天开始做两件事第一把当前可用的工作流整理进一个独立仓库打上标签第二在工作流 json 所在目录写下它依赖的模型和插件。坚持三周后你回头再翻自己的工作流会很庆幸当时做了版本记录。对于正在带领团队维护 ComfyUI 模板的开发者优先把custom_nodes.manifest和模型哈希两件事落地这能解决大部分“别人仓库跑不起来”的协作问题。