Git 大文件上传失败深度解析与终极解决方案_含 macOS_Windows 全流程20251014
🚀 Git 大文件上传失败深度解析与终极解决方案（含 macOS / Windows 全流程）
标签：Git / 大文件问题 / Gitee / macOS / Windows / 实战排查
🧭 一、前言：为什么删了大文件仍然 push 不上？
在日常开发中，我们常会遇到类似报错：
remote: File [xxxx] size 168.945MB, exceeds quota 100MB
remote: Please remove the file[s] from history and try again
To https://gitee.com/xxx/xxx.git! [remote rejected] master -> master (pre-receive hook declined)
很多人第一反应是：
“我不是已经把大文件删除了吗？为什么还是 push 不上？”
这篇文章就带你彻底搞懂：
- 为什么删除文件仍然无效；
- 如何在 macOS / Windows 下彻底清除 Git 历史中隐藏的大文件；
- 如何从根源防止此类问题再次发生。
📖 二、问题分析：Git 的“记忆”机制
✅ 1. Git 不是文件系统，而是快照系统
Git 的提交历史会永久保存每一次快照。
即便你在最新提交里删除了文件，旧的提交中仍然保存着它的完整副本。
因此，即使你删除了文件并重新提交，Git 仍然会把之前那个大文件打包上传，导致 push 被拒。
✅ 2. 大文件被检测的范围
远端（如 Gitee / GitHub）会检查整个 commit 历史的 blob 对象，只要有一个对象超过限制，就会拒收。
✅ 3. 删除文件只是“软删除”
git rm、rm + commit 只是让当前快照不包含该文件，但历史仍有记录。
要彻底清除，需要重写 Git 的历史（历史重写）。
💡 三、解决方案总览
| 系统 | 工具 | 推荐方式 | 备注 |
|---|---|---|---|
| macOS / Linux | git-filter-repo | ✅ 推荐 | 新一代官方工具，速度快、可靠 |
| Windows | BFG Repo-Cleaner | ✅ 推荐 | 图形友好、Java 版，无需 Homebrew |
🧰 四、macOS / Linux 解决方案：git-filter-repo
🧩 1. 安装工具
brew install git-filter-repo
🧩 2. 备份仓库
cd your_project_dir
git clone --mirror . ../repo_backup.mirror
这样即使操作失误，也能还原。
🧩 3. 删除指定大文件路径（推荐）
git filter-repo --force \--invert-paths \--path sysoper/jenkins-plugins.tar.gz
--invert-paths表示“移除指定路径”。
你也可以加多个--path来删除多个文件。
🧩 4. 删除指定 blob 哈希（如果不知道路径）
从 Gitee 报错可看到大文件哈希（例如 e0d7c57682b9fc...）：
echo e0d7c57682b9fc5841674545e3c4ecc5410f3ea8 > /tmp/big.txt
git filter-repo --force --strip-blobs-with-ids /tmp/big.txt
🧩 5. 清理历史并强推
git reflog expire --expire=now --all
git gc --prune=now --aggressivegit remote add origin https://gitee.com/yourname/yourrepo.git
git push origin --force --all
git push origin --force --tags
⚠️ 强推会覆盖远端历史。若远端有保护分支，请先取消保护。
🪟 五、Windows 解决方案：BFG Repo-Cleaner
下载地址：https://rtyley.github.io/bfg-repo-cleaner/
⚙️ 1. 准备工作
确保系统装有 Java：
java -version
如果没有，可安装 Adoptium Temurin JDK
⚙️ 2. 克隆一个镜像仓库
git clone --mirror https://gitee.com/yourname/yourrepo.git
cd yourrepo.git
⚙️ 3. 删除大文件（路径或大小）
例如删除所有大于 100MB 的文件：
java -jar bfg.jar --strip-blobs-bigger-than 100M
或仅删除特定路径：
java -jar bfg.jar --delete-files sysoper/jenkins-plugins.tar.gz
⚙️ 4. 清理并推送
git reflog expire --expire=now --all && git gc --prune=now --aggressive
git push --force
🔍 六、排查大文件的常用命令
1️⃣ 查看仓库中最大的文件
git verify-pack -v .git/objects/pack/*.idx \
| sort -k3 -n | tail -10 | awk '{print $1,$3}' \
| while read hash size; doecho "$size $hash $(git rev-list --objects --all | grep $hash | awk '{print $2}')"
done | sort -nr
2️⃣ 查看最近提交中包含的大文件
git log --pretty=format:"%h %s" --numstat | grep -E "[0-9]{6,}"
🚫 七、防御策略：从源头杜绝大文件进入 Git
在 .gitignore 中加入以下规则：
# 大文件与构建产物
*.zip
*.tar
*.tar.gz
*.7z
*.iso
*.img
*.mp4
*.exe# 临时与打包目录
sysoper/
dist/
build/
data/
backup/
🚨 习惯性加上
.gitignore是团队管理的第一道防线。
🚨 不要把插件包、docker 镜像、模型文件、日志打包进仓库。
🧩 八、最佳实践建议
| 场景 | 推荐做法 |
|---|---|
| Jenkins 插件包、Docker 构建包 | 存放在制品仓库（如 Nexus / OSS / COS） |
| 大模型、音频、视频样本 | 存放在对象存储（如 S3 / COS） |
| 本地临时备份 | 存放于 /tmp 或 .local/backup/，并在 .gitignore 忽略 |
| 团队协作 | 统一配置 .gitattributes 和 .gitignore，定期检查仓库大小 |
🧭 九、完整问题复盘（实战案例）
项目：enterprise-cicd-scripts
系统：macOS
远端：Gitee
1️⃣ 添加大文件 sysoper/jenkins-plugins.tar.gz (~169MB)
2️⃣ push 被拒：超过 100MB
3️⃣ 删除文件再提交，仍然 push 不上
4️⃣ 使用 git-filter-repo 删除历史中的该文件
5️⃣ 清理并强推，问题彻底解决
🧩 十、总结
| 要点 | 说明 |
|---|---|
| ❌ 删除文件 ≠ 删除历史 | Git 的“记忆”机制会保存所有快照 |
| ✅ 必须重写历史 | 使用 git-filter-repo 或 BFG |
| 🧹 清理后要强推 | git push --force --all |
| 💡 防范于未然 | .gitignore 永远是最好的保险 |
🏁 结语
这类大文件提交问题看似偶发，其实是团队开发中非常常见的隐患。
一旦仓库里混入了几十 MB 的二进制文件，后续每次克隆、打包、同步都会被放大。
理解 Git 的“历史不可变性”，掌握一套标准清理方法，就能在任何平台（macOS / Windows / Linux）轻松应对。
📚 附录：一键清理脚本（适用于 macOS / Linux）
#!/bin/bash
# clean_large_files.sh - 清理大文件历史并强推TARGET=${1:-100M}echo "🔍 查找大于 $TARGET 的历史文件..."
git verify-pack -v .git/objects/pack/*.idx \
| sort -k3 -n | awk -v limit=${TARGET%M} '{ if($3 > limit*1024*1024) print $1 }' \
| while read hash; doecho $hash >> /tmp/big_blobs.txt
doneif [ -s /tmp/big_blobs.txt ]; thenecho "🧹 删除大文件 blob..."git filter-repo --force --strip-blobs-with-ids /tmp/big_blobs.txtgit gc --prune=now --aggressiveecho "🚀 推送中..."git push origin --force --allgit push origin --force --tags
elseecho "✅ 没有超过 $TARGET 的历史大文件。"
fi