不妧说实话，第一次被 GitHub 拒掉提交时，我还以为是自己操作出了问题。
项目里放了一个训练好的模型权重文件，git add 之后 git push，结果远端直接甩回来一行红字：
text复制remote: error: File model.pth is 312.42 MB; this exceeds GitHub's file size limit of 100 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage
紧接着我看了下本地仓库状态，文件已经在本地提交了，但远端一个字节都没收。这就是 GitHub 对大文件上传最经典的拦截方式：不是等你传完再告诉你，而是在推送阶段就把整个传输中止掉。
这不是个例。模型文件、设计稿、视频素材、数据集、安装包，凡是体积超过 100MB 的二进制文件，放进代码仓库的那一刻起，就注定会撞上这道限制。这篇内容就是一次完整的大文件上传失败解决记录，我会把 GitHub 的文件限制规则、Git LFS 的原理和操作、历史仓库迁移、配额报错，以及不走 LFS 的替代方案全部过一遍。适合被"Large files detected"卡住的人，也适合想在团队里建立一套大文件管理规范的人参考。
1. GitHub文件限制规则与"上传失败"的真实成因
1.1 官方限制并非只有一个100MB
很多人以为 GitHub 只有"单文件超过 100MB 不能提交"这一条规则，实际比这复杂一点。
GitHub 对仓库文件的限制分几个层级：
| 限制对象 | 限制数值 | 触发表现 |
|---|---|---|
| 网页端上传文件 | 单文件 25MB | 页面直接报错 |
| 普通 git push 单文件 | 超过 50MB 警告 | 推送时会显示 warning，但可能仍然成功 |
| 普通 git push 单文件 | 超过 100MB 拒绝 | 远端返回 GH001 错误，push 中断 |
| Git LFS 管理的文件 | 免费额度 1GB 存储 + 1GB 带宽/月 | 超出后返回 data quota 错误 |
| Release 附件 | 单文件 2GB | 超过则无法上传 |
也就是说，50MB 时 GitHub 会提醒你"这文件有点大了"，100MB 时直接拒绝，而 2GB 是另一套通道（Release）的上限。如果你在网上看到有人说"我 push 了一个 500MB 的文件也没事儿"，要么他用了 LFS，要么他走的是 Release，要么他那个仓库根本不是 GitHub 托管的。
另外注意一个容易混淆的点：GitHub 的 100MB 限制针对的是普通代码仓库的 git push，而不是 Release 附件，也不是 LFS 对象。后两者有另一套体积规则。很多人上来就以为是"GitHub 不能传大文件"，其实准确说法是"GitHub 不能通过普通 git push 传超过 100MB 的文件"。
1.2 失败的几种典型形态
我在各个项目里实际遇到的大文件上传失败，表现形态并不完全一样，至少有这么几种：
形态一：push 直接被拒
这是最典型的一种，报错长这样：
text复制remote: error: File assets/video/demo.mp4 is 325.00 MB; this exceeds GitHub's file size limit of 100 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage
这种情况下，本地 commit 是成功的，但远端分支收不到任何内容。此时 git log 里已经有那个提交了，但 git push 永远失败。
形态二：push 卡在传输阶段后超时
文件没有超过 100MB，但总量很大，比如几千个小文件加起来几个 GB。push 时进度条卡在某个位置，然后报 RPC failed; HTTP 500 curl 22 The requested URL returned error 或者 fatal: the remote end hung up unexpectedly。这类问题不是文件大小限制，而是传输中断或 HTTP buffer 不够，后面我会专门讲。
形态三：LFS 配额超限
如果你已经用 LFS 管理大文件，但仓库的 LFS 存储或带宽超出了免费额度，会报：
text复制batch response: this repository is over its data quota
这个报错非常容易让人误以为是网络问题，实际上是配额问题。
形态四：GUI 工具"假失败"
有些图形化 Git 客户端在 push 大文件时，由于没有把远端错误信息完整展示出来，只显示"failed to push"，导致你搞不清是文件超限还是网络故障。我第一次遇到时也排查了很久，最后还是在命令行里重新 push 才看到 GH001 的具体报错。
1.3 先判断"文件超限"还是"传输故障"
我不建议一上来就装 LFS。先花一分钟定位问题类型，能省很多事。
判断方法很简单：在命令行执行 git push，看报错类型。如果返回的是 this exceeds GitHub's file size limit，那就是文件超限，直接走 LFS 方案。如果返回的是 RPC failed、Operation timed out、Connection reset by peer 这类网络层错误，那说明传输链路有问题，大文件本身可能没超限，需要从传输层面解决。
还有一种特殊情况：本地仓库曾经提交过大文件，后来删掉了，但 Git 历史里还留着那个大文件对象。这种情况下 push 一样会被拒，因为你推送的不只是当前版本，而是整个提交历史。这类问题要在 git push 时看报错里提示的 File xxx is xxx MB，如果那个文件是历史遗留，单纯删除当前文件是没用的，必须处理历史。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。