推送代码时被仓库平台拦下来,报错说 blob 对象太大,这种经历但凡碰到一次就够让人头疼的。最近我就在 CNB 上遇到了这个经典问题:本地仓库里有个 309 MiB 的文件,推送到远端时直接被拒绝,提示“blob 对象大小 309 MiB 超过了单个文件大小限制 256 MiB”。这个报错本身不复杂,但它牵扯出来的问题却很典型:Git 仓库里的大文件到底该怎么管,历史提交里的大对象怎么清掉,以及以后怎么避免再踩同一个坑。
这篇文章会把这次踩坑的完整过程、排查思路、解决方案和避坑经验都梳理一遍,包括 Git 对象存储的基本原理、平台侧限制的由来、用 Git LFS 管理大文件的具体操作、以及用 git filter-repo 重写历史把大文件彻底“抹掉”的做法。无论你是和我一样被这个报错卡住,还是单纯想搞明白大文件在 Git 仓库里应该怎么处理,这篇都能给你一份可以直接拿来用的方案。
1. 这个报错到底在说什么:309 MiB 的 blob 是怎么来的
先把报错本身拆开看。CNB 提示“推送的 blob 对象大小 309 MiB 超过了单个文件大小限制 256 MiB”,这里面的关键词有三个:blob 对象、单文件大小限制、推送。
blob 是 Git 内部四种对象类型之一(另外三种是 tree、commit、tag),你可以把它理解成 Git 存储文件内容的最小单位。当你往 Git 里添加一个文件并提交时,Git 会把这个文件的内容压缩后存成一个 blob 对象。重点在于:这个 blob 对象的大小就是文件本身的大小,只要这个文件进入过 Git 的历史,哪怕后来你把它删了,这个 blob 对象也依然会在对象数据库里存活。所以这个报错的本质就是:你当前提交分支里存在一个超过 256 MiB 的文件,或者更隐蔽的情况是——你的提交历史里某个历史版本存在过这样一个大文件。
这里有一个新手特别容易误解的点:很多人以为只要把大文件删掉再提交一次就能解决问题,事实是并不行。因为 Git 的历史是不可变的,之前那个包含大文件的 commit 依然挂在历史链上,推送时服务器端会检查整个接收范围内的所有对象,任何一个超限的 blob 都会被拦下来。这也是为什么这类问题往往“删了还报错”、让人一头雾水。
从这个角度说,CNB 作为托管平台,它在服务端做这个限制是合理的。256 MiB 的单文件限制意味着服务端在接收、存储、传输这个对象时的成本是可接受的,同时也能防止有人把 Git 仓库当成网盘来用。类似 GitHub 的限制是 100 MiB(超过 50 MiB 就会警告),Gitee 是单文件 100 MiB,不同平台策略不同,但核心逻辑一样:保护服务端存储和带宽资源。
再往深一层想,这个报错还暴露了一个工程管理问题:仓库里为什么会混进一个 300 多 MiB 的文件?最常见的来源是这几类:
- 二进制产物,比如编译出来的安装包、APK、固件;
- 模型文件,比如深度学习的权重文件;
- 数据集、日志、数据库备份;
- 视频、音频或大体积的压缩包;
- 不小心把 node_modules、dist 这类目录的整体压缩包提交了进去。
我的情况属于第一种,一个 APK 安装包不小心被打包进了提交里,当时想着反正是内部仓库,先推上去再说。结果就是被 CNB 的 256 MiB 限制拦得死死的,连带着正常的小文件推送也被阻塞了。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 定位元凶:怎么找出仓库里的大文件
遇到这个报错之后,第一件事不是急着去改历史,而是先搞清楚到底是哪个文件超了限制。这里有两个层面要查:当前工作区/当前分支里的文件,以及整个提交历史里存在过的所有大文件。
2.1 先检查当前分支里有没有超限文件
最简单的命令是直接在仓库里扫一遍,看看当前目录下有哪些文件超过 256 MiB:
bash复制find . -type f -size +256M -not -path "./.git/*" -exec ls -lh {} \;
这个命令会列出所有大于 256 MiB 的文件。如果你运气好,发现当前工作区就有一个这样的文件,先把它从 Git 跟踪中移除:
bash复制git rm --cached <大文件名>
echo "大文件名" >> .gitignore
git commit -m "chore: 移除超限大文件并加入忽略列表"
做完这一步,当前分支的问题就解决了。但前面说过,历史里的大对象还在,所以这个时候推送大概率还是会被拦,只是报错提示可能不变。别急,继续往下查。
2.2 排查整个提交历史里的超大对象
如果你查了当前工作区没有超限文件,或者明明删了还是报同样的错,那问题一定藏在了历史提交里。
