最开始用 ComfyUI 的时候我也没想过要专门管理工作流文件。节点少、流程简单随手保存一下就够了。但当工作流越来越多尤其是开始做图生图、局部重绘、ControlNet 系列工作流程之后问题就出来了同一个工作流可能改了七八个版本文件名从v1一路排到v11_final_final某个节点参数被误改后想退回上一版却发现根本没有上一版。更别说换电脑、重装系统、或者是和团队成员协作共享工作流时文件散落在微信、网盘、U盘里版本一乱就彻底分不清谁是最新的。这篇文章就围绕“用 GitHub 管理 ComfyUI 工作流”这一主题完整梳理从本地版本管理、远程仓库托管到团队协作和常见问题排查的全套流程。无论你是刚接触 ComfyUI 的新手还是已经积累了大量工作流文件的进阶用户都能按文章中的步骤把工作流管起来。1. 为什么要把 ComfyUI 工作流交给 Git 和 GitHub 管理1.1 工作流文件的本质是 JSONComfyUI 的工作流文件本质上是 JSON 格式的文本文件。文件里记录了每一个节点的类型、坐标、参数、连线关系以及分组、备注等界面信息。只要你打开过工作流 JSON就能看到类似nodes、links、widgets_values这样的字段。正因为它是文本文件所以特别适合用 Git 这类版本控制工具来管理。Git 能逐行跟踪文件变化记录每次修改的时间、作者和内容差异。如果某次修改把参数调坏了可以通过 Git 快速恢复到之前的任意版本。1.2 本地管理工作流的常见痛点很多 ComfyUI 用户一开始并没有版本管理的意识工作流文件直接散落在桌面或下载目录里。时间一长会遇到几种很明显的问题工作流改动后没有历史记录改坏了只能凭记忆手动调回来。文件命名混乱workflow_v1.json、workflow_v2_v2.json越来越多根本分不清哪个才是最终版。换电脑或重装系统后忘记备份工作流文件积累很久的节点方案直接丢失。多人协作时A 改了一版B 又改了一版最后到底以谁的为准没有结论。模型、自定义节点版本更新后与旧工作流不兼容但又不知道旧工作流用了哪个版本。这些问题单独看都不大但叠加在一起会严重影响生成效果的复现和迭代效率。用 GitHub 管理后每一次修改都留痕每一次调整都能回退分享和协作也都在统一的平台里完成。1.3 Git 和 GitHub 是什么有什么关系Git 是一个分布式的版本控制工具运行在本地。它负责跟踪文件变更、生成提交记录、创建分支、合并代码。GitHub 则是基于 Git 的远程代码托管平台你可以把本地 Git 仓库推送到 GitHub 上实现云备份和多设备同步。两者配合使用刚好满足 ComfyUI 工作流管理场景Git 负责本地精细控制。GitHub 负责远程备份和协作。需要强调的是Git 是核心。即使不上传 GitHub只在本机用 Git 管理工作流文件也能解决大部分版本回溯问题。上 GitHub 则能进一步解决备份和协作问题。2. 环境准备与版本说明2.1 需要准备的工具开始之前建议先确认以下几项本地已经安装 ComfyUI并且可以正常加载、导出工作流。安装方式可以是手动部署也可以是整合包不影响本文后续操作。安装好 Git 客户端。Windows 用户可以从 Git 官网下载安装包macOS 用户可以通过 Homebrew 安装Linux 用户直接使用发行版自带的包管理器安装即可。注册一个 GitHub 账号。如果还没有账号可以到 GitHub 官网注册用户名和邮箱后续会用到。关于版本这里不建议写死某个 ComfyUI 版本因为 ComfyUI 迭代很快不同版本的界面和节点信息可能有差异。本文重点讲的是通用思路你只需要保证自己的 ComfyUI 能正常导出 JSON 文件Git 能正常执行命令即可。2.2 检查 Git 是否安装成功安装完 Git 后打开终端Windows 下可以用 Git Bash 或 CMD执行下面的命令git --version如果能看到类似git version 2.x.x的输出说明 Git 已经安装成功。如果提示找不到命令说明 Git 还没有加入环境变量需要重新安装或手动配置环境变量。2.3 准备一个工作流文件在进入 Git 操作之前先在 ComfyUI 中任意打开一个你常用的工作流然后通过界面菜单导出为 JSON 文件。如果目前还没有自定义工作流直接用软件自带的默认文生图流程导出一个也行。导出的文件建议放到一个单独的目录里例如comfyui-workflows/ └── text-to-image.json后面所有 Git 操作都会围绕这个目录展开。3. 认识 ComfyUI 工作流文件的核心结构3.1 界面 JSON 和 API JSON 有什么区别在讨论管理方法之前有必要先分清 ComfyUI 工作流的两种常见格式。第一种是界面 JSON也就是你在 ComfyUI 界面中“导出工作流”得到的文件。它包含完整的节点位置、尺寸、颜色、折叠状态等界面数据双击文件可以直接拖入 ComfyUI 还原成可视化流程图。第二种是 API JSON通常用于通过 API 调用 ComfyUI 后端执行任务。它只包含执行任务所需的节点类型和参数不包含界面布局信息结构更精简。下面是界面 JSON 的简化片段目的是帮助你理解结构{ last_node_id: 3, last_link_id: 2, nodes: [ { id: 3, type: KSampler, pos: [200, 100], size: [315, 262], flags: {}, order: 3, mode: 0, inputs: [ {name: model, type: MODEL, link: 1}, {name: positive, type: CONDITIONING, link: 2} ], outputs: [ {name: LATENT, type: LATENT, links: []} ], properties: {Node name for SR: KSampler}, widgets_values: [8, fixed, 20, 7.5, randomize, 123] } ], links: [ [1, 4, 0, 3, 0, MODEL], [2, 5, 0, 3, 1, CONDITIONING] ], groups: [], config: {}, extra: {}, version: 0.4 }从这段结构可以看出界面 JSON 会记录节点在画布上的位置、尺寸、节点顺序、连线信息等。实际导出时文件内容会比这复杂得多尤其是涉及到自定义节点时每个插件节点都会带有自己的参数列表。API JSON 的结构则完全不同它更像一张“执行清单”类似下面这样{ 3: { class_type: KSampler, inputs: { seed: 123, steps: 20, cfg: 7.5, sampler_name: euler, scheduler: normal, denoise: 1.0, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0] } } }在管理工作流时建议以界面 JSON 为主因为它能直接在 ComfyUI 中还原成可视化流程。如果有服务端批量出图的需求可以额外导出一份 API JSON。3.2 为什么缺少自定义节点时会提示安装缺失包经常在社区看到有人分享工作流文件下载后拖入 ComfyUI界面却提示“请安装缺失的包以使用此工作流”。这个提示的本质是工作流 JSON 中的某个节点类型class_type在当前 ComfyUI 环境中不存在。ComfyUI 本身自带的节点数量有限很多高级功能依赖自定义节点比如 ControlNet、AnimateDiff、局部重绘扩展等。当你打开一个引用了这些插件节点的工作流时ComfyUI 会先检查环境里有没有对应的节点类如果没有就会给出缺失提示。如果工作流是通过 GitHub 管理并分享的强烈建议在 README 里写明依赖了哪些自定义节点甚至是自定义节点的版本范围。这样其他人克隆仓库后能快速通过 ComfyUI Manager 补装缺失节点而不是面对一堆 JSON 报错无从下手。3.3 工作流文件保存位置的选择ComfyUI 的工作流文件可以保存在本地任意位置。比较推荐的做法是单独建立一个目录不要和模型文件混在一起。因为模型文件动辄几个 GB不适合放进 Git 仓库而工作流文件通常只有几 KB 到几十 KB非常适合做精细的版本管理。推荐的目录结构类似comfyui-workflows/ ├── workflows/ │ ├── text-to-image.json │ ├── img2img.json │ ├── controlnet-lineart.json │ └── inpaint.json ├── assets/ │ ├── examples/ │ └── thumbnails/ ├── .gitignore └── README.md这样分门别类存放后续用 Git 维护时每次提交能清楚知道改了哪个工作流也方便其他人查看和复用。4. 本地用 Git 管理 ComfyUI 工作流4.1 初始化 Git 仓库先在准备好的工作流目录中初始化 Git 仓库cd comfyui-workflows git init执行成功后目录下会出现一个隐藏的.git文件夹这就是 Git 的版本数据库。之后所有文件变更Git 都会记录在内。接着建议设置当前仓库的用户信息这样提交记录里能知道是谁做的修改git config user.name 你的名字 git config user.email 你的邮箱这里要说明一下git config user.name和git config user.email有两种设置方式。一种是在当前仓库设置只对当前项目生效另一种是加--global参数全局设置对所有仓库生效。对于个人电脑建议使用--global一次配置好不需要每个仓库都重复设置。4.2 编写 .gitignore 排除无关文件如果你的工作流目录中除了 JSON 文件还有模型文件、临时图片、缓存文件那么需要编写.gitignore文件告诉 Git 哪些文件不纳入版本管理。一个适合 ComfyUI 工作流管理的.gitignore示例# 模型文件体积巨大不建议纳入版本管理 models/checkpoints/* models/loras/* models/vae/* models/controlnet/* models/embeddings/* # ComfyUI 运行时产生的临时目录 temp/ cache/ *.log # 备份文件 *.bak *.backup *.old # 系统文件 .DS_Store Thumbs.db # Python 缓存 __pycache__/ *.pyc注意.gitignore的匹配规则会从上到下依次生效。如果某个目录被忽略了但你又确定要提交其中某个文件可以用!来取反。比如models/checkpoints/* !models/checkpoints/说明文档.md但相对稳妥的做法是只把纯工作流 JSON 文件和说明文档纳入 Git其他大文件一律不提交。4.3 首次提交把工作流文件和.gitignore加入暂存区然后创建第一次提交git add . git commit -m init: 添加基础文生图工作流执行git add .会将当前目录下所有未被忽略的文件加入暂存区。git commit -m用于提交双引号中的内容是提交说明。建议第一次提交说明写清楚这次提交做了什么例如init: 添加基础文生图工作流提交完成后用下面的命令查看提交记录git log --oneline输出会显示一条提交记录类似a1b2c3d init: 添加基础文生图工作流这个a1b2c3d是提交 ID 的缩写后续回退版本时经常要用到它。4.4 日常迭代中的提交节奏当你在 ComfyUI 中调整了工作流例如修改了采样步数或者新增了一个 Lora 节点改完后可以将新的 JSON 文件覆盖到工作流目录中然后提交git add workflows/text-to-image.json git commit -m update: 调整文生图采样步数为30这里建议提交粒度尽量小一点。每次改动都能对应一条清晰的提交信息未来排查问题时能快速定位到具体变更。4.5 用分支管理实验性想法Git 分支很适合管理“实验性”工作流。例如现在稳定的主线工作流是text-to-image.json你想尝试加入 ControlNet 节点但又不想影响已有的正常流程。可以在主分支上创建并切换到新分支git checkout -b feature/controlnet在新分支上修改工作流文件并提交。如果调试后发现效果不错可以合并回主分支git checkout main git merge feature/controlnet如果实验失败可以直接删除这个分支不影响主分支的任何内容git branch -D feature/controlnet这类操作在纯人工管理文件时很难做到但用 Git 之后会变得非常自然。4.6 版本回退与恢复假设某次修改后发现效果变差了想回退到之前的版本。先用git log --oneline查看提交记录找到要回到的那个提交 ID。然后有两种处理方式。方式一是用git reset --hard强制回退git reset --hard 提交ID这种方式会直接丢弃工作区中未提交的修改还会让当前分支指向历史提交。操作时一定要谨慎建议先确认当前工作区没有需要保留的内容或者先提交一份“存档”再回退。方式二是用git revert生成一个反向提交git revert 提交IDgit revert不会删除历史记录而是新生成一次提交把某个提交的改动反向撤销。这种方式更适合已经推送到远端仓库的场景因为不会重写历史团队成员拉取时不容易产生冲突。5. 推送到 GitHub 实现远程备份与分享5.1 在 GitHub 上创建远程仓库本地 Git 仓库只能管理本机版本的变更。如果想换电脑后还能继续同步或者想分享给其他 ComfyUI 用户就需要把仓库推送到 GitHub。登录 GitHub 后点击页面右上角的“”号选择“New repository”。填写仓库名称例如comfyui-workflows然后选择可见性Public任何人都能看到这个仓库适合分享工作流。Private只有你自己和被你授权的协作者能看到适合个人备份和私有项目。其他选项比如 README、.gitignore可以不勾选也可以在创建后再补充不影响使用。5.2 关联本地仓库并推送在 GitHub 创建完仓库后页面会提示关联本地仓库的命令。核心操作如下git remote add origin https://github.com/你的用户名/comfyui-workflows.git git branch -M main git push -u origin main第一行命令的作用是把本地仓库与远程仓库建立关联origin是远程仓库的默认别名。第二行命令把当前分支重命名为main这是 GitHub 默认的主分支名。第三行命令把本地main分支推送到远程-u参数会把本地分支和远程分支建立跟踪关系之后直接执行git push即可。执行完git push后终端会要求输入 GitHub 用户名和密码或令牌。从当前 GitHub 的认证方式看很多场景不再支持直接用账号密码建议提前在 GitHub 个人设置中生成一个 Personal Access Token个人访问令牌然后把令牌作为密码输入。推送成功后刷新 GitHub 仓库页面就能看到工作流文件已经上传到远程仓库。5.3 在新电脑上克隆仓库换电脑或重装系统后只需要执行克隆命令就能把整个工作流仓库拉到本地git clone https://github.com/你的用户名/comfyui-workflows.git克隆完成后把工作流 JSON 文件重新拖入 ComfyUI 即可正常使用。如果工作流依赖了自定义节点还需要先安装对应的插件。5.4 后续推送与拉取在本地修改工作流并提交后推送到 GitHubgit push在另一台电脑上拉取最新修改git pullgit pull会从远程仓库拉取最新提交并尝试与本地分支合并。多设备同步时这一点非常方便。6. 协作场景下的工作流更新与冲突处理6.1 多人协作的基本流程当团队多人共同维护一批 ComfyUI 工作流时建议采用“分支 PR”的方式。基本流程如下成员先从主仓库克隆代码或者 Fork 到自己的账号下。每次修改前从最新的main分支创建自己的功能分支。在功能分支上修改工作流并提交。推送分支到 GitHub并发起 Pull Request。相关负责人审查后合并到main分支。这样做的好处是每次工作流变更都经过评审和记录不会出现在线乱改、互相覆盖的情况。6.2 工作流 JSON 为什么容易冲突ComfyUI 导出的界面 JSON 有时是一整行压缩后的内容不像普通代码那样易于阅读。当两个人同时修改同一个工作流文件时Git 很可能无法自动合并于是产生冲突。冲突的本质是Git 发现同一份文件的同一段内容在两条分支上发生了不同修改无法判断应该保留哪个版本。遇到这种情况不要怕按冲突标记手动解决即可。假设冲突内容出现在workflows/text-to-image.json中文件里会出现类似下面的标记 HEAD 当前分支的版本内容 另一条分支的版本内容 feature/xxx你需要手动确定保留哪一部分然后把 HEAD、、 feature/xxx这些标记行全部删除再保存文件最后执行git add workflows/text-to-image.json git commit -m fix: 解决文生图工作流合并冲突减少冲突的办法有两个尽量在独立的 JSON 文件中维护不同的工作流减少多人同时修改同一个文件的情况。每次开始新改动前先git pull拉取最新代码保证本地基于最新版本修改。6.3 用 git diff 查看工作流参数变化如果你想知道两个版本的工作流到底改了哪些参数可以用git diff来对比。查看尚未提交的修改git diff workflows/text-to-image.json查看某个历史提交和工作区当前版本的差异git diff 提交ID workflows/text-to-image.json不过对于压缩成一行的工作流 JSONgit diff输出可能不够直观。一个折中办法是在 ComfyUI 中把 JSON 格式化后再提交虽然文件体积会变大但可读性会好很多git diff也能展示出具体的参数变化。7. 最佳的仓库组织与配套文档方案7.1 为工作流仓库编写 README一个清晰的工作流仓库不只是堆几个 JSON 文件还应该有说明文档。README 建议包含这些内容仓库用途。工作流文件列表。每个工作流的适用场景和参数说明。依赖的自定义节点。推荐的基础模型类型。示例图片。一个简单的 README 模板# ComfyUI Workflows 本仓库用于管理我的 ComfyUI 工作流文件所有文件都可以直接拖入 ComfyUI 使用。 ## 快速开始 1. 克隆本仓库到本地。 2. 打开 ComfyUI。 3. 将 workflows/ 目录下的 JSON 文件拖入界面。 4. 如提示缺失节点请先通过 ComfyUI Manager 安装对应插件。 ## 工作流列表 | 文件 | 用途 | 依赖节点 | 备注 | | --- | --- | --- | --- | | text-to-image.json | 基础文生图 | 无 | 需要 SD1.5/SDXL 模型 | | img2img.json | 图生图 | 无 | 需要输入图像 | | controlnet-lineart.json | 线稿上色 | ControlNet 辅助节点 | 需要线稿图 |7.2 用 Tag 管理重要版本当某个工作流经过验证效果稳定且适合对外分享时可以打一个标签例如v1.0.0git tag -a v1.0.0 -m 文生图工作流稳定版 git push origin v1.0.0之后如果工作流依赖的模型或插件有变化也可以通过 GitHub 的 Release 功能发布带说明的版本包。7.3 提交信息规范建议提交信息最好简洁且具有描述性。推荐使用下面的前缀feat新增工作流。fix修复工作流参数或连线问题。docs更新 README 或说明文档。chore整理目录、调整.gitignore等维护性操作。示例feat: 新增 ControlNet 线稿上色工作流 fix: 修复 img2img 中采样器连接错误 docs: 增加工作流依赖节点说明7.4 不要在 JSON 中提交敏感信息ComfyUI 本身不存 API Key但部分插件或自定义脚本可能允许填写 Token、密钥或服务器地址。这类敏感信息建议不要直接写入工作流 JSON 并提交到 GitHub。如果确实需要这类配置可以考虑使用环境变量读取配置。将敏感字段从工作流中拆离单独用配置文件维护并把该文件加入.gitignore。仓库设置为 Private并严格控制协作者权限。7.5 高阶玩法用 GitHub Actions 自动校验 JSON如果团队有精力做进一步工程化可以利用 GitHub Actions 在每次提交时自动校验 JSON 格式是否合法避免一个损坏的工作流文件被合入主分支。下面是一个简单的示例核心思路是当workflows/目录下的文件发生变化时自动对所有 JSON 文件执行格式校验name: 校验工作流 JSON on: push: paths: - workflows/** jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: 检查 JSON 格式 run: | for f in workflows/*.json; do python -m json.tool $f /dev/null || echo JSON 格式错误: $f done这个示例用到actions/checkout实际版本建议以 GitHub Actions 官方市场的最新版本为准。这里只演示思路当你对 GitHub Actions 有基础了解后可以扩展成更完整的校验流程。8. 常见问题与排查思路问题现象常见原因解决思路GitHub 页面或 push 操作经常超时网络波动、DNS 解析异常、访问不稳定检查本地网络错峰重试必要时使用公开镜像站点但注意时效与安全隐患不要依赖不明第三方加速工具git push 被拒绝远程仓库有本地没有的新提交先执行git pull解决冲突后再推送中文文件名乱码或无法识别Git 默认对中文文件名转义设置git config core.quotepath false然后重新查看状态.gitignore不生效文件已经被 Git 跟踪使用git rm --cached 文件取消跟踪后再提交合并工作流 JSON 产生冲突多人同时修改同一文件手动保留正确版本并删除冲突标记调整协作方式减少同文件并发修改提交了大体积模型文件模型文件没有加入.gitignore使用git rm --cached移除跟踪重新提交并清理 Git 历史拖入工作流提示“请安装缺失的包”工作流依赖自定义节点但当前环境未安装通过 ComfyUI Manager 搜索安装对应节点或查看 README 中的依赖说明工作流 JSON 无法在 ComfyUI 打开文件导出不完整、手动编辑时破坏了结构使用python -m json.tool校验格式重新导出 JSONgit reset --hard后想找回丢失内容本地未提交的修改被重置覆盖如果曾执行过git commit可以尝试git reflog找回之前的提交记录在这张表格中GitHub 访问问题是最容易遇到且最不方便排查的一项。正常的解决思路是检查网络连接、刷新 DNS、错峰访问。如果确实有镜像站可用也建议以官方仓库为最终数据源镜像站只做临时下载用途不要作为长期依赖。.gitignore不生效是一个高频问题。原因是.gitignore只对未被 Git 跟踪的文件生效。如果某个文件在添加.gitignore之前已经被git add过Git 会继续跟踪它即使后来写入了忽略规则也没效果。此时需要先取消跟踪git rm --cached models/checkpoints/某个大文件然后再次提交该文件就会被移出版本管理但本地文件仍然保留。9. 从本地管理到团队协作的路径总结这套用 GitHub 管理 ComfyUI 工作流的方案本质上是把软件工程中成熟的版本控制思路平移到了 AI 绘画流程管理里。对个人用户来说先学会git init、git add、git commit、git push、git pull这五个命令就足够解决 90% 的工作流管理需求。对团队用户来说再补充分支、合并、PR 评审就能形成一套规范的工作流协作流程。有几点经验值得放在最后强调。第一不要等到工作流很大、很复杂了再开始管理最好的时机就是现在。哪怕只有一个 JSON 文件也建议先纳入 Git 仓库再慢慢补充文档。第二每次修改后要及时提交提交信息写清楚。不要攒了一堆改动然后一次性提交否则未来回溯时很难定位某次具体变更。第三工作流文件如果包含依赖节点信息把依赖写进 README。这样不管是自己重装环境还是别人克隆仓库都能快速恢复出同样的生成效果。第四涉及删除、回退、强制推送这类破坏性操作时先确认有没有备份再动手。条件允许时可以先在一个临时分支上验证操作结果。第五模型文件、配置文件、临时图片尽量保持在 Git 仓库之外仓库里只保留纯文本形式的工作流文件和相关文档这样仓库体积小、历史清晰、协作也顺畅。接下来你可以在自己的 ComfyUI 环境中试着把当前最常用的一个工作流导出、初始化 Git 仓库、提交到 GitHub。完成这一步再考虑整理历史工作流、写 README、或者体验 GitHub Actions 自动校验。版本管理这件事越早开始收益越大。