当前位置：首页 > news >正文

遇到 Git 提示大文件无法上传确实让人头疼

news 2025/9/6 8:33:04

遇到 Git 提示大文件无法上传确实让人头疼，但别担心，我们可以一步步来解决。为了让你更清晰地了解整个流程，我先用一个表格来概括主要步骤：

步骤	核心操作	关键命令/工具示例 (用于删除历史中的大文件)
1. 定位大文件	使用 Git 命令或工具找出仓库中的大文件	`git rev-list --objects --all \| grep "$(git verify-pack -v .git/objects/pack/*.idx \| sort -k 3 -n \| tail -5 \| awk '{print$1}')"`
2. 删除大文件	从所有历史记录中彻底删除找到的大文件	`git filter-repo --path <文件路径> --invert-paths`
		或 `BFG` 工具
3. 清理与推送	执行垃圾回收并强制推送到远程仓库	`git gc --aggressive --prune=all` , `git push --force`
4. 预防再次发生	使用 `.gitignore` 和 Git LFS 避免类似问题	`git lfs track "*.psd"`

接下来，我们详细看看每一步的具体操作。

📍 第一步：定位问题大文件

首先需要找出到底是哪个（些）文件体积过大。Gitee 的错误信息有时会直接给出文件名，如果没有，你可以通过以下命令来查找：

查看体积最大的几个文件：这个命令会列出仓库中体积最大的5个文件（你可以修改 tail -5 中的数字来查看更多）：
```
git rev-list --objects --all | grep "$(git verify-pack -v .git/objects/pack/*.idx | sort -k 3 -n | tail -5 | awk '{print$1}')"
```
使用图形化工具（可选）：如果你更喜欢图形界面，一些 Git 客户端（如 GitKraken、SourceTree）或者 Git LFS 的相关命令（git lfs ls-files）也能帮助你直观地查看大文件。

🗑️ 第二步：从历史中彻底删除大文件

找到大文件后，就需要将它从 Git 的历史记录中彻底移除。请注意，以下操作会重写 Git 历史，这意味着会改变提交的哈希值。如果仓库是多人协作，必须提前通知所有协作者，让他们在你强制推送后重新克隆仓库。

这里推荐使用 git filter-repo，它是一个更现代、更高效且更安全的工具，可以替代老旧的 git filter-branch。

安装 git-filter-repo：
- Ubuntu/Debian: sudo apt install git-filter-repo
- macOS: brew install git-filter-repo
- 也可以通过 Pip 安装: pip install git-filter-repo

使用 git-filter-repo 删除文件（以删除 src/assets/大文件/mtbg.gif 为例）：

# 确保你在仓库的根目录下
# --path 指定要删除的文件路径
# --invert-paths 意味着排除这些路径，即删除它们
git filter-repo --path src/assets/大文件/mtbg.gif --invert-paths --force

这条命令会遍历所有提交，并将指定的文件从历史中彻底剔除。

替代方案：使用 BFG Repo-Cleaner
BFG 是一个专为清理 Git 仓库中大文件而设计的工具，比 filter-branch 更快速简单。

# 安装 BFG 需要 Java 环境
# 下载 BFG jar 包（例如 wget 方式）
wget http://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
# 运行 BFG 删除特定文件
java -jar bfg-1.14.0.jar --delete-files 'mtbg.gif'

🧹 第三步：清理本地仓库并强制推送

彻底删除大文件后，本地仓库还需要进行一些清理操作，然后再推送到远程。

执行垃圾回收 (GC)：这个命令会清理不必要的文件并优化本地仓库。
```
git gc --aggressive --prune=all
```
之后你可以用 git count-objects -vH 查看优化后的仓库大小，应该会显著减小。
强制推送到远程仓库：因为重写了历史，必须使用 --force 选项来推送。
```
# 强制推送所有分支
git push origin --force --all
# 强制推送所有标签
git push origin --force --tags
```
再次强调：强制推送前务必确保团队其他成员知晓！

🛡️ 第四步：预防问题再次发生

为了避免以后再次遇到同样的问题，最好采取一些预防措施：

善用 .gitignore 文件：在仓库根目录创建或编辑 .gitignore 文件，忽略那些不需要版本控制的文件，如编译产物、依赖包、日志文件、系统文件等。例如：
```
# 忽略 .zip 压缩包
*.zip
# 忽略 node_modules 目录
node_modules/
# 忽略 .log 日志文件
*.log
```
记得将 .gitignore 文件也提交到 Git 中。
使用 Git LFS 管理必需的大文件：如果你的项目中确实需要版本控制一些大型文件（如图片、视频、模型文件等），Git Large File Storage (LFS) 是一个更好的选择。它会将大文件存储在单独的地方，而在 Git 仓库中只保留指针，从而避免仓库体积过快增长。
```
# 安装 Git LFS
git lfs install
# 跟踪特定类型的文件（例如跟踪所有 .psd 文件）
git lfs track "*.psd"
# 确保 .gitattributes 文件被提交（此文件保存 LFS 跟踪规则）
git add .gitattributes
git commit -m "开始使用 Git LFS 跟踪 .psd 文件"
```

⚠️ 操作前的重要提醒

在进行上述操作，尤其是重写历史（git filter-repo、BFG）和强制推送（git push --force）前，请务必注意：

备份你的仓库：最简单的方法就是直接复制整个仓库文件夹。
通知协作者：重写历史后，其他所有开发者必须使用 git clone 重新克隆仓库，或者使用 git fetch origin && git reset --hard origin/master 等命令将其本地分支重置到新的历史记录上。否则，他们的提交极有可能引起混乱。