在使用 Git 向 GitHub 推送项目时，经常会遇到「大文件超标」的报错——GitHub 对普通仓库的单个文件大小默认限制为 100MB，若推送超过该大小的文件（如数据集、模型权重、大型压缩包），会直接被远程仓库拒绝。本文整理了从「问题定位」到「三种解决方案」的完整流程，适合作为开发笔记或博客分享，帮助更多人避坑。
一、问题现象：推送失败的典型日志
首先明确报错特征——推送过程中会先正常执行「枚举对象→压缩→写入」步骤，但最终会出现 remote rejected 提示，核心错误信息如下（截取关键片段）：
# 推送后期的错误日志
remote: error: File dataset1/cifar-10-python.tar.gz is 162.60 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: File vgg16_method1.pth is 527.81 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: File vgg16_method2.pth is 527.80 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.
error: failed to push some refs to 'https://github.com/GMQcoder/pytorch_test.git'
To https://github.com/GMQcoder/pytorch_test.git
! refs/heads/master:refs/heads/master [remote rejected] (pre-receive hook declined)
Done
关键信息：exceeds GitHub's file size limit of 100.00 MB，明确指出超标文件的路径和大小。
二、核心原因：GitHub 的文件大小限制
GitHub 为了保证仓库性能和存储效率，设置了以下限制（2024年最新规则）：
- 单个文件大小：默认100MB（超过会直接拒绝推送）；
- 仓库总大小：建议不超过1GB（无强制限制，但超过后克隆/拉取会变慢）；
- 大文件存储（LFS）限额：免费账户提供1GB存储空间+10GB月带宽（付费账户可扩容）。
若推送的文件（如深度学习模型 .pth、数据集 .tar.gz）超过100MB，必须通过特殊方式处理，否则无法推送。
三、三种解决方案：按需选择
根据「是否需要长期维护大文件」「文件是否公开可下载」等场景，提供三种解决方案，按推荐优先级排序。
方案一：官方推荐——用 Git LFS 管理大文件（首选）
Git LFS（Large File Storage，大文件存储）是 GitHub 官方提供的工具，原理是：将大文件的「引用（指针）」存入 Git 仓库，实际文件存储在 LFS 服务器，既不占用仓库体积，又能正常追踪大文件版本。
适合场景：需要长期在仓库中维护大文件（如自定义模型权重、私有数据集）。
步骤1：安装 Git LFS
不同系统的安装方式不同，确保安装后能在终端调用 git lfs 命令：
- Windows/macOS：直接下载安装包
官网地址：Git LFS 下载页，双击安装后重启终端。 - Linux（Ubuntu/Debian）：通过包管理器安装
sudo apt-get update && sudo apt-get install git-lfs - 验证安装：终端输入
git lfs --version，显示版本号即成功（如git-lfs/3.4.1 (GitHub; linux amd64; go 1.20.6)）。
步骤2：初始化 Git LFS（首次使用必做）
进入本地项目仓库目录，执行初始化命令，让 Git 识别 LFS 工具：
git lfs install
成功会提示：Git LFS initialized.（全局初始化一次即可，后续所有仓库通用）。
步骤3：追踪超标大文件
告诉 Git LFS 要管理哪些文件，支持「单个文件」或「按后缀匹配」：
# 1. 精准追踪报错日志中的3个大文件（推荐，避免误追踪）
git lfs track "dataset1/cifar-10-python.tar.gz"
git lfs track "vgg16_method1.pth"
git lfs track "vgg16_method2.pth"
# 2. 按后缀批量追踪（适合同类型大文件，如所有模型权重、数据集）
git lfs track "*.pth" # 追踪所有 .pth 模型文件
git lfs track "*.tar.gz" # 追踪所有 .tar.gz 压缩包
执行后会在项目根目录生成 /.gitattributes 文件，该文件记录了 LFS 追踪规则，必须提交到仓库（否则其他人克隆时无法识别大文件）。
步骤4：提交 LFS 配置与大文件
- 先提交
.gitattributes配置文件：git add .gitattributes git commit -m "添加 Git LFS 追踪规则" - 重新添加并提交大文件（若之前已执行过
git add，需先清除缓存）：# 清除之前误添加的大文件缓存（避免残留普通 Git 追踪记录） git rm --cached dataset1/cifar-10-python.tar.gz git rm --cached vgg16_method1.pth git rm --cached vgg16_method2.pth # 重新添加大文件（此时会被 LFS 接管，而非普通 Git） git add dataset1/cifar-10-python.tar.gz git add vgg16_method1.pth git add vgg16_method2.pth # 提交大文件 git commit -m "用 Git LFS 提交大文件：CIFAR-10 数据集 + VGG16 模型"
步骤5：推送至 GitHub
# 若分支是 main（而非 master），替换为 git push origin main
git push origin master
推送时会看到 LFS 专属日志（如 Uploading LFS objects: 100% (3/3)），表示大文件正在通过 LFS 上传，耐心等待即可。
验证 LFS 效果
推送成功后，在 GitHub 仓库页面查看大文件：
- 文件名旁会显示
LFS标识，点击文件会提示「This is a Git LFS object」； - 仓库总大小不会包含 LFS 文件体积（仅计算指针大小）。
方案二：临时方案——移除/清理历史中的大文件
若大文件「无需长期维护」（如本地临时生成的模型、可重新下载的公开数据集），可直接从 Git 中删除，避免占用仓库资源。
适合场景：大文件是临时文件，或可通过其他渠道获取。
场景A：大文件未提交到 Git 历史（仅执行过 git add）
- 清除缓存并删除本地文件（确保已备份，删除后本地文件会消失）：
# 清除 Git 缓存中的大文件 git rm --cached dataset1/cifar-10-python.tar.gz git rm --cached vgg16_method1.pth git rm --cached vgg16_method2.pth # 删除本地文件（可选，若需保留本地文件，跳过此步） rm -f dataset1/cifar-10-python.tar.gz rm -f vgg16_method1.pth rm -f vgg16_method2.pth - 提交删除操作并推送：
git commit -m "删除超标大文件，避免 GitHub 限制" git push origin master # 分支为 main 则替换为 main
场景B：大文件已提交到 Git 历史（需彻底清理）
若之前已将大文件提交到 Git 历史（即使后来删除，历史记录中仍有残留），需用 git-filter-repo 工具彻底清除历史中的大文件（谨慎操作：会修改仓库历史，多人协作需提前沟通）。
-
安装
git-filter-repo（比传统git filter-branch更快更安全）：- Ubuntu：
sudo apt-get install git-filter-repo - macOS：
brew install git-filter-repo - Windows：通过 Git 官网 安装最新 Git，自带
git-filter-repo。
- Ubuntu：
-
彻底删除历史中的大文件：
# 替换为你的大文件路径，每行一个文件 git filter-repo --path dataset1/cifar-10-python.tar.gz --invert-paths git filter-repo --path vgg16_method1.pth --invert-paths git filter-repo --path vgg16_method2.pth --invert-paths--path：指定要删除的文件路径；--invert-paths：表示「排除该文件」，即从所有历史提交中删除。
-
强制推送修改后的历史（仅自己使用的仓库推荐，多人协作需确保他人已同步）：
# --force-with-lease 比 --force 更安全，避免覆盖他人提交 git push origin master --force-with-lease
方案三：优雅方案——用外部存储链接替代大文件
若大文件是「公开可下载的」（如 CIFAR-10 数据集官网可获取、模型权重传至 Google Drive/百度网盘），可将文件从仓库中移除，在 README.md 中提供下载链接，让使用者自行下载。
适合场景：大文件是公开资源，无需存入仓库占用空间。
步骤1：删除本地大文件并提交
参考「方案二 场景A」，删除大文件并推送删除操作。
步骤2：在 README.md 中添加下载链接
在项目根目录的 README.md 中补充清晰的下载指引，示例如下：
## 📥 数据集与模型权重下载
由于文件大小超过 GitHub 100MB 限制，需手动下载并放置到指定路径：
### 1. CIFAR-10 数据集（162.60MB）
- 下载地址：[CIFAR-10 官网](https://www.cs.toronto.edu/~kriz/cifar.html)（点击「CIFAR-10 python version」下载）
- 解压路径：将 `cifar-10-python.tar.gz` 解压到 `./dataset1/` 目录下，最终路径为 `./dataset1/cifar-10-batches-py/`
### 2. VGG16 模型权重（527.81MB/个）
- Method 1 权重：[Google Drive 链接](https://drive.google.com/file/d/xxx/view?usp=sharing)
- Method 2 权重：[百度网盘链接](https://pan.baidu.com/s/xxx)（提取码：abc1）
- 放置路径：直接将 `.pth` 文件放在项目根目录下，与 `train.py` 同级。
### 📌 验证文件完整性
下载后可通过 MD5 校验文件是否损坏：
- cifar-10-python.tar.gz：MD5=xxx
- vgg16_method1.pth：MD5=xxx
- vgg16_method2.pth：MD5=xxx
步骤3：提交 README 并推送
git add README.md
git commit -m "更新 README：添加大文件下载链接"
git push origin master
四、关键注意事项
- Git LFS 限额问题：免费账户仅有1GB LFS 存储空间和10GB月带宽，若大文件总大小超过限额，需升级付费计划（如 GitHub Pro 账户提供10GB LFS 存储）。
- 多人协作提醒：若团队使用 Git LFS，其他成员克隆仓库后需执行
git lfs pull才能拉取完整大文件（直接git pull仅会拉取指针）。 - 避免误提交大文件：在项目根目录添加
.gitignore文件，提前排除不需要的大文件（如*.pth、dataset/），避免重复踩坑。 - 历史修改风险：使用
git-filter-repo清理历史时，若仓库已公开或多人协作，需提前告知团队成员，让所有人重新克隆仓库（避免本地历史与远程冲突）。
五、方案对比与选择建议
| 解决方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| Git LFS | 需长期维护大文件、需版本控制 | 官方支持、版本追踪、不占仓库体积 | 免费账户有存储/带宽限额 |
| 移除/清理大文件 | 大文件是临时文件、无需版本控制 | 操作简单、不依赖外部工具 | 无法再追踪大文件版本 |
| 外部存储链接 | 大文件是公开资源、可通过其他渠道下载 | 不占用仓库任何资源 | 使用者需手动下载，体验稍差 |
根据实际需求选择：
- 长期维护 → 选 Git LFS；
- 临时文件 → 选移除/清理；
- 公开资源 → 选外部存储链接。
通过以上流程，可彻底解决 GitHub 大文件推送失败的问题，同时保证仓库的整洁性和可维护性。建议根据项目场景固定一种方案，避免后续反复修改。
扫一扫
882
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
