Git大文件推送失败问题及解决方案

问题

在日常开发中，我们经常会遇到这样的问题：

Remote: File [xxx.exe] size 188.156MB, exceeds quota 100MB
Remote: Please remove the file[s] from history and try again

这是因为 Gitee/GitHub 等平台对单个文件大小有限制（一般是 100MB）。一旦提交了超过限制的大文件，push 就会被拒绝。

本文以我遇到的一个 exe 安装包 被错误提交进 Git 仓库为例，分享一下完整的解决思路。

一、为什么不能直接删除文件？

很多同学第一反应是直接删除项目里的 exe 文件，然后再提交一次。
但是问题在于：

• 大文件已经存在于 Git 历史中
• 即使最新提交删除了它，push 时远程仍然会检测到它的历史，依然报错

所以必须 从历史中彻底移除 这个文件。

二、用 git filter-repo 删除大文件

git filter-repo 是官方推荐的替代工具，比 filter-branch 更快更简单。

1. 安装

pip install git-filter-repo

2. 在干净仓库中操作

⚠️ 注意：git filter-repo 会修改整个提交历史。为了安全，最好新克隆一份仓库来操作：

git clone https://gitee.com/xxx/your-repo.git clean-repo
cd clean-repo

3. 删除大文件

例如删除 YoloAndHalcon/MainPro/发布/屏蔽盖SetupV1.0.exe：

git filter-repo --path YoloAndHalcon/MainPro/发布/屏蔽盖SetupV1.0.exe --invert-paths

这会把该文件从整个历史中移除。

4. 强制推送

git push origin --force

完成后，大文件就不再存在于远程仓库了。

三、如何避免 exe 等大文件被跟踪？

很多时候，exe、zip、mp4、训练模型等大文件 根本不应该放在 Git 仓库里。

1. 使用 .gitignore

在项目根目录添加 .gitignore：

# 忽略编译生成的二进制文件
*.exe
*.dll
*.so
*.dylib

# 忽略压缩包
*.zip
*.rar
*.7z
*.tar
*.gz

# 忽略大数据文件
*.csv
*.json
*.xlsx
*.db

# 忽略图片和视频（按需开启）
*.mp4
*.avi
*.mov
*.jpg
*.png

# 忽略机器学习模型
*.pt
*.onnx
*.h5
*.ckpt
*.pb

提交后，这些文件就不会再被 Git 跟踪。

2. 如果必须保存大文件

如果确实需要（比如模型文件、视频数据），推荐两种方式：

• Git LFS（适合版本控制大文件，但 Gitee 免费版只有 1GB 限额）
• Release 附件 / 网盘 / OSS（不占用 Git 仓库空间，更加灵活）

四、总结

1. 遇到 push 报错提示大文件超 100MB，要用 git filter-repo 从历史中彻底删除。
2. 操作步骤：新克隆仓库 → 执行删除命令 → 强制推送。
3. 平时要提前配置好 .gitignore，避免 exe、zip、模型文件等被误提交。
4. 一句话经验：源代码放 Git，大文件放 Release/网盘，二者分开管理，省心省力。

到此这篇关于Git大文件推送失败问题及解决方案的文章就介绍到这了,更多相关Git大文件推送失败内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！