这个报错估计折腾过不少刚接触 GitHub 的朋友——你辛辛苦苦把一个模型权重文件、数据集压缩包或者安装镜像拖进仓库结果 push 的时候终端直接甩出一句remote: error: File model.pth is 132.7 MB; this exceeds GitHubs file size limit of 100.0 MB remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.然后整个提交被拒仓库状态卡在中间重试好几次都是同一个结果。这篇文章就是来解决这个问题的我会把 GitHub 对上传大文件的限制规则讲清楚再把 Git LFS、Release、拆分文件、对象存储这几条正经路线的实操步骤和踩坑经验完整写出来最后补上上传中断、网络波动这些高频问题的处理方法。适合刚把 GitHub 当网盘用的新手也适合团队协作时被大文件搞崩仓库的老手。1. GitHub的100MB限制到底是什么先搞清楚规则再动手很多人一看到 100MB 这个数字就以为是仓库上限其实规则比这复杂一点而且不同的上传入口限制完全不一样。先把这个底层逻辑理顺后面选方案才不会被报错带着走。1.1 网页上传、命令行push与Release附件是三套规则GitHub 同一个项目里网页端上传、git push、Release 附件走的是三套完全不同的限制逻辑。很多人的第一个误区就在这里——在网页上拖一个 80MB 的文件成功了就以为命令行 push 也没问题结果被打了个措手不及。网页端上传的文件官方限制是单文件不能超过 25MB。这已经被卡得很死超过这个大小浏览器直接弹红字根本不给继续的机会。这个入口适合传配置文件、小图片、文档之类的零碎内容完全不适合传任何像样的程序包或者数据集。命令行 git push 的限制才是大家常说的 100MB。理论上单个文件超过 50MB 时 Git 就开始警告但真正硬性拒绝是文件超过 100MB。这里的 100MB 是指单个 blob 对象的大小不是仓库总大小所以哪怕你一个仓库里 200 个文件每个 99MBgit push 也能过只是过程会非常酸爽。Release 附件是一套独立体系单个附件最大允许 2GB而且不占用 git 仓库的对象存储。这个限制比 git push 宽得多非常适合发布二进制产物、安装包、模型权重这些根本没必要进版本历史的大块头。1.2 50MB警告、100MB硬限制与100GB仓库上限Git 的警告机制是这样的当你准备 push 的文件超过 50MB本地 git 会先给你一个 warning意思是这个文件有点大了建议你用 LFS。这个警告不会阻止提交但已经是一个明确的信号——继续往这个方向走马上就会撞墙。超过 100MB 就是硬性拒绝错误码 GH001GitHub 服务器直接在 pre-receive 钩子阶段就把提交弹回来你的对象根本进不了远程仓库。这个机制是同步阻塞的也就是说你 push 到 GitHub 时远端会在接收对象之前先检查所有 blob 的大小超标的直接整个拒绝不存在先传上去再说的情况。仓库总大小方面GitHub 官方给出的是建议不超过 1GB硬上限 100GB。注意这个 1GB 是推荐不是强制但是当仓库膨胀到这个量级clone 和 pull 的体验会变得极其痛苦因为每次操作都要把所有历史对象拉一遍。我见过一个团队把模型权重直接提交进 git 仓库三个月后仓库到了 8GB新同事 clone 一次要半小时CI 拉代码直接超时。这种仓库从健康度角度讲已经算废了一半。1.3 还有一个经常被忽略的历史包袱这里要特别提醒一个隐蔽的坑即使你现在把大文件从工作目录删掉了只要它停留在 git 历史里它依然占用仓库体积而且依然可能导致 push 失败。原因在于 git 的对象模型——每次 commit 保存的是完整快照的引用大文件一旦进入某个历史提交后续所有 clone 该仓库的人都需要下载这个对象。GitHub 检查的是仓库里所有历史对象不是只看最新提交。所以很多人遇到的情况是删掉了大文件重新 commitpush 还是失败或者仓库体积没有变小。这就是为什么那些大文件必须做历史清理后面第四章会专门讲。2. 大文件方案选型别一上来就无脑上LFS东西会报错的时候很多人第一反应是那我用 Git LFS 不就行了。LFS 确实是解决 100MB 限制的正规方案但不一定是最优解尤其对免费账户来说LFS 的配额很紧用错了地方反而会给自己挖更大的坑。先做一轮选型对比再决定具体走哪条路。2.1 四条路线的对比我把实际项目中见过的主流路线整理成一个表方便大家对照自己场景选方案单文件上限是否进版本历史免费额度典型场景Git LFS无严格限制受配额约束只存指针实体存LFS存储1GB存储1GB/月带宽需要版本管理的大文件如设计稿、样本数据GitHub Releases单附件2GB不进git历史依赖仓库总空间安装包、二进制、模型权重发布split拆分后push拆完的每个分片100MB进git历史无额外成本偶尔一次性传大文件不追求版本管理对象存储/网盘取决于服务商完全不入仓库各服务商不同数据集、备份、多人共享超大文件从成本角度说LFS 不是免费的无限空间免费账户只有1GB 存储 1GB/月带宽。一个 500MB 的模型文件第一次 push 就会用掉你一半存储配额如果有两个人各 clone 一次当月带宽就清零了。所以 LFS 真正的适用对象是需要纳入版本管理、更新频率不低、团队必须通过 git 拿最新版的文件。2.2 选型判断这份清单直接照着对我自己在面对大文件时一般按这个顺序做判断你可以直接抄文件是否需要在不同 commit 之间追踪历史版本需要 → Git LFS文件是构建产物/安装包只是给别人下载不需要追踪中间版本 → GitHub Releases文件是一次性临时共享不需要长期保存 → 对象存储预签名链接或者网盘文件是大数据集团队所有人都要经常拉取→ 对象存储别塞 git只是想绕过 100MB 限制赶紧把东西传上去→ split 拆分是最快方案这里要泼一盆冷水没有任何一种方案能让你把 10GB 的数据集合理地塞进 GitHub 仓库。GitHub 不是一个对象存储服务它是代码托管平台。超过 1GB 级别的文件不管走哪条路都会在 clone 或者带宽上付出惨痛代价。2.3 方案选错的代价选型错误不是换个方案那么简单因为 git 历史是会留痕的。最典型的错误就是前面说的直接把 200MB 的模型权重 commit 进主分支等发现问题时这个对象已经进了历史仓库体积永远背着一个 200MB 的包袱。另一种常见错误是 LFS 当网盘用。把大量频繁变动的文件全部 track 进 LFS结果免费带宽一个月内被刷爆之后所有团队成员 push 都报 quota exceeded。你在 LFS 里存的每一个字节都对应真实的存储和带宽账单它不是 GitHub 送你的无限硬盘。所以先想清楚用途再动工具。不要因为某个方案能传大文件就用它要因为这个文件的性质适合某个方案才用它。3. Git LFS完整实操从安装到提交一条龙如果文件确实需要进版本历史Git LFS 就是绕不开的方案。这里把完整流程走一遍每一步都说明一下为什么要这么做免得你安装完不知道怎么用或者用了一半卡在奇怪的地方。3.1 安装Git LFS与初始化先确认本地环境装没装 LFS最简单的方法是直接执行git lfs version。如果提示找不到命令按系统分三种装法# macOS有Homebrew brew install git-lfs # Ubuntu/Debian sudo apt-get install git-lfs # Windows # 从我实际经验看在 https://git-lfs.com 下载安装包最稳妥 # 或者如果你已经装了 Git for Windows安装包里有自带 git-lfs勾选即可安装完成后进入你的项目目录执行一次全局初始化git lfs install这条命令会修改你的 git 全局配置把 LFS 需要的 filter 钩子注册进 Git。不执行这一步后面 track 了文件也会不生效。注意它改的是全局配置所以只需要做一次不是每个仓库都要重复初始化。提示如果在公司内网环境拿到的是离线安装包安装完记得用git lfs install --skip-repo确认钩子状态。3.2 跟踪文件类型并提交在仓库里选择需要走 LFS 的文件类型比如模型权重、压缩包、数据文件git lfs track *.pth git lfs track *.zip git lfs track data/*.bin执行完文件夹里会多出一个.gitattributes文件这是 LFS 的核心配置文件它告诉 Git 哪些模式匹配的文件要用 LFS 处理。这个文件本身要正常提交进仓库git add .gitattributes git add model.pth git commit -m chore: 使用 LFS 管理模型文件这里有个容易踩的坑如果你在 track 之前已经把一个大文件 add 进 index 了track 之后必须重新 add。因为 Git 是在 add 的时候决定对象入库方式的track 之后不加一次文件仍然会按普通 blob 进 git 存储。正确顺序是先 track再 add再 commit。3.3 推送与拉取时到底发生了什么push 的时候LFS 背后的动作和普通 git push 不一样。普通文件会直接作为 blob 存入 .git 目录LFS 文件在本地被替换成一段几十字节的文本指针pointer真正的文件内容被单独上传到 GitHub 的 LFS 存储服务。所以你在远程仓库看到的 LFS 文件其实是一段包含 SHA256 哈希和版本信息的指针文本。别人 clone 这个仓库时git 只会拉取指针然后在 checkout 阶段通过 LFS 钩子从远程拉取真实文件内容。这个设计的价值在于仓库本体很小clone 很快但需要某个大文件时又能按需取回。我自己在拉取代码时发现的一个体验差异是如果团队里有人 push 了新的 LFS 文件其他人 pull 时如果没装 git-lfs只会看到一堆指针文件真实内容拉不下来。所以团队使用 LFS必须确保所有成员都在本地装了 git-lfs否则会出现代码在但数据全没的诡异状态。3.4 配额、费用与删除LFS文件LFS 免费配额是1GB 存储空间 1GB/月带宽超出后就无法继续 push LFS 文件只能购买 Data Pack个人账户是 $5/月起包含 50GB 存储和 50GB 带宽。关于配额有两点容易误判存储配额按所有存过的 LFS 文件历史版本总大小计算。你把一个大文件更新 5 次存储占用算的是所有版本之和不是只看最新版本。带宽配额按数据拉取量计算。团队 10 个人每次 clone 都要把 500MB 的 LFS 文件各拉一遍一次就是 5GB 带宽免费额度自然不够看。如果某个 LFS 文件已经不需要了从仓库里删除并提交不会立即释放存储配额。GitHub 的 LFS 存储是独立于 git 历史管理的你需要一并处理历史引用和 LFS 对象。实践中最稳妥的方式是确认团队都不需要旧对象后在 GitHub 网页端进入仓库的 Settings → Git LFS 管理释放存储或者联系官方支持处理超限对象。4. 已经 push 了大文件怎么办清理历史提交的全过程如果说 LFS 是进攻型武器那清理历史就是拆迁队。仓库已经被大文件污染了光靠删文件、再 commit 解决不了问题因为大文件还躺在历史提交里仓库体积和 push 限制问题都没根治。4.1 先说为什么不能直接删文件很多人遇到 100MB 报错的第一反应是那我直接git rm删掉再提交不就行了。 实际上不行。Git 的历史是不可变的快照链每个 commit 都指向父提交你删文件的这个提交虽然不包含大文件了但之前的那个提交仍然包含。GitHub 检查历史对象时照样看到那个 100MB 的 blobpush 照旧失败。所以必须做的是重写历史。重写之后旧的提交被新提交替代大文件对象在 GC 时才可能被真正清除。这也是为什么整个过程需要 force push——你是在改istory不是追加一个 commit。4.2 git filter-repo现在更推荐的清理方式早期大家用git filter-branch但它又慢又麻烦。现在更推荐git filter-repo效率和稳定性都高很多。先安装# 用 pip 安装 pip install git-filter-repo # macOS 也可以用 brew brew install git-filter-repo然后做一个 mirror 克隆镜像克隆不带工作目录纯粹为了重写历史git clone --mirror gitgithub.com:yourname/yourrepo.git cd yourrepo.git git filter-repo --strip-blobs-bigger-than 100M这条命令会扫描所有历史提交找出所有超过 100MB 的 blob 并删除。执行完毕后再把远程地址加回来并强制推送git remote add origin gitgithub.com:yourname/yourrepo.git git push --force --all如果你还要顺便清理 tags在 push 时加上--tags。注意 filter-repo 为了保护隐私会默认移除原 remote 配置所以需要重新 add。4.3 团队协作下的强制推送流程历史重写最麻烦的不是技术而是团队协作。因为所有本地 clone 都基于旧提交你 force push 之后其他人如果不做处理下一次 push 会把旧的提交重新推回去你清理的工作就白干了。这里给一个稳妥的协作步骤提前在群里/邮件里通知团队xx 点开始清理历史期间所有人不要 push执行 filter-repo force push要求每个成员在本地手动重新同步git fetch --all git reset --hard origin/main如果成员有本地 feature 分支操作要更小心先把分支 push 到远端备份再 cherry-pick 最近的提交到新历史。4.4 清理后仓库瘦身没有还没完force push 完成不等于大文件已经彻底消失。远端和本地都还可能有悬空对象dangling objects。在本地仓库里执行git reflog expire --expirenow --all git gc --prunenow --aggressive这两条命令的意义是让 reflog 里的引用全部过期再激进地做一次垃圾回收把没有引用的对象物理删除。执行后git count-objects -vH查看仓库实际大小如果size-pack降下来了才算真正清理干净。否则那些已删除的大文件对象仍然占用本地磁盘和远端带宽。远端的历史对象清理则取决于 GitHub 端对仓库的重新计算不是立即发生但仓库推送时的 100MB 检查会马上恢复正常。如果你希望 GitHub 端也彻底回收存储需要联系官方支持说明情况一般几天内会处理。5. 不折腾LFS的替代方案Release、拆分与外部存储不是所有大文件都需要进版本历史。很多时候只是我想把这个文件放 GitHub 上大家能下载那完全没必要动用 LFS 或者历史重写这种重型武器。这里说三种更轻量、在很多场景下更合理的替代方案。5.1 GitHub Releases适合分发安装包和二进制GitHub Releases 是官方提供的发版功能单附件允许到 2GB而且不占用 git 仓库的常规对象空间接口稳定还有配套的下载统计页。我处理团队的安装包发布时基本都用它比往仓库里塞压缩包干净得多。网页端操作很简单打开仓库主页 → Releases → Draft a new release → 填版本号和说明 → 把文件拖到附件区域 → 发布。命令行可以用ghgh release create v1.0.0 model.pth dataset.zip --title 版本发布 --notes 见更新日志一个容易被忽略的点Release 页面还能直接编辑已有版本重新上传附件替换旧文件适合最新版下载这种常见需求。没有中间历史版本不产生存储包袱。另外一个实用技巧是配合 GitHub 的 Latest release 逻辑可以在 README 里放一个始终指向最新版附件的下载链接用户不用翻版本列表。5.2 split拆分大文件先传后合并如果只是临时需要把一个超过 100MB 的文件塞进仓库又不想新增 LFS 配额可以把它拆成多个小于 100MB 的分片全部 push 到仓库后再提供合并指令。这个方法治标不治本但胜在零配置、零额外成本对付一次性传输非常快。在 Linux/macOS 的终端或者 Windows 的 Git Bash 里# 把 300MB 的模型文件拆成 4 个 90MB 的分片 split -b 90m model.pth model_parts_ # 会生成 model_parts_aa、model_parts_ab、model_parts_ac、model_parts_ad然后把这些分片一起提交、push 到仓库。下载方拿到后合并并校验cat model_parts_* model.pth md5sum model.pth # 和源文件的 md5 对比确认没损坏Windows 环境如果不方便装 Git Bash也可以用 7-Zip 的分卷压缩功能右键 → 添加到压缩包 → 选择分卷大小 90MB。这个方法唯一的成本是操作上的琐碎以及仓库里多了一堆分片文件。但好处是直接绕开 100MB 限制连 LFS 都不用初始化。我自己在给不太熟悉 git 伙伴做数据交接时偶尔会这样处理——在某些场景下简单粗暴反而比标准方案更有效率。5.3 对象存储与网盘数据集的归宿真正的大块头——几十 GB 的数据集、全量备份、算法训练产物——根本不适合待在 GitHub 上。我的建议是放到对象存储或者网盘然后只把下载链接提交到仓库 README 或 Release 说明里。对象存储比如阿里云 OSS、腾讯云 COS、MinIO 自建的优势是带宽高、支持断点续传、可以生成临时有效期的预签名 URL适合给团队或用户提供可控的下载入口。发布前的流程一般是把数据上传到对象存储 Bucket为准入控制生成一个带有效期的 URL比如 7 天用 SDK 或者控制台生成把 URL 写到 Release 或 README 中网盘是更省事的选择适合不追求自动化、只是临时共享的场景。缺点是你没法控制别人下载的带宽链接也容易失效。数据类大文件放对象存储还有一个隐藏价值别人 clone 你的仓库时不会被巨型文件拖垮。仓库交互速度和大文件下载需求完全解耦这是 git 仓库、LFS 都做不到的。5.4 国内代码托管平台的双仓库同步很多开发者在 GitHub 本身访问不稳定的情况下会把自己仓库同步一份到国内代码托管平台比如 Gitee日常用国内平台做仓库交互GitHub 只保留一份镜像。这是一种绕开 GitHub 网络瓶颈的务实做法也让大文件的拉取变得更可控。具体操作不复杂在 Gitee 新建空仓库把 GitHub 仓库添加为 remotegit remote add gitee gitgitee.com:yourname/yourrepo.git git push gitee --all git push gitee --tags后续每次提交可以同时推送两个 remotegit push github --all git push gitee --all如果要保持镜像自动同步Gitee 有从 GitHub 拉取更新的功能在仓库管理后台设置即可实测对小团队和开源项目完全够用。这个方案的好处是下载和协作都可以走国内平台大文件的传输速度会明显更稳定但注意它不等于把 GitHub 的限制变没了托管平台本身也有单文件大小限制大文件仍然需要按前文思路处理。6. 上传中断与网络波动的几个实战处理手段大文件上传除了触发 100MB 校验还经常死在半路——推到 90% 突然报错重试后又要重新推。这种情况和文件大小限制无关更多是 HTTP 传输层面和网络环境的问题。这里整理几个我自己实测有效的处理手段。6.1 报错怎么看常见的几种失败姿势大文件 push 到 GitHub 常见报错有这么几类先对号入座报错特征通常原因处理方向RPC failed; curl 56 OpenSSL SSL_read: SSL_ERROR_SYSCALLHTTP/2 连接被中断、缓冲区不足调 postBuffer、换 HTTP/1.1RPC failed; HTTP 413 curl 22请求体太大被中间层拒绝调 postBuffer、分批 pushfatal: The remote end hung up unexpectedly连接超时或网络波动换 SSH、调整 timeouterror: pack-objects died of signal 9464内存不足或 pack 太大分批提交、减小单次 pack大文件上传本质上是把 git 的 pack 文件整体通过 HTTP 发送。任何一环的稳定性问题都会被大体积放大这就是为什么几十 KB 的提交看起来没事、几百 MB 的 push 就各种灵异错误。6.2 http.postBuffer调优与SSL问题最常用的第一个处理手段是调大 HTTP 缓冲区git config --global http.postBuffer 524288000这个配置项的值是字节数默认一般是 1MB 或者更小不同 git 版本不一样。当 push 的数据量超过缓冲区时git 的 HTTP 传输会被截断报错往往就是上面表格里的 curl 56 或 413。调大到 500MB 之后大多数传输中断问题能得到缓解。如果问题依旧可以考虑禁用 HTTP/2。某些网络环境下 HTTP/2 的多路复用反而会导致连接不稳定git config --global http.version HTTP/1.1另外HTTPS 证书校验在特殊网络环境公司代理、自签证书下也可能干扰大文件传输。但这块要非常小心不要为了图方便全局关闭证书校验更推荐针对单个仓库单独配置并且只在明确知道风险的情况下操作git config http.sslVerify false # 强烈不建议全局关闭只能针对可控仓库临时用6.3 SSH协议与KeepAlive配置HTTPS push 走的是 443 端口容易受到各种链路干扰。一个很有效的替代方案是把远程地址从 HTTPS 换成 SSHSSH 走 22 端口传输稳定性和重连机制通常更好git remote set-url origin gitgithub.com:yourname/yourrepo.git ssh-keygen -t ed25519 -C your_emailexample.com # 把 ~/.ssh/id_ed25519.pub 内容添加到 GitHub - Settings - SSH keys换完后可以ssh -T gitgithub.com测试连通性。另一个与 SSH 相关的稳定手段是开启 KeepAlive防止长连接被空闲超时机制切断。在~/.ssh/config里添加Host github.com HostName github.com User git ServerAliveInterval 60 ServerAliveCountMax 3这样即使传输过程中有一小段时间没有数据流动SSH 连接也会维持住不会因为网络空闲被误杀。实测下来对于几百 MB 的 push这配置能避免很大一部分中途断连问题。6.4 分批提交与浅克隆兜底如果调优了传输层仍然不稳定那就从源头减小单次 push 的数据量。把一个大 push 拆成多个小提交逐个推上去是目前最有效的兜底手段没有之一。听起来笨但实际中分 5 次每次 20MB比一次推 100MB的成功率高得多。配合这个消息队列一样的操作顺序git add file_part1 git commit -m upload part1 git push git add file_part2 git commit -m upload part2 git push # 按需继续分批提交也适合那些仓库里一次新增了大量文件的场景避免单次 pack 过大。另一个实用的技巧是浅克隆如果只是临时需要拉一次仓库代码不需要历史可以用--depth 1只拉最新提交减少网络传输量。配合大文件场景git clone --depth 1能显著降低 clone 阶段失败的概率。等需要历史的时候再git fetch --unshallow补全。如果仓库本身下载长期不稳定也可以找公开的 GitHub 镜像站点来拉取下载包。这类站点在开发者社区里很常见但注意它们只适合下载公开项目不要在不可信的服务上提交或传输任何未公开、敏感的内容。最后再分享一点我个人的习惯。处理 GitHub 大文件问题我现在的流程基本固定为先判断文件要不要版本管理要的走 Git LFS不要的看是给谁下载——给人下载用 Release给程序下载用对象存储。临时应急就 split传完通知别人合并。平时在项目里提前把*.pth、*.zip这类文件加进.gitignore或者git lfs track从源头避免大文件混进普通提交里。这个习惯帮我省掉了至少十次仓库突然 push 失败的深夜加班也希望你能少踩这些坑。 GitHub大文件上传失败？Git LFS与Release方案全解析
这个报错估计折腾过不少刚接触 GitHub 的朋友——你辛辛苦苦把一个模型权重文件、数据集压缩包或者安装镜像拖进仓库结果 push 的时候终端直接甩出一句remote: error: File model.pth is 132.7 MB; this exceeds GitHubs file size limit of 100.0 MB remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.然后整个提交被拒仓库状态卡在中间重试好几次都是同一个结果。这篇文章就是来解决这个问题的我会把 GitHub 对上传大文件的限制规则讲清楚再把 Git LFS、Release、拆分文件、对象存储这几条正经路线的实操步骤和踩坑经验完整写出来最后补上上传中断、网络波动这些高频问题的处理方法。适合刚把 GitHub 当网盘用的新手也适合团队协作时被大文件搞崩仓库的老手。1. GitHub的100MB限制到底是什么先搞清楚规则再动手很多人一看到 100MB 这个数字就以为是仓库上限其实规则比这复杂一点而且不同的上传入口限制完全不一样。先把这个底层逻辑理顺后面选方案才不会被报错带着走。1.1 网页上传、命令行push与Release附件是三套规则GitHub 同一个项目里网页端上传、git push、Release 附件走的是三套完全不同的限制逻辑。很多人的第一个误区就在这里——在网页上拖一个 80MB 的文件成功了就以为命令行 push 也没问题结果被打了个措手不及。网页端上传的文件官方限制是单文件不能超过 25MB。这已经被卡得很死超过这个大小浏览器直接弹红字根本不给继续的机会。这个入口适合传配置文件、小图片、文档之类的零碎内容完全不适合传任何像样的程序包或者数据集。命令行 git push 的限制才是大家常说的 100MB。理论上单个文件超过 50MB 时 Git 就开始警告但真正硬性拒绝是文件超过 100MB。这里的 100MB 是指单个 blob 对象的大小不是仓库总大小所以哪怕你一个仓库里 200 个文件每个 99MBgit push 也能过只是过程会非常酸爽。Release 附件是一套独立体系单个附件最大允许 2GB而且不占用 git 仓库的对象存储。这个限制比 git push 宽得多非常适合发布二进制产物、安装包、模型权重这些根本没必要进版本历史的大块头。1.2 50MB警告、100MB硬限制与100GB仓库上限Git 的警告机制是这样的当你准备 push 的文件超过 50MB本地 git 会先给你一个 warning意思是这个文件有点大了建议你用 LFS。这个警告不会阻止提交但已经是一个明确的信号——继续往这个方向走马上就会撞墙。超过 100MB 就是硬性拒绝错误码 GH001GitHub 服务器直接在 pre-receive 钩子阶段就把提交弹回来你的对象根本进不了远程仓库。这个机制是同步阻塞的也就是说你 push 到 GitHub 时远端会在接收对象之前先检查所有 blob 的大小超标的直接整个拒绝不存在先传上去再说的情况。仓库总大小方面GitHub 官方给出的是建议不超过 1GB硬上限 100GB。注意这个 1GB 是推荐不是强制但是当仓库膨胀到这个量级clone 和 pull 的体验会变得极其痛苦因为每次操作都要把所有历史对象拉一遍。我见过一个团队把模型权重直接提交进 git 仓库三个月后仓库到了 8GB新同事 clone 一次要半小时CI 拉代码直接超时。这种仓库从健康度角度讲已经算废了一半。1.3 还有一个经常被忽略的历史包袱这里要特别提醒一个隐蔽的坑即使你现在把大文件从工作目录删掉了只要它停留在 git 历史里它依然占用仓库体积而且依然可能导致 push 失败。原因在于 git 的对象模型——每次 commit 保存的是完整快照的引用大文件一旦进入某个历史提交后续所有 clone 该仓库的人都需要下载这个对象。GitHub 检查的是仓库里所有历史对象不是只看最新提交。所以很多人遇到的情况是删掉了大文件重新 commitpush 还是失败或者仓库体积没有变小。这就是为什么那些大文件必须做历史清理后面第四章会专门讲。2. 大文件方案选型别一上来就无脑上LFS东西会报错的时候很多人第一反应是那我用 Git LFS 不就行了。LFS 确实是解决 100MB 限制的正规方案但不一定是最优解尤其对免费账户来说LFS 的配额很紧用错了地方反而会给自己挖更大的坑。先做一轮选型对比再决定具体走哪条路。2.1 四条路线的对比我把实际项目中见过的主流路线整理成一个表方便大家对照自己场景选方案单文件上限是否进版本历史免费额度典型场景Git LFS无严格限制受配额约束只存指针实体存LFS存储1GB存储1GB/月带宽需要版本管理的大文件如设计稿、样本数据GitHub Releases单附件2GB不进git历史依赖仓库总空间安装包、二进制、模型权重发布split拆分后push拆完的每个分片100MB进git历史无额外成本偶尔一次性传大文件不追求版本管理对象存储/网盘取决于服务商完全不入仓库各服务商不同数据集、备份、多人共享超大文件从成本角度说LFS 不是免费的无限空间免费账户只有1GB 存储 1GB/月带宽。一个 500MB 的模型文件第一次 push 就会用掉你一半存储配额如果有两个人各 clone 一次当月带宽就清零了。所以 LFS 真正的适用对象是需要纳入版本管理、更新频率不低、团队必须通过 git 拿最新版的文件。2.2 选型判断这份清单直接照着对我自己在面对大文件时一般按这个顺序做判断你可以直接抄文件是否需要在不同 commit 之间追踪历史版本需要 → Git LFS文件是构建产物/安装包只是给别人下载不需要追踪中间版本 → GitHub Releases文件是一次性临时共享不需要长期保存 → 对象存储预签名链接或者网盘文件是大数据集团队所有人都要经常拉取→ 对象存储别塞 git只是想绕过 100MB 限制赶紧把东西传上去→ split 拆分是最快方案这里要泼一盆冷水没有任何一种方案能让你把 10GB 的数据集合理地塞进 GitHub 仓库。GitHub 不是一个对象存储服务它是代码托管平台。超过 1GB 级别的文件不管走哪条路都会在 clone 或者带宽上付出惨痛代价。2.3 方案选错的代价选型错误不是换个方案那么简单因为 git 历史是会留痕的。最典型的错误就是前面说的直接把 200MB 的模型权重 commit 进主分支等发现问题时这个对象已经进了历史仓库体积永远背着一个 200MB 的包袱。另一种常见错误是 LFS 当网盘用。把大量频繁变动的文件全部 track 进 LFS结果免费带宽一个月内被刷爆之后所有团队成员 push 都报 quota exceeded。你在 LFS 里存的每一个字节都对应真实的存储和带宽账单它不是 GitHub 送你的无限硬盘。所以先想清楚用途再动工具。不要因为某个方案能传大文件就用它要因为这个文件的性质适合某个方案才用它。3. Git LFS完整实操从安装到提交一条龙如果文件确实需要进版本历史Git LFS 就是绕不开的方案。这里把完整流程走一遍每一步都说明一下为什么要这么做免得你安装完不知道怎么用或者用了一半卡在奇怪的地方。3.1 安装Git LFS与初始化先确认本地环境装没装 LFS最简单的方法是直接执行git lfs version。如果提示找不到命令按系统分三种装法# macOS有Homebrew brew install git-lfs # Ubuntu/Debian sudo apt-get install git-lfs # Windows # 从我实际经验看在 https://git-lfs.com 下载安装包最稳妥 # 或者如果你已经装了 Git for Windows安装包里有自带 git-lfs勾选即可安装完成后进入你的项目目录执行一次全局初始化git lfs install这条命令会修改你的 git 全局配置把 LFS 需要的 filter 钩子注册进 Git。不执行这一步后面 track 了文件也会不生效。注意它改的是全局配置所以只需要做一次不是每个仓库都要重复初始化。提示如果在公司内网环境拿到的是离线安装包安装完记得用git lfs install --skip-repo确认钩子状态。3.2 跟踪文件类型并提交在仓库里选择需要走 LFS 的文件类型比如模型权重、压缩包、数据文件git lfs track *.pth git lfs track *.zip git lfs track data/*.bin执行完文件夹里会多出一个.gitattributes文件这是 LFS 的核心配置文件它告诉 Git 哪些模式匹配的文件要用 LFS 处理。这个文件本身要正常提交进仓库git add .gitattributes git add model.pth git commit -m chore: 使用 LFS 管理模型文件这里有个容易踩的坑如果你在 track 之前已经把一个大文件 add 进 index 了track 之后必须重新 add。因为 Git 是在 add 的时候决定对象入库方式的track 之后不加一次文件仍然会按普通 blob 进 git 存储。正确顺序是先 track再 add再 commit。3.3 推送与拉取时到底发生了什么push 的时候LFS 背后的动作和普通 git push 不一样。普通文件会直接作为 blob 存入 .git 目录LFS 文件在本地被替换成一段几十字节的文本指针pointer真正的文件内容被单独上传到 GitHub 的 LFS 存储服务。所以你在远程仓库看到的 LFS 文件其实是一段包含 SHA256 哈希和版本信息的指针文本。别人 clone 这个仓库时git 只会拉取指针然后在 checkout 阶段通过 LFS 钩子从远程拉取真实文件内容。这个设计的价值在于仓库本体很小clone 很快但需要某个大文件时又能按需取回。我自己在拉取代码时发现的一个体验差异是如果团队里有人 push 了新的 LFS 文件其他人 pull 时如果没装 git-lfs只会看到一堆指针文件真实内容拉不下来。所以团队使用 LFS必须确保所有成员都在本地装了 git-lfs否则会出现代码在但数据全没的诡异状态。3.4 配额、费用与删除LFS文件LFS 免费配额是1GB 存储空间 1GB/月带宽超出后就无法继续 push LFS 文件只能购买 Data Pack个人账户是 $5/月起包含 50GB 存储和 50GB 带宽。关于配额有两点容易误判存储配额按所有存过的 LFS 文件历史版本总大小计算。你把一个大文件更新 5 次存储占用算的是所有版本之和不是只看最新版本。带宽配额按数据拉取量计算。团队 10 个人每次 clone 都要把 500MB 的 LFS 文件各拉一遍一次就是 5GB 带宽免费额度自然不够看。如果某个 LFS 文件已经不需要了从仓库里删除并提交不会立即释放存储配额。GitHub 的 LFS 存储是独立于 git 历史管理的你需要一并处理历史引用和 LFS 对象。实践中最稳妥的方式是确认团队都不需要旧对象后在 GitHub 网页端进入仓库的 Settings → Git LFS 管理释放存储或者联系官方支持处理超限对象。4. 已经 push 了大文件怎么办清理历史提交的全过程如果说 LFS 是进攻型武器那清理历史就是拆迁队。仓库已经被大文件污染了光靠删文件、再 commit 解决不了问题因为大文件还躺在历史提交里仓库体积和 push 限制问题都没根治。4.1 先说为什么不能直接删文件很多人遇到 100MB 报错的第一反应是那我直接git rm删掉再提交不就行了。 实际上不行。Git 的历史是不可变的快照链每个 commit 都指向父提交你删文件的这个提交虽然不包含大文件了但之前的那个提交仍然包含。GitHub 检查历史对象时照样看到那个 100MB 的 blobpush 照旧失败。所以必须做的是重写历史。重写之后旧的提交被新提交替代大文件对象在 GC 时才可能被真正清除。这也是为什么整个过程需要 force push——你是在改istory不是追加一个 commit。4.2 git filter-repo现在更推荐的清理方式早期大家用git filter-branch但它又慢又麻烦。现在更推荐git filter-repo效率和稳定性都高很多。先安装# 用 pip 安装 pip install git-filter-repo # macOS 也可以用 brew brew install git-filter-repo然后做一个 mirror 克隆镜像克隆不带工作目录纯粹为了重写历史git clone --mirror gitgithub.com:yourname/yourrepo.git cd yourrepo.git git filter-repo --strip-blobs-bigger-than 100M这条命令会扫描所有历史提交找出所有超过 100MB 的 blob 并删除。执行完毕后再把远程地址加回来并强制推送git remote add origin gitgithub.com:yourname/yourrepo.git git push --force --all如果你还要顺便清理 tags在 push 时加上--tags。注意 filter-repo 为了保护隐私会默认移除原 remote 配置所以需要重新 add。4.3 团队协作下的强制推送流程历史重写最麻烦的不是技术而是团队协作。因为所有本地 clone 都基于旧提交你 force push 之后其他人如果不做处理下一次 push 会把旧的提交重新推回去你清理的工作就白干了。这里给一个稳妥的协作步骤提前在群里/邮件里通知团队xx 点开始清理历史期间所有人不要 push执行 filter-repo force push要求每个成员在本地手动重新同步git fetch --all git reset --hard origin/main如果成员有本地 feature 分支操作要更小心先把分支 push 到远端备份再 cherry-pick 最近的提交到新历史。4.4 清理后仓库瘦身没有还没完force push 完成不等于大文件已经彻底消失。远端和本地都还可能有悬空对象dangling objects。在本地仓库里执行git reflog expire --expirenow --all git gc --prunenow --aggressive这两条命令的意义是让 reflog 里的引用全部过期再激进地做一次垃圾回收把没有引用的对象物理删除。执行后git count-objects -vH查看仓库实际大小如果size-pack降下来了才算真正清理干净。否则那些已删除的大文件对象仍然占用本地磁盘和远端带宽。远端的历史对象清理则取决于 GitHub 端对仓库的重新计算不是立即发生但仓库推送时的 100MB 检查会马上恢复正常。如果你希望 GitHub 端也彻底回收存储需要联系官方支持说明情况一般几天内会处理。5. 不折腾LFS的替代方案Release、拆分与外部存储不是所有大文件都需要进版本历史。很多时候只是我想把这个文件放 GitHub 上大家能下载那完全没必要动用 LFS 或者历史重写这种重型武器。这里说三种更轻量、在很多场景下更合理的替代方案。5.1 GitHub Releases适合分发安装包和二进制GitHub Releases 是官方提供的发版功能单附件允许到 2GB而且不占用 git 仓库的常规对象空间接口稳定还有配套的下载统计页。我处理团队的安装包发布时基本都用它比往仓库里塞压缩包干净得多。网页端操作很简单打开仓库主页 → Releases → Draft a new release → 填版本号和说明 → 把文件拖到附件区域 → 发布。命令行可以用ghgh release create v1.0.0 model.pth dataset.zip --title 版本发布 --notes 见更新日志一个容易被忽略的点Release 页面还能直接编辑已有版本重新上传附件替换旧文件适合最新版下载这种常见需求。没有中间历史版本不产生存储包袱。另外一个实用技巧是配合 GitHub 的 Latest release 逻辑可以在 README 里放一个始终指向最新版附件的下载链接用户不用翻版本列表。5.2 split拆分大文件先传后合并如果只是临时需要把一个超过 100MB 的文件塞进仓库又不想新增 LFS 配额可以把它拆成多个小于 100MB 的分片全部 push 到仓库后再提供合并指令。这个方法治标不治本但胜在零配置、零额外成本对付一次性传输非常快。在 Linux/macOS 的终端或者 Windows 的 Git Bash 里# 把 300MB 的模型文件拆成 4 个 90MB 的分片 split -b 90m model.pth model_parts_ # 会生成 model_parts_aa、model_parts_ab、model_parts_ac、model_parts_ad然后把这些分片一起提交、push 到仓库。下载方拿到后合并并校验cat model_parts_* model.pth md5sum model.pth # 和源文件的 md5 对比确认没损坏Windows 环境如果不方便装 Git Bash也可以用 7-Zip 的分卷压缩功能右键 → 添加到压缩包 → 选择分卷大小 90MB。这个方法唯一的成本是操作上的琐碎以及仓库里多了一堆分片文件。但好处是直接绕开 100MB 限制连 LFS 都不用初始化。我自己在给不太熟悉 git 伙伴做数据交接时偶尔会这样处理——在某些场景下简单粗暴反而比标准方案更有效率。5.3 对象存储与网盘数据集的归宿真正的大块头——几十 GB 的数据集、全量备份、算法训练产物——根本不适合待在 GitHub 上。我的建议是放到对象存储或者网盘然后只把下载链接提交到仓库 README 或 Release 说明里。对象存储比如阿里云 OSS、腾讯云 COS、MinIO 自建的优势是带宽高、支持断点续传、可以生成临时有效期的预签名 URL适合给团队或用户提供可控的下载入口。发布前的流程一般是把数据上传到对象存储 Bucket为准入控制生成一个带有效期的 URL比如 7 天用 SDK 或者控制台生成把 URL 写到 Release 或 README 中网盘是更省事的选择适合不追求自动化、只是临时共享的场景。缺点是你没法控制别人下载的带宽链接也容易失效。数据类大文件放对象存储还有一个隐藏价值别人 clone 你的仓库时不会被巨型文件拖垮。仓库交互速度和大文件下载需求完全解耦这是 git 仓库、LFS 都做不到的。5.4 国内代码托管平台的双仓库同步很多开发者在 GitHub 本身访问不稳定的情况下会把自己仓库同步一份到国内代码托管平台比如 Gitee日常用国内平台做仓库交互GitHub 只保留一份镜像。这是一种绕开 GitHub 网络瓶颈的务实做法也让大文件的拉取变得更可控。具体操作不复杂在 Gitee 新建空仓库把 GitHub 仓库添加为 remotegit remote add gitee gitgitee.com:yourname/yourrepo.git git push gitee --all git push gitee --tags后续每次提交可以同时推送两个 remotegit push github --all git push gitee --all如果要保持镜像自动同步Gitee 有从 GitHub 拉取更新的功能在仓库管理后台设置即可实测对小团队和开源项目完全够用。这个方案的好处是下载和协作都可以走国内平台大文件的传输速度会明显更稳定但注意它不等于把 GitHub 的限制变没了托管平台本身也有单文件大小限制大文件仍然需要按前文思路处理。6. 上传中断与网络波动的几个实战处理手段大文件上传除了触发 100MB 校验还经常死在半路——推到 90% 突然报错重试后又要重新推。这种情况和文件大小限制无关更多是 HTTP 传输层面和网络环境的问题。这里整理几个我自己实测有效的处理手段。6.1 报错怎么看常见的几种失败姿势大文件 push 到 GitHub 常见报错有这么几类先对号入座报错特征通常原因处理方向RPC failed; curl 56 OpenSSL SSL_read: SSL_ERROR_SYSCALLHTTP/2 连接被中断、缓冲区不足调 postBuffer、换 HTTP/1.1RPC failed; HTTP 413 curl 22请求体太大被中间层拒绝调 postBuffer、分批 pushfatal: The remote end hung up unexpectedly连接超时或网络波动换 SSH、调整 timeouterror: pack-objects died of signal 9464内存不足或 pack 太大分批提交、减小单次 pack大文件上传本质上是把 git 的 pack 文件整体通过 HTTP 发送。任何一环的稳定性问题都会被大体积放大这就是为什么几十 KB 的提交看起来没事、几百 MB 的 push 就各种灵异错误。6.2 http.postBuffer调优与SSL问题最常用的第一个处理手段是调大 HTTP 缓冲区git config --global http.postBuffer 524288000这个配置项的值是字节数默认一般是 1MB 或者更小不同 git 版本不一样。当 push 的数据量超过缓冲区时git 的 HTTP 传输会被截断报错往往就是上面表格里的 curl 56 或 413。调大到 500MB 之后大多数传输中断问题能得到缓解。如果问题依旧可以考虑禁用 HTTP/2。某些网络环境下 HTTP/2 的多路复用反而会导致连接不稳定git config --global http.version HTTP/1.1另外HTTPS 证书校验在特殊网络环境公司代理、自签证书下也可能干扰大文件传输。但这块要非常小心不要为了图方便全局关闭证书校验更推荐针对单个仓库单独配置并且只在明确知道风险的情况下操作git config http.sslVerify false # 强烈不建议全局关闭只能针对可控仓库临时用6.3 SSH协议与KeepAlive配置HTTPS push 走的是 443 端口容易受到各种链路干扰。一个很有效的替代方案是把远程地址从 HTTPS 换成 SSHSSH 走 22 端口传输稳定性和重连机制通常更好git remote set-url origin gitgithub.com:yourname/yourrepo.git ssh-keygen -t ed25519 -C your_emailexample.com # 把 ~/.ssh/id_ed25519.pub 内容添加到 GitHub - Settings - SSH keys换完后可以ssh -T gitgithub.com测试连通性。另一个与 SSH 相关的稳定手段是开启 KeepAlive防止长连接被空闲超时机制切断。在~/.ssh/config里添加Host github.com HostName github.com User git ServerAliveInterval 60 ServerAliveCountMax 3这样即使传输过程中有一小段时间没有数据流动SSH 连接也会维持住不会因为网络空闲被误杀。实测下来对于几百 MB 的 push这配置能避免很大一部分中途断连问题。6.4 分批提交与浅克隆兜底如果调优了传输层仍然不稳定那就从源头减小单次 push 的数据量。把一个大 push 拆成多个小提交逐个推上去是目前最有效的兜底手段没有之一。听起来笨但实际中分 5 次每次 20MB比一次推 100MB的成功率高得多。配合这个消息队列一样的操作顺序git add file_part1 git commit -m upload part1 git push git add file_part2 git commit -m upload part2 git push # 按需继续分批提交也适合那些仓库里一次新增了大量文件的场景避免单次 pack 过大。另一个实用的技巧是浅克隆如果只是临时需要拉一次仓库代码不需要历史可以用--depth 1只拉最新提交减少网络传输量。配合大文件场景git clone --depth 1能显著降低 clone 阶段失败的概率。等需要历史的时候再git fetch --unshallow补全。如果仓库本身下载长期不稳定也可以找公开的 GitHub 镜像站点来拉取下载包。这类站点在开发者社区里很常见但注意它们只适合下载公开项目不要在不可信的服务上提交或传输任何未公开、敏感的内容。最后再分享一点我个人的习惯。处理 GitHub 大文件问题我现在的流程基本固定为先判断文件要不要版本管理要的走 Git LFS不要的看是给谁下载——给人下载用 Release给程序下载用对象存储。临时应急就 split传完通知别人合并。平时在项目里提前把*.pth、*.zip这类文件加进.gitignore或者git lfs track从源头避免大文件混进普通提交里。这个习惯帮我省掉了至少十次仓库突然 push 失败的深夜加班也希望你能少踩这些坑。