Gitee码云大文件上传限制突破：从报错到解决的完整流程

1. 遇到Gitee大文件上传报错怎么办？

最近在团队协作开发时，突然遇到Gitee报错："remote: error: File: , exceeds 100.00 MB"。这个错误让我一头雾水，明明上周还能正常提交代码，怎么突然就不行了？经过一番排查才发现，原来是项目里不小心混入了一个120MB的设计稿源文件。相信不少开发者都遇到过类似问题，今天我就把完整的排查和解决过程分享给大家。

Gitee对免费用户的单个文件大小限制确实是100MB，这个限制对于代码文件来说完全够用，但如果项目中不小心混入了视频、设计稿、数据集等大文件，就会触发这个报错。更麻烦的是，即使你删除了这个大文件，由于Git的版本控制特性，这个文件仍然存在于历史记录中，导致后续提交依然会报错。下面我就从报错分析、问题定位到最终解决，一步步带你搞定这个烦人的问题。

2. 快速定位问题文件

2.1 理解报错信息

当看到"remote: error: File: , exceeds 100.00 MB"这个报错时，首先要明确几点：

1. 报错的是单个文件大小超过限制，不是整个仓库大小
2. 文件可能存在于当前提交，也可能隐藏在历史记录中
3. 文件名在报错信息中可能显示不全，需要进一步排查

2.2 使用Git命令查找大文件

在Linux/Mac环境下，可以直接使用这个命令查找大文件：

git rev-list --objects --all | grep "$(git verify-pack -v .git/objects/pack/*.idx | sort -k 3 -n | tail -5 | awk '{print$1}')"

但Windows用户会遇到麻烦，因为Windows默认的cmd/powershell不支持完整的grep和awk命令。这里推荐使用Cmder这个神器，它是一个Windows下的强大命令行工具，集成了Git和很多Linux常用命令。

安装Cmder非常简单：

1. 访问官网 https://cmder.net/ 下载完整版（包含Git）
2. 解压到任意目录（建议不要放在C盘根目录）
3. 双击cmder.exe即可使用

安装完成后，切换到你的项目目录，执行上述查找命令就能看到所有大文件了。我上次用这个方法，发现是一个不小心提交的PSD设计文件占用了150MB空间。

3. 彻底删除历史中的大文件

3.1 使用filter-branch清理历史记录

找到问题文件后，仅仅删除当前版本的文件是不够的，必须从Git历史中彻底清除。这里我们需要用到git filter-branch这个"重型武器"。

基本命令格式如下：

git filter-branch -f --prune-empty --index-filter "git rm -rf --cached --ignore-unmatch 文件路径" --tag-name-filter cat -- --all

注意几个关键点：

1. 必须使用双引号包裹rm命令，单引号会导致报错
2. 文件路径要使用相对路径，从项目根目录开始
3. 必须在项目根目录执行这个命令
4. --all参数表示处理所有分支

我上次执行时就踩了坑，因为文件路径写错了，导致命令运行了半小时却什么都没改。正确的文件路径应该是类似"assets/images/large_file.psd"这样的相对路径。

3.2 清理本地缓存

执行完filter-branch后，还需要运行以下命令清理本地缓存：

git gc --prune=now git reflog expire --expire=now --all git fsck --full --unreachable git repack -A -d git prune

这一系列命令的作用是：

1. gc：垃圾回收，清理松散对象
2. reflog：重置引用日志
3. fsck：检查仓库完整性
4. repack：重新打包对象
5. prune：删除不可达对象

4. 重新提交代码

4.1 常规提交方式

完成上述清理后，就可以重新提交代码了：

git add . git commit -m "移除大文件" git push origin master

不过要注意，由于我们改写了历史记录，如果其他人已经克隆了这个仓库，他们需要执行以下操作：

git fetch --all git reset --hard origin/master

4.2 强制推送的注意事项

在某些情况下，可能需要强制推送：

git push --force origin master

但强制推送要特别小心，尤其是多人协作的项目中，因为这会导致其他人的本地历史与远程不一致。建议强制推送前先通知团队成员。

5. 预防大文件问题的实用技巧

5.1 使用.gitignore文件

最好的解决方案是预防问题的发生。在项目根目录创建.gitignore文件，添加不需要版本控制的文件类型，例如：

*.psd *.ai *.mp4 *.zip *.dll

5.2 使用Git LFS管理大文件

如果确实需要版本控制大文件，可以使用Git LFS（Large File Storage）：

1. 安装Git LFS：

git lfs install

2. 跟踪大文件类型：

git lfs track "*.psd" git lfs track "*.mp4"

3. 像平常一样提交更改：

git add .gitattributes git add file.psd git commit -m "Add design file" git push origin master

5.3 使用预提交钩子检查文件大小

可以在.git/hooks/pre-commit中添加检查脚本，防止提交大文件：

#!/bin/sh hard_limit=$(git config hooks.filesizehardlimit || echo 100000000) soft_limit=$(git config hooks.filesizesoftlimit || echo 80000000) for file in $(git diff --cached --name-only); do size=$(git cat-file -s ":0:$file" 2>/dev/null || stat -c%s "$file") if [ "$size" -gt "$hard_limit" ]; then echo "错误: 文件 '$file' 超过大小限制 ($hard_limit bytes)" exit 1 fi if [ "$size" -gt "$soft_limit" ]; then echo "警告: 文件 '$file' 接近大小限制 ($size > $soft_limit bytes)" fi done

把这个脚本保存为pre-commit文件，并赋予执行权限，就能在提交时自动检查文件大小了。

6. 常见问题排查

6.1 filter-branch执行失败

如果filter-branch报错"fatal: bad revision 'rm'"，通常是因为：

1. 使用了单引号而不是双引号
2. 文件路径不正确
3. 不在项目根目录执行

6.2 推送被拒绝

如果推送时报错"[remote rejected] master -> master (pre-receive hook declined)"，可能是因为：

1. 仓库设置了大小限制
2. 虽然删除了大文件，但历史记录仍然过大
3. 需要联系仓库管理员调整限制

6.3 清理后仓库大小没变化

如果执行完所有清理步骤后，远程仓库大小没有变化，可能需要：

1. 在Gitee上删除原仓库
2. 重新创建一个同名仓库
3. 推送清理后的本地仓库

不过这会丢失所有issue和PR，所以只作为最后手段。

7. 替代方案：分卷压缩大文件

对于确实需要版本控制但又超过限制的文件，可以考虑分卷压缩：

# 压缩 zip -s 99m large_file.zip large_file.psd # 解压 zip -s 0 large_file.zip --out full.zip

每个分卷都会小于100MB，可以单独提交。不过这种方法会让文件管理变得复杂，建议只在特殊情况下使用。

经过这次折腾，我养成了几个好习惯：定期检查仓库大小、完善.gitignore配置、使用Git LFS管理资源文件。这些预防措施能节省大量排查问题的时间。如果你也遇到类似问题，不妨按照这个流程一步步排查，应该能顺利解决Gitee的大文件限制问题。