git仓库瘦身清理大文件的方法【实战】

别碰 git filter-branch，它易出错、极慢、留坑；优先用 git-filter-repo（官方推荐、功能全面）或 BFG Repo-Cleaner（Ja va 环境友好、命令直白）。

先说结论：如果你想让Git仓库成功“瘦身”，有件事必须优先明确——远离 git filter-branch。这个老牌工具虽然名气大，但实际用起来坑不少：历史重写容易出错、速度慢得让人心焦，处理完还可能留下各种“后遗症”。相比之下，git-filter-repo 和 BFG Repo-Cleaner 才是更现代、更可靠的选择。前者是官方推荐的新秀，功能全面；后者对Ja va环境更友好，命令也更直白。

怎么快速定位历史里真正占空间的大文件

很多人的第一个误区，是只盯着当前工作区里有没有大文件。其实，Git仓库臃肿的罪魁祸首，往往是那些“已经被删除，却依然活在历史记录里”的大文件。所以，必须从Git对象层进行深度扫描。

• 这条命令能帮你揪出真正的“元凶”：git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sed -n 's/^blob //p' | sort -n -k 2 | tail -10 | cut -c 1-12,41- | $(command -v gnumfmt || echo numfmt) --field=2 --to=iec-i --suffix=B。它的厉害之处在于，输出的是Blob对象的原始大小（包含路径），而非压缩后的尺寸，结果最为准确。
• 扫描结果出来后，重点关注那些带有 .so、.a、.dll、.zip、.pdf 后缀的行。这些文件大概率就是你要找的“僵尸脂肪”。尤其是 .so 这类编译产物，往往在每次构建时都会生成新的哈希，被多次提交进历史，体积叠加起来非常快。
• 千万别只看 du -sh .git 显示的表面数字。这个大小包含了打包文件、引用日志和未清理的悬空对象。更科学的做法是结合 git count-objects -vH 命令，观察 size-pack（打包后大小）和 count（对象数量）的比值。如果松散对象的数量远高于打包对象，那就说明仓库里的“垃圾”还没清理干净。

用 git-filter-repo 清理指定大文件或目录

目前来看，git-filter-repo 是最稳妥的清理方案。不过，必须警惕的是，它会重写所有提交的哈希值。这意味着，操作前务必备份整个项目文件夹（注意，不是简单的 git clone）。

• 安装：通过 pip install git-filter-repo 安装（需要Python 3.8+），macOS用户也可以直接使用 brew install git-filter-repo。
• 重要前提：进入项目根目录后，不要在已经配置了远程origin的仓库里直接运行命令。git-filter-repo 默认会拒绝在非裸仓库上操作。虽然可以加 --force 参数强制运行，但更推荐的做法是，先用 git clone --mirror 克隆出一个裸仓库，再对这个裸仓库进行处理。
• 删除单个文件：git-filter-repo --path path/to/bigfile.so --invert-paths --force。这里的 --invert-paths 参数是关键，它的作用是“保留除指定路径外的所有内容”，也就是执行剔除操作。
• 删除整个目录：git-filter-repo --path docs/ --invert-paths --force。这比逐个删除目录下的文件要高效得多。
• 按大小批量删除：git-filter-repo --strip-blobs-bigger-than 50M --force。这个命令非常适合那些不清楚具体文件路径，但能确定历史中存在大量超大文件的场景。

用 BFG Repo-Cleaner 快速删 >1MB 的 .so 或其他二进制文件

如果你的机器上已经安装了Ja va环境，那么 BFG Repo-Cleaner 会是一个更快捷的选择。它对Windows用户或在CI环境中编写脚本尤其友好。

• 下载：curl -O https://repo1.ma ven.org/ma ven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
• 必须使用镜像克隆：先用 git clone --mirror https://your/repo.git 克隆仓库，你会得到一个 repo.git 目录（没有工作区）。
• 删除所有 .so 文件：ja va -jar bfg-1.14.0.jar --delete-files "*.so" repo.git
• 删除所有大于1MB的Blob对象：ja va -jar bfg-1.14.0.jar --strip-blobs-bigger-than 1M repo.git
• 关键后续操作：清理完成后，必须进入 repo.git 目录，执行 git reflog expire --expire=now --all && git gc --prune=now --aggressive。这一步是释放磁盘空间的核心，如果漏掉，清理效果将大打折扣。

清理完推送到远程前最关键的三件事

很多人在这里栽了跟头：本地清理明明成功了，一推送到远程就报错，或者同事怎么也拉取不下来新代码。问题几乎都出在下面这几个环节：

• git-filter-repo 会自动删除本地的remote配置。所以，清理后你需要手动加回去：git remote add origin https://your/repo.git。
• 强制推送前，先确认远程分支的名称（例如原来是 master）。接着，重命名你的本地分支以匹配（例如 git branch -M main）。然后，分别执行 git push --force --all origin 和 git push --force --tags origin 来推送所有分支和标签。
• 所有协作者必须重新克隆仓库，而不能使用 git pull。因为历史已经被重写，旧的提交哈希全部失效了。记得提醒他们，在 git clone 新仓库后，运行 git log --oneline | head -5 检查前几条提交的哈希值是否与你推送的一致。
• 如果项目使用了 Git LFS，清理后记得重新执行 git lfs track 来指定跟踪规则，并 git add .gitattributes。否则，LFS规则不会在新的历史记录中生效。

最后，还有一个最容易被忽略的点：清理工具只修改了提交历史，并不会自动删除你本地工作区中残留的那些大文件。在执行完所有步骤后，务必手动检查并 rm -rfbuild/、dist/、.so 等文件。更重要的是，立刻把它们添加到 .gitignore 文件中。否则，下一次提交时，它们很可能又会悄无声息地溜回仓库，让之前的清理工作前功尽弃。