清理 Git 代码库大文件历史记录

在日常开发中，我们可能会不小心将一些大文件（如二进制文件、大型资源文件等）提交到 Git 仓库中。即使后来删除了这些文件，它们依然存在于 Git 的历史记录中，导致 .git 目录变得非常庞大，严重影响 git clone 和 git pull 的速度。

本文将介绍如何分析 Git 仓库的占用情况，并使用工具清理历史记录中的大文件。

问题分析

Git 仓库体积过大的主要原因通常是 .git/objects/pack/*.pack 文件过大。Git 将文件历史记录存储在本地的 "database" 中，如果历史记录中包含了大量的二进制文件变动，pack 文件就会迅速膨胀。

$!info\] Git Internals - Packfiles Git 使用 packfile 来优化存储。详情可参考：[Git - Internals - Packfiles](https://link.juejin.cn?target=https%3A%2F%2Fgit-scm.com%2Fbook%2Fen%2Fv2%2FGit-Internals-Packfiles "https://git-scm.com/book/en/v2/Git-Internals-Packfiles")$

第一步：找出大文件

在清理之前，我们需要先找出是哪些文件占用了大量空间。

1. 查看仓库大小

使用 git count-objects 命令可以查看仓库的打包对象数量和磁盘占用情况：

bash 复制代码

# -v: verbose, 显示详细信息
# -H: human-readable, 以人类可读的格式显示大小
git count-objects -v -H

2. 查找 Packfile 中最大的对象

我们可以通过 git verify-pack 命令查看 packfile 中的对象详情，并按大小排序找出最大的几个 blob 对象：

bash 复制代码

# 查看 .git/objects/pack/ 下的 .idx 文件
# sort -rn -k 3: 按第3列（size）倒序排列
# head -10: 取前10个
git verify-pack -v .git/objects/pack/*.idx | sort -rn -k 3 | head -10

输出结果格式如下：

text 复制代码

# SHA-1 (Blob ID) | type | size | size-in-packfile | offset-in-packfile
9704d6e7c732b07418ffe2c0dd2c2030d0cd5a2e blob   2621847 2622645 235218
2bdb752d86091c343f2f4d3af88f038f6b4c2846 blob   2212925 868876 2918139
...

3. 定位具体文件路径

拿到 Blob ID 后，我们需要知道它对应的是哪个文件。使用 git rev-list 配合 grep 可以查找对应的文件名：

bash 复制代码

# 替换 <blob id> 为上面查到的 SHA-1
git rev-list --objects --all | grep 2bdb752d86091c343f2f4d3af88f038f6b4c2846

输出示例：

text 复制代码

2bdb752d86091c343f2f4d3af88f038f6b4c2846 .yarn/cache/playwright-core-npm-1.55.0-1c6d3fab0f-843376a8e2.zip

这样我们就找到了罪魁祸首，例如上面的 yarn/cache/playwright-core-npm-1.55.0-1c6d3fab0f-843376a8e2.zip。

第二步：分析问题

通过上面的步骤，我们发现 .yarn/cache/ 目录下的 zip 文件占用了大量空间。

原因分析 ：在使用 Yarn 2+ (Berry) 版本时，默认会将依赖以 zip 形式存储。如果项目没有正确配置 .gitignore，或者开发者误操作，就容易将 .yarn/cache 目录提交到 Git 仓库中。这些二进制缓存文件不仅体积大，而且变动频繁，是导致 Git 仓库膨胀的常见原因。

Yarn 2+ 的 .gitignore 最佳实践：

根据 Yarn 官方文档，对于大多数非 Zero-Installs 的项目，我们应该忽略以下目录：

gitignore 复制代码

# Yarn 2+
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

# 关键：忽略缓存目录
.yarn/cache

# 忽略构建状态和安装状态
.yarn/build-state.yml
.yarn/install-state.gz

# PnP 相关
.pnp.*

既然找到了问题根源是误提交了 .yarn/cache，接下来的目标就是将其从历史记录中彻底清除。

第三步：清理大文件

找到大文件后，我们需要将其从所有历史记录中彻底移除。这里推荐使用 BFG Repo-Cleaner ，它比原生的 git filter-branch 更快、更简单。

使用 BFG Repo-Cleaner

$!info\] BFG Repo-Cleaner BFG 是一个用 Scala 编写的工具，专门用于快速清理 Git 仓库中的大文件或隐私信息。官网：[rtyley.github.io/bfg-repo-cl...](https://link.juejin.cn?target=https%3A%2F%2Frtyley.github.io%2Fbfg-repo-cleaner%2F "https://rtyley.github.io/bfg-repo-cleaner/")$

1. 下载并运行

BFG 提供了一个 .jar 包，需要安装 Java 环境运行。

bash 复制代码

# 下载 bfg-1.14.0.jar 后，在仓库目录的上一级运行
# my-repo 为你的仓库目录名称

# 方式一：移除超过指定大小的文件 (例如 1M)
java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 1M my-repo

# 方式二：移除指定名称的文件 (支持 glob 模式)
java -jar bfg-1.14.0.jar --delete-files '*.{zip,jar,exe}' my-repo

# 方式三：移除指定文件夹
java -jar bfg-1.14.0.jar --delete-folders '.svn' my-repo

常用参数说明：

-b, --strip-blobs-bigger-than <size>: 移除超过指定大小的 blob。
-B, --strip-biggest-blobs NUM: 移除最大的前 NUM 个 blob。
-D, --delete-files <glob>: 按文件名移除文件。
--delete-folders <glob>: 按文件夹名移除文件夹。
--no-blob-protection: 允许修改最新提交（默认情况下 BFG 会保护最新的一次 commit 不被修改，以防误删）。

这里我们使用命令删除 .yarn/cache 目录下的所有文件：

bash 复制代码

java -jar bfg-1.14.0.jar --delete-folders '.yarn/cache' my-repo

2. 物理删除与垃圾回收

BFG 只是更新了 Git 的引用（refs）和历史记录，并没有真正物理删除磁盘上的对象。我们需要运行 Git 的垃圾回收命令来彻底释放空间：

bash 复制代码

# 强制过期所有 reflog，并执行垃圾回收
git reflog expire --expire=now --all && git gc --prune=now --aggressive

执行完上述步骤后，再次检查仓库大小，应该会发现体积明显减小。最后，需要强制推送到远程仓库：

bash 复制代码

git push origin --force --all

$!warning\] 警告这是一个破坏性操作，会重写 Git 历史。在执行之前，请务必**备份**你的仓库！此外，强制推送后，其他协作者需要重新 clone 仓库或进行 rebase 操作。$

清理 Git 代码库大文件历史记录