一个解压好的数据集、一份编译产物、几个 PSD 原图可能只是随手git add .推送时就撞上了这堵墙remote: error: File model/weights.bin is 146.80 MB; this exceeds the platforms file size limit of 100 MB remote: error: GH001: Large files detected. ! [remote rejected] main - main (pre-receive hook declined) error: failed to push some refs to ...本地仓库里好好的提交也成功了远端就是不收。这种“Git 推送失败远程仓库提示文件超过 100MB 限制”的问题几乎每个团队迟早都会遇到。本文会从报错机制说起给你一套决策清单、两条完整的实操路线删除历史文件 / Git LFS 迁移最后附上高频问题的排查记录。无论你是刚入门的新手还是已经被队友的大文件坑过的老手照着下面的步骤走基本能一次把问题解决。1. 先看懂报错100MB 限制到底卡在哪一层1.1 限制来自远端平台而不是 Git 本身先把一个容易被误会的点说清楚Git 本身并不限制单文件大小。你在本地仓库里提交一个 1GB 的文件git commit不会报错git log也正常显示。100MB 这个数字是远端托管平台在服务端施加的约束。更准确地说平台在服务端装了一类叫 pre-receive hook 的钩子程序。每次收到推送请求它会在真正更新分支引用之前把这次推送涉及的所有对象扫描一遍只要发现单个 blob文件内容对象超过阈值就拒绝整个推送。这个机制类似仓库门口的安检Git 把东西一路运到了门口门卫按自己的规则量尺寸超标的包裹一律不进库。理解这一点很重要因为不少补救思路如果建立在“本地没问题那就没事”的错觉上后面就会发现完全跑不通。1.2 为什么“删掉文件再提交”依然失败这是最常见的直觉反应文件太大那我删掉再提交一次不就行了结果 push 还是失败很多人当场懵住。原因出在 Git 的存储模型每个提交commit都记录着一整棵文件树tree的快照每个文件快照对应一个 blob 对象。哪怕你在最新提交里把大文件删掉了只要这个 blob 还被历史中的某个旧提交引用着它就仍然存在于提交链里。推送时服务端扫描的是这次推送包含的全部对象而不是只看最新快照所以大文件在服务端眼里依然“在包里”。打个比方你把一个超重的大箱子塞进了一列火车中途到站后把箱子扔下车但火车已经带着它驶过了检查站。你在下一站扔不扔都不影响检查站已经拍下的记录。要让服务器“看不见”这个大文件唯一办法是重写历史让那些引用它的旧提交彻底消失而不是简单地补一个删除提交。1.3 把大文件从仓库历史里找出来报错信息里一般会直接给出文件路径这样最省事。但有时候历史里有多个大文件或者日志被截断这时候就需要自己动手排查。下面这条命令能在整个 Git 对象库里按大小列出前 20 个 blobgit rev-list --objects --all \ | git cat-file --batch-check%(objecttype) %(objectname) %(objectsize) %(rest) \ | awk $1 blob {print $3, $4} \ | sort -rn | head -20输出是“字节数 文件路径”两列把数字除以 1048576 就是 MB。注意命令里的--all表示扫描所有分支和标签引用如果大文件只存在于某一个分支在当前分支上用git ls-files是看不到的。2. 动手前先决策四条可行路线怎么选2.1 决策前必须回答的三个问题在敲任何命令之前先回答三个问题第一这个大文件现在还需要吗第二如果需要它必须放进 Git 仓库做版本管理吗第三如果必须管理它是经常变动的二进制文件还是基本不变的资源包这三个问题直接决定你后续走哪条路。盲目跟着网上的教程重写历史或者一上来就上 Git LFS都可能让原本简单的事情变得更复杂。我见过太多次有人为了让一个根本不该入库的安装包通过检查花了两个小时折腾 LFS最后发现这个包在构建脚本里就能自动下载纯属白忙一场。2.2 四条路线的对比路线核心动作优点代价 / 风险典型场景A 彻底移除重写历史删掉大文件仓库最干净一劳永逸提交哈希全变全体成员需重新同步误提交 / 不再需要的临时产物B LFS 接管用 Git LFS 托管大文件保留版本管理绕过单文件限制引入额外工具依赖受平台配额限制设计素材、模型权重、音视频资源C 外部存储文件放对象存储仓库只留脚本不重写历史不破坏现有流程版本映射要自己维护拉取强依赖外部构建产物、依赖包、数据集D 拆仓库 / 调配置拆分子模块或换用可调上限的平台从结构上根治大仓库问题改造量大迁移成本高仓库已经臃肿到影响日常使用2.3 一般情况下我会怎么选如果文件确实是误提交或者历史里混入了一堆过期产物选 A 最干净。如果文件是需要长期维护的二进制资产选 B。如果文件本质上属于“构建过程中能再生成”的东西选 C 才是根治方案——这类文件不该进 Git也不该进 LFS留在仓库里只会持续污染体积。排优先级时一般先考虑“不重写历史”的方案再考虑“重写历史”的方案因为历史重写的协作成本不低。但如果大文件已经进了提交历史路线 C 也只能解决“以后不再入库”并不能让当前历史里的 blob 消失最终还是需要 A 或 B 来收尾。3. 路线 A 实操彻底移除大文件并重写历史3.1 先停止跟踪并补上忽略规则进入实操之前先把工作区收拾干净。如果文件还要留在磁盘上、只是不再纳入 Git执行git rm --cached model/weights.bin如果文件连同工作区副本都不需要了直接git rm model/weights.bin。无论哪种都建议马上把对应路径写进.gitignore否则后面重写完历史、远端总算干净了你又可能手滑把它加回来。这一步本身也会产生一个提交但它不是解决问题的关键真正起作用的是后面的历史重写。如果只想快速让本地不再跟踪它这一步就够了但要让远端接受推送必须继续往下走。3.2 历史重写工具选型接下来要做的是让仓库历史里不再出现大文件可选的工具有三个git filter-branchGit 自带的工具功能完整但性能和可用性都比较差官方文档也建议新项目用 filter-repo 替代。我只有在小仓库应急时才会用它。git filter-repoPython 实现速度比 filter-branch 快一到两个数量级功能明确是目前的主流选择。安装方式一般是pip install git-filter-repo或brew install git-filter-repo。BFG Repo-CleanerJava 工具专门用来干“删文件、删目录、替换字符串”这类脏活超大仓库场景下很快但需要额外安装 Java 运行时。三者的参数不一样但思路一致遍历所有提交按规则改写其中某些文件引用然后生成一条新的提交链。3.3 用 filter-repo 删除指定文件的完整步骤先用一段干净的环境把仓库完整克隆下来。推荐处理完就抛弃这个临时目录不要在你日常开发的目录里直接跑以防误伤未提交的改动。pip install git-filter-repo # 或 brew install git-filter-repo git clone 远端仓库地址 /tmp/cleanup-repo cd /tmp/cleanup-repo git filter-repo --invert-paths --path model/weights.bin--path指定要删除的文件路径可以写多个--path-glob *.zip可以用通配符批量删除。--invert-paths的意思是“除了这些路径之外全部保留”相当于把这些路径从历史里反向过滤掉。跑完之后filter-repo 会刻意删掉 origin 远程配置这是防误操作的设计目的是强迫你确认之后才允许把重写后的历史推出去。3.4 清理残留对象并强制推送历史重写完成后旧提交链在本地其实还有残留引用reflog 里的记录尤其容易造成混乱。不清理的话即便推送成功这些旧对象也可能在未来某个时刻带来奇怪的报错。先收尾git reflog expire --expirenow --all git gc --prunenow --aggressive然后重新添加远程并推送git remote add origin 远端仓库地址 git push --force-with-lease origin main这里强烈建议用--force-with-lease而不是--force。它会在推送前检查本地记录的远端引用和实际远端引用是否一致能在一定程度上兜住“远端已经被别人更新过”的情况减少冲掉同事提交的风险。如果要推所有分支和标签可以分别加--all和--tags。推完之后第一时间通知团队。历史被重写意味着所有同事的本地分支都和新远端对不上了。最省心的做法是让相关成员备份自己未推送的改动之后重新 clone。3.5 只在最后一次提交时的快捷处理如果大文件只是最近一次提交里刚加入的历史重写整套流程就显得笨重。此时可以用更快的方式先把文件从暂存区移除然后修正刚才的提交。git rm --cached model/weights.bin git commit --amend git push --force-with-lease origin main前提是这大文件只出现在你的开发分支的最后一次提交里而且没有其他人基于这次提交继续工作。git commit --amend会把当前提交改写成全新提交旧提交从分支引用里消失服务端扫描时自然就看不到大文件了。这个快捷方法很容易被忽略但它真的能救急。4. 路线 B 实操用 Git LFS 接管大文件4.1 LFS 的原理把大文件换成指针如果大文件不是误提交而是需要长期维护的二进制资产比如 AI 模型权重、设计源文件、音频素材那就该认真考虑 Git LFS。LFSLarge File Storage的设计核心很简单Git 仓库里不存大文件本体只存一个几十字节的指针文件里面记录文件的哈希标识和原始大小真正的内容由 git-lfs 客户端拦截下来上传到独立的大文件存储区。推送时服务端扫描到的是小指针自然就绕过了单文件 100MB 限制。对使用者来说日常命令几乎不变还是git add、git commit、git push但仓库的实际体积会大幅下降clone 和 fetch 的速度也会明显改善。这也是 LFS 能在各种托管平台上成为标准方案的原因。4.2 安装初始化与跟踪规则第一步安装并初始化客户端git lfs install这条命令会写入全局 Git 配置注册 LFS 需要的 filter 驱动。第二步为需要托管的文件类型建立跟踪规则git lfs track *.zip *.psd model/weights.bingit lfs track的实际效果是把这些模式写入.gitattributes文件。这个文件必须提交到仓库里团队其他人 clone 之后才会自动获得同样的跟踪规则否则他们拉到的只会是光秃秃的指针而不是真实文件。接下来正常 add、commit 即可。提交时git-lfs 会把大文件内容写入本地的 LFS 缓存Git 索引里记下的只是指针。4.3 用 lfs migrate 重写历史前面反复强调过如果大文件已经存在于历史里只加.gitattributes和track规则是不够的因为旧提交里的大 blob 依然在。此时必须做历史迁移git lfs migrate import --includemodel/weights.bin --everything--include可以是具体路径也可以是通配符比如*.zip--everything表示处理所有分支和标签。迁移引擎会把匹配到的 blob 替换成 LFS 指针把真实内容转存到本地的 LFS 目录并同步更新.gitattributes。这一步本质上和路线 A 的历史重写一样只是“删除大对象”换成了“替换成小指针”。因此要再次提醒这个操作会改变提交哈希后续推送必须走强制推送流程。4.4 推送、验证与配额管理迁移完成之后接下来就是推送环节。这一推和普通提交不同需要把 LFS 对象一并传上去git push --force-with-lease origin main推送过程中git-lfs 会通过 pre-push 钩子先把真实大文件上传到平台侧的 LFS 存储区等 LFS 对象传完再更新 Git 引用。如果 LFS 对象上传失败Git 引用也不会更新推送会明确报错。验证是否成功两个命令很有用git lfs ls-files # 列出当前被 LFS 追踪的文件 git lfs ls-files --all # 列出历史里所有 LFS 文件如果指针记录都对应到了真实文件远端仓库也能看到 LFS 标识说明接管成功。最后提醒一点绝大多数托管平台对 LFS 有配额限制免费额度通常不大额度用完后推送会被拒绝。即便单文件绕过 100MB也要提前算好总账别把所有素材库一股脑全塞进去。4.5 团队协作里的 LFS 注意事项引入 LFS 等于给团队增加了新的协作约束每个成员都要在本地执行过一次git lfs install否则 clone 下来会得到一堆指针而不是真实文件。遇到这种情况成员只需要在仓库目录里执行git lfs pull就能补齐内容。另外LFS 文件在 clone 和 checkout 时默认会全量拉取仓库如果很大首次 clone 的时间和流量消耗会明显增加。有些平台支持选择性拉取或稀疏检出可以缓解这个问题但需要额外配置。这些细节最好在团队文档里写清楚避免解决方案上线第一天就有人踩坑。5. 高频问题与排查技巧实录5.1 删了文件、提交也改了为什么还是失败把这个高频问题单独拎出来你已经git rm并重新提交了push 依然报 100MB。几乎可以肯定大文件还残留在历史里或者存在于其他分支和标签上。先用 1.3 节那条扫描命令确认大文件路径然后检查它出现在哪些引用上git branch -a和git tag都要看。如果另一个分支里的旧提交引用着它而你的重写只处理了当前分支服务端扫描时照样能发现。统一做法是让所有引用都参与重写——路线 A 用 filter-repo 时默认覆盖所有 refs路线 B 用--everything推送时也要把--all和--tags一起带上别只推当前分支。5.2 filter-repo 跑完发现 remote 不见了这是 filter-repo 的故意设计不是 bug。它在完成历史重写后会移除 origin 远程目的就是阻止你不加思考地直接 force push 到远端。解决办法很简单git remote add origin 远端地址再推送。另外要注意filter-repo 默认要求在一个“干净克隆”里执行。如果你在平时的开发目录里直接跑可能会收到类似 Refusing to run in an unclean copy 的提示。遇到这种情况先别急着加--force硬闯重新克隆一份独立副本再处理更稳妥。5.3 LFS 迁移之后仓库里仍有大文件迁移之后 push 仍报错或者git lfs ls-files列表跟预期不符常见原因有两个一是--include的路径没写全漏掉了某些后缀或子目录二是通配符没生效因为路径模式是从仓库根目录匹配的。排查用git lfs migrate info --everything它会按文件类型汇总整个仓库历史里的大小分布一眼就能看出还有哪些大块头没被接管。确认遗漏后把 include 规则补全再跑一次 migrate。注意 migrate 支持多次运行但每次都会改动提交哈希最好一次性把规则写全免得反复折腾。5.4 强制推送之后队友的仓库乱套了历史重写之后所有旧提交哈希都失效了。队友原先的本地分支还基于旧提交下次 push 会被远端拒绝直接 fetch 的话也可能看到一片冲突。正确做法是先让队友把自己还未推送的改动用git format-patch或git stash备份然后重新 clone或者在确认本地没有未推送提交的前提下执行git fetch --all --prune git reset --hard origin/main。这个责任在发起重写的人身上。动手前先在群里同步约好窗口期确认没有同事在这个阶段提交再执行 force push。别小看这一步我见过因为历史重写没沟通整个团队花了一下午救数据的案例。5.5 提前拦截给仓库加一道大文件闸门与其等平台报错不如在本地把风险拦住。我最常用的是给仓库配一个 pre-commit 钩子暂存区里一旦出现超过阈值的文件就拒绝提交。示例脚本如下#!/bin/bash # 放在 .git/hooks/pre-commit并赋予执行权限 LIMIT$((100 * 1024 * 1024)) git diff --cached --name-only -z | while IFS read -r -d f; do [ -f $f ] || continue size$(stat -c %s $f 2/dev/null) if [ -n $size ] [ $size -gt $LIMIT ]; then echo pre-commit 拦截$f 为 $((size / 1024 / 1024)) MB超过 100MB 上限 echo 如确需版本管理请先执行 git lfs track 接管该文件 exit 1 fi doneLinux 上stat -c %s取文件字节数macOS 要换成stat -f %z脚本里注明即可。这种钩子只对新的提交生效不会改动已有历史配合团队文档能拦下大部分 100MB 报错。6. 最后我在实战里的几点体会处理这类问题多了之后我最大的体会是绝大多数 100MB 报错都不是蓄意破坏而是仓库里混进了一个“本来就不该被版本管理的东西”。模型权重、数据集、打包产物、IDE 缓存这些文件要么应该走 LFS要么应该留在对象存储里让脚本去拉取。提交前花十秒钟看一眼git status养成把生成物写进.gitignore的习惯比事后花一两个小时重写历史便宜得多。如果你已经站在报错现场别慌。先按第 2 节的三个问题确定路线再动命令。误提交、临时产物选路线 A需要长期维护的二进制资源选路线 B可再生的构建产物选路线 C。历史重写不是普通提交它会影响所有协作者动手前沟通动手后同步用--force-with-lease做最后一道保险。最后再补一个小技巧重写历史之前先执行git bundle create backup.bundle --all打一个全量备份。无论中间哪一步出了问题都能从这份包里随时还原。这是我踩过几次坑之后给自己立下的铁律希望你在实战中大概率用不上它。