复盘：Git 提交大文件导致推送失败及解决过程

🌳多平台技术论坛专家博主，全网11W+粉丝

✈️公众号 | 乡下小哥编程 。回复 Java全套视频教程 或 前端全套视频教程 即可获取 300G+ 教程资料及项目实战案例

⭐职场开发经验干货分享、开源项目源码分享

一、事件背景

• 项目中误将大文件（如 *.jar、*.zip 等）直接添加到了 Git 仓库中。

• 其中 Z-MicroMall/Doc/软件/sentinel-dashboard-1.8.8.jar 和 Z-MicroMall/Doc/软件/nacos-server-2.2.2.zip 等文件超过 GitHub 单文件 100MB 限制。

• 多次提交（commit）后，尝试将代码推送（push）到 GitHub 远程仓库时，推送被拒绝，提示文件大小超过限制。

二、问题表现

• git push 失败，报错类似：

  remote: error: File ... is 142.01 MB; this exceeds GitHub's file size limit of 100.00 MB remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.

• 远程仓库拒绝接收推送，影响正常开发。

三、根因分析

• Git 版本控制机制会保留所有历史提交的快照，即使后来删除文件，历史中仍然存在这些大文件。

• GitHub 对单个文件限制最大 100MB，违反该限制时远程会拒绝接收。

四、解决方案步骤

1. 从 Git 历史中彻底删除大文件

• 使用官方推荐的 git-filter-repo 工具，替代过时且易出错的 git filter-branch。

• 该工具能重写所有提交历史，彻底清除指定文件。

git filter-repo --force --path "软件/sentinel-dashboard-1.8.8.jar" --invert-paths git filter-repo --force --path "Z-MicroMall/Doc/软件/nacos-server-2.2.2.zip" --invert-paths

注意：使用 --force 参数绕过工具默认的“只能在fresh clone上操作”限制。

2. 清理 Git 垃圾和旧引用

rd /s /q .git\refs\original # Windows 下删除原始引用 git reflog expire --expire=now --all git gc --prune=now --aggressive

3. 恢复远程仓库配置

• git-filter-repo 操作时会移除远程配置，需要重新添加：

git remote add origin https://github.com/zhengyuzh/Z-MicroMall.git

4. 强制推送清理后的主分支

git push origin main --force

如果主分支叫 master，替换为 master。

五、后续建议

• 不要在 Git 仓库直接提交大文件，使用 Git Large File Storage (Git LFS) 管理大文件。

• 养成良好习惯，避免大文件进入版本历史。

• 定期检查仓库是否存在大文件，防患于未然。

总结