Git 仓库因为一个大文件直接卡死这种经历我相信不少人都遇到过。git push推到一半终端弹出一行remote: error: GH001: Large files detected紧接着是File ... exceeds 100 MB整个提交被拒绝你只能对着本地那个 150MB 的模型压缩包发呆。GitHub 的 100MB 单文件硬限制、50MB 软警告、1GB 仓库建议红线每一条都像悬在头上的剑。这个问题的标准解法就是 Git LFSLarge File Storage——用指针文件替换仓库里的大文件本体把真实内容挪到独立的 LFS 存储服务上既绕过 GitHub 的限制又不让.git目录变成磁盘杀手。这篇文章我从原理讲到实操从新仓库的初次配置讲到老仓库的历史迁移把 Git LFS 的落地全过程一次性说透。1. 大文件是怎么把一个友好仓库变成定时炸弹的1.1 先看 Git 的存储模型快照思维带来的体积放大器Git 和 SVN 这类传统版本控制有个本质区别SVN 记录的是文件增量diff每个版本只存变化了多少而 Git 干脆每次提交都生成一份完整的文件快照。也就是说哪怕你只是在 100MB 的二进制文件上改了一个字节Git 也会把改动后的整个 100MB 对象塞进.git/objects里。更麻烦的是Git 的压缩算法zlib对文本有效对已经压缩过的二进制文件比如.zip、.png、.mp4、.psd这类自身已经做过压缩处理的格式几乎毫无作用。压缩前 100MB压缩后还是 100MB纯纯地占空间。我举个实际数字假设你每周往仓库里更新一次 80MB 的模型文件一年 52 个版本光这一个文件的.git体积就膨胀到 4GB 以上。再加上 Git 的松散对象loose object和打包文件packfile机制历史里任何一个版本都不会自动消失——除非你重写历史或者用git gc清理但普通场景下你根本不会做也做不干净。这才是大文件真正的杀伤力它不只在当前工作区占地方而是把整个 Git 历史变成一个越来越臃肿的仓库胖子。1.2 GitHub 的限制红线与常见报错GitHub 对仓库体积的控制分三个层级很多新人只听过 100MB其实前面还有一条 50MB 警告线限制项阈值表现单文件软限制50MBpush 时警告不阻断单文件硬限制100MBpush 直接被拒绝仓库推荐大小1GB超过后 GitHub 会邮件提醒且 clone 体验明显下降仓库硬性警告5GB仓库被标记为超大可能被限制访问核心报错就是开头那句exceeds 100 MB还有一类常见的错误是GH002——通常出现在你写了filter规则或者尝试用子模块绕过的场景GitHub 会在服务端直接拦截。GitHub 甚至为这种情况专门提供了bfg-repo-cleaner和git filter-repo的官方推荐流程把历史里的大文件刨出去。但注意filter-repo只解决把历史改干净当你仍然需要在项目里继续维护这些大文件时LFS 才是从工作流层面根治问题的方式。2. Git LFS 的核心机制指针替换与 clean/smudge 过滤器2.1 指针文件长什么样为什么能骗过 GitGit LFS 的思路用一个词概括就是偷梁换柱当你git add一个被 LFS 跟踪的二进制文件时LFS 会拦截这个文件把它的真实内容上传到远程 LFS 存储服务器然后在 Git 仓库里只留一个指针文件pointer file。一个标准的 LFS 指针文件长这样version https://git-lfs.github.com/spec/v1 oid sha256:4d7a214fabb7a1e6e8c2b0f1f7a0e3cf1d9c1d0b6c0a5f3a51c3c04c8c1a9e1e24 size 134217728三行内容第一行是规范版本号第二行是文件内容的 SHA-256 哈希LFS 管这个叫 OID第三行是原始文件大小。Git 看到的是一个只有几百字节的文本文件提交、推送、合并都毫无压力真正的大体积数据被 LFS 客户端流式上传到独立的存储服务上和 Git 对象库彻底分家。这里有个关键点值得展开指针文件里的 SHA-256 跟 Git 内部的 SHA-1 对象 ID 是完全两套体系。Git 的 SHA-1 是针对整个文件内容计算的而 LFS 的 OID 是对真实大文件的内容做 SHA-256 哈希。这样做的好处是内容寻址content-addressable——两个不同的文件名、不同的提交版本只要文件内容相同LFS 存储里就只有一份对象天然支持去重。2.2 clean 与 smudge写入和取回时的两次翻译LFS 的实现依赖 Git 的filter 机制。Git 允许你注册两种过滤器clean filter在文件从工作区写入 Git 索引git add时触发LFS 在这里把真实文件换成指针文件。smudge filter在文件从 Git 检出到工作区git checkout、git pull时触发LFS 在这里读取指针里的 OID从本地缓存或远程把真实文件内容拉回来还原。你可以通过git config看到 LFS 注册的过滤器git config --global --list | grep lfs典型的输出类似filter.lfs.cleangit-lfs clean -- %f filter.lfs.smudgegit-lfs smudge -- %f filter.lfs.processgit-lfs filter-process filter.lfs.requiredtrue这个requiredtrue也很重要如果某个仓库用了 LFS 但客户端没装 git-lfsGit 会直接报错而不是静默地把指针文件当普通文本存进去这点我在第 6 节踩坑部分会详细说。实际使用中你还会注意到git add一个 LFS 文件时终端会有类似Uploading LFS objects: 100% (1/1)的进度条这就是 clean 阶段在做真实内容的上传。所以 LFS 的上传不只发生在git push早在git add的时候就开始了。2.3 LFS 不是 .gitignore也不是子模块这个误区的杀伤力极大。我见过有同事试图用.gitignore忽略大文件然后通过网盘私下分发结果团队成员各拿各的版本文件一旦过期或错乱问题比仓库膨胀还难查。.gitignore是不纳入版本管理而 LFS 是版本管理照做只是换了存储位置两者解决的是完全不同的需求。还有一类方案是 Git 子模块本质上是仓库套仓库适合管理变量独立、更新节奏不同的项目但作为大文件方案很尴尬——每个子模块都是一个完整 Git 仓库克隆时层层递归认证、权限、更新同步都是麻烦。LFS 则是在同一个仓库内透明切换对普通开发者来说除了安装 git-lfs 客户端和看几个进度条日常操作跟普通 Git 完全一致。这也是它能在 GitHub 生态里成为事实标准的原因透明、无感同时把大文件从 Git 对象库里彻底隔离出去。3. 从零落地安装、跟踪规则与首次推送3.1 各平台安装与 git lfs install第一步是装客户端不同平台命令不太一样# macOSHomebrew brew install git-lfs # Debian/Ubuntu sudo apt install git-lfs # CentOS/RHEL sudo yum install git-lfs # Windowschoco 或官方安装包 choco install git-lfs装完后在终端执行一次git lfs install这个命令的本质是帮你做两件事写入上面那双 clean/smudge 过滤器配置并安装一个post-checkout钩子确保每次检出时 LFS 对象能自动从远程拉取。注意它是全局配置跑一次就够了不用每个仓库都重复。新版 Git for Windows 其实已经默认捆绑了 git-lfs如果你的 Git Bash 版本比较新直接git lfs install就能用。Linux 上如果系统源的版本太旧建议直接用官方安装脚本否则可能因为 LFS 指针规范版本过低导致兼容问题。3.2 选择跟踪规则该跟踪什么不该跟踪什么进入项目仓库后用git lfs track声明要跟踪的文件类型。这个命令的本质是往.gitattributes里写入规则# 进入仓库目录 cd my-project # 声明跟踪规则 git lfs track *.psd git lfs track *.zip git lfs track *.mp4 git lfs track assets/models/*.bin执行后查看.gitattributes*.psd filterlfs difflfs mergelfs -text *.zip filterlfs difflfs mergelfs -text *.mp4 filterlfs difflfs mergelfs -text assets/models/*.bin filterlfs difflfs mergelfs -text注意-text这个标志。它告诉 Git 这个文件不要做换行符转换也不要尝试文本合并。二进制文件一旦被 Git 误伤、改了行尾LFS 的 OID 校验就会不通过我在第 6 节会详细讲这个坑。选择跟踪规则时我的建议是能明确匹配的就不要用宽泛通配符。比如全仓库git lfs track *这种操作等于把所有文件都丢给 LFS对付费配额和拉取性能都是灾难。通常盯着这几类就行设计源文件.psd / .ai / .sketch / .fig、资源包.zip / .7z / .tar.gz、媒体文件.mp4 / .mov / .wav、模型权重.pt / .h5 / .onnx / .bin、数据库备份.sql / .bak等不宜做纯文本 diff 的二进制大文件。3.3 .gitattributes 的维护与团队同步.gitattributes是走普通 Git 流程提交的。当你git add它之后整个仓库的所有协作者只要拉取到这次提交git-lfs 就会自动按规则拦截对应文件不需要团队每个人手动执行track命令。但有一个细节很多人忽略.gitattributes里的跟踪规则只能约束后续新增的文件这些规则在历史提交中不会追溯生效。也就是说如果你在第二次提交时才声明*.mp4要跟踪而第一次提交里已经有一个 300MB 的.mp4文件被当普通对象存进了 Git 历史那这个文件继续留在历史的.git包里未来依然是一个体积隐患。想把它抠出来就得用第 4 节的git lfs migrate做历史迁移。整个流程走下来就是如此git lfs track *.psd git add .gitattributes git add design/demo.psd git commit -m add psd with lfs git push origin main如果远程是 GitHubpush 结束后到仓库页面看一眼文件列表你会看到带 LFS 标记的文件条目点进去后 GitHub 展示的其实是 LFS 对象而不是像普通文本那样直接渲染内容。4. 老仓库救星git lfs migrate 的历史迁移指南4.1 为什么不能直接改写历史很多人在被大文件卡住之后的第一反应是那我重新提交一次不带上那个大文件不就行了。问题是大文件已经躺在历史提交里了新的提交不带它但旧的历史对象仍然占着.git/objects的空间。你就算在当前 HEAD 把这些文件删掉仓库体积也瘦不下去。GitHub 拒绝 push 的历史大文件本质就是检查所有要推送的 commit 对象而不是只看最新指针。所以必须用重写历史的方式把所有历史提交里符合规则的大文件全部替换成 LFS 指针。手工用filter-repo做工程量很大还要处理各种边界情况。好在官方提供了一个专门干这活的命令——git lfs migrate。4.2 migrate import 的完整实操与参数说明以我实际做过的一个项目举例仓库里有 300 个历史提交其中混着几十个.zip包和.pyc缓存文件仓库初始体积 2.3GB。迁移命令如下# 先备份原仓库 cp -r my-project my-project-backup # 进入仓库 cd my-project # 迁移所有分支上的 .zip 文件 git lfs migrate import --include*.zip,*.pyc --everything--everything表示对所有本地引用分支、标签覆盖迁移。如果你只想处理主干可以明确指定git lfs migrate import --include*.zip --include-refrefs/heads/main--include的语法和.gitattributes一致支持逗号分隔多个模式--exclude可以排除不想处理的目录。这里特别提醒两点一是migrate会重写 commit hash。也就是说迁移之后的历史在 SHA-1 校验层面和原历史完全不兼容老仓库的origin/main和本地迁移后的main会成为两个互不相干的分支直接git push会被拒绝。正确做法是强制推送git push origin --force main git push origin --force --tags二是如果原始仓库有外地协作者正在基于旧历史开发强制推送之后他们本地会进入历史分叉状态。唯一的补救办法就是让他们git fetch后用git rebase或重新 clone这个问题没有优雅解只能提前在团队里打好招呼。4.3 迁移后的仓库瘦身与 GC 处理migrate 执行完成后工作区文件已经变成 LFS 指针了但你本地的.git/objects里那些旧对象还占着空间。Git 的gc不会立刻回收它们因为有 reflog 和挂在 refs 上的临时引用挡着。需要手动清一遍# 删除所有 backup 引用migrate 会在 refs/original 下留备份 git for-each-ref --format%(refname) refs/original | xargs -n 1 git update-ref -d # 让 reflog 过期并立即清空所有不可达对象 git reflog expire --expirenow --all git gc --prunenow --aggressive跑完这套后.git目录才会真正瘦下来。我第一次迁移时只跑了gc、没有清理refs/original结果空间释放了一半都不到检查引用才发现旧对象被备份引用牢牢锁住。4.4 团队协作中迁移的前提与通知顺序如果你的仓库只有自己一个人在维护强制推送没太大后果。但一旦有协作者或 CI 系统迁移前至少要做三件事让所有同事把本地未推送的改动先推到远程并 pull 到干净状态因为迁移会从当前仓库的新历史重新生成一份完整的历史任何未同步的 commit 都会变成孤儿。在群里明确迁移窗口期窗口内禁止任何人 push。迁移完成后由仓库维护者第一时间强制推送。通知大家基于旧历史重新 clone不要尝试 pull 或者 rebase因为两段历史的合并方式不可预测。CI/CD 那边也要同步处理GitHub Actions 里默认的actions/checkoutv4虽然内置了 LFS 支持但自建的 CI 需要手动安装 git-lfs 并执行git lfs install否则 checkout 出来的只是指针文件构建直接失败。5. 配额、带宽与克隆体验LFS 的账要算清楚5.1 免费配额到底怎么算GitHub LFS 的免费额度是1GB 存储 1GB 带宽/月超出后有两种后果付费升级或者跳过 LFS 文件的下载仓库照常可用但大文件拿不到。很多人对 LFS 额度有个误解以为删除仓库里的文件就会释放额度。LFS 的存储空间按对象去重后的总量算而且删除引用并不会自动删除 LFS 对象。你从项目里删掉一个 500MB 的文件并推上去GitHub 后台那个对象还在只是失去了引用。想真正释放只有两条路用git lfs prune清理本地缓存或去 GitHub 后台手动删除 LFS 文件记录Settings - Storage 里可以管理。我项目里就吃过一次亏删了两个旧版镜像包以为没事结果限额还是红的。查看当前用量也简单GitHub 网页端进入仓库的设置页找到 Storage 一栏会列出所有 LFS 对象和总计大小。命令行侧可以用git lfs ls-files --long查看当前跟踪文件列表但真正准确的配额数据还是以网页端为准。5.2 GIT_LFS_SKIP_SMUDGE 与懒拉取LFS 拖慢了 clone 体验是很多人吐槽的重点。尤其是在网络条件不好的情况下一个仓库几百个 LFS 文件每个对象都要到远端重新拉clone 时间能翻好几倍。这时候可以用环境变量跳过 smudge 阶段GIT_LFS_SKIP_SMUDGE1 git clone gitgithub.com:user/repo.git这个命令执行的后果是工作区里所有 LFS 文件变成指针文件而不是真实内容。之后你可以按需找回某个文件git lfs pull --includeassets/models/*.bin只拉取被include规则命中的 LFS 对象其他继续搁置。对于体积巨大但使用频率低的资源目录这个操作方式极其好用团队里可以约定默认跳过下载谁需要资源谁自己git lfs pull。如果你想在.gitconfig里固定这种懒加载策略也不难git config --global filter.lfs.smudge git-lfs smudge --skip -- %f但我不太建议全局这么配容易造成同事拉下来全新仓库发现文件全是几行纯文本误以为代码丢失了。更适合的场合是 CI 构建机器——构建只需要源码不需要设计原稿。5.3 已经删除的文件为什么不释放额度这点再展开说一遍因为太容易踩了。LFS 的存储计数是所有存在的对象总大小不是当前文件总大小。把文件从工作区删除上游的 LFS 对象依然保留。GitHub 提供手动清理入口仓库 Settings - Storage - Delete LFS files。删完之后要注意如果其他分支或历史提交还需要那个对象删除会造成拉取失败。所以清理前先确认这个 LFS 对象是否已经被所有分支和历史不再引用。本地也同理git lfs prune可以清理本地缓存它的策略很保守——只删除没有在任何当前提交、最近提交或未推送的提交中被引用的对象。如果你刚才还在两个分支间切换prune 可能什么都不清理这是安全设计别硬来。6. 我踩过的那些 LFS 坑以及对应的排查思路6.1 拉取时 batch response 错误这是最经典的 LFS 翻车现场git pull时一堆文件能正常拉突然弹出来Error: batch response: This repository is over its data quota.这表示远程 LFS 配额超了。如果是团队自己的仓库去后台看存储详情把没用的对象删掉。如果是 GitHub 免费额度超了要么交钱升级要么在拉取时用GIT_LFS_SKIP_SMUDGE1临时绕过等空间释放后再拉取需要的文件。还有一种非常相似但来源不同的情况Error: batch response: Not found这个通常不是配额问题而是认证问题。如果你用 HTTPS clone 的 GitHub 仓库LFS 的下载请求需要单独的凭据Git 缓存账号时可能只覆盖了普通 Git 请求、没覆盖 LFS 端点的认证。解决办法是在 remote URL 里带上带权限的 token或者切到 SSH 协议。注意 GitHub 的 LFS 服务端和仓库是同一个域名但实际下载请求会重定向到其他 CDN 域名防火墙、代理等网络层面的骚操作也可能导致 LFS 请求失败这种时候优先检查网络环境和凭据。6.2 多平台协作时的 pointer 残留与换行符问题我遇到过的第二个高频坑是git add之后文件没有正确进入 LFS而是把指针文件当普通文本提交了。现象是其他人 pull 下来后发现demo.psd打不开打开一看是一堆纯文本字符以version https://git-lfs.github.com/spec/v1开头。出这个问题的原因基本就是跟踪规则没生效。最常见的是.gitattributes里的通配符写错了、路径写错了或者规则写在.git/info/attributes而不是仓库共享的.gitattributes。排查方法git check-attr filter -- assets/demo.psd正常输出是assets/demo.psd: filter: lfs如果输出unspecified说明规则没匹配上去检查.gitattributes的路径和通配符写法。另外就是 Windows 上换行符转换引发的 OID 不匹配。LFS 向服务器提交的 OID 是根据原始二进制内容计算 SHA-256 得到的如果 Git 在你的机器上执行了换行符转换git add进来的是一个被修改过的文件clean 过滤器拿到的内容和原始文件不一致远端校验就会失败。应对方法对二进制文件确保.gitattributes里加了-text并在仓库根目录统一配置换行符策略。GitHub 官方模板里通常会在.gitattributes开头加一行* textauto然后对每个 LFS 类型单独覆盖-text这是一个比较稳妥的起点。6.3 认证机制HTTPS 与 SSH 的资源下载差异GitHub 对 LFS 的远程交互有个特殊的处理当你用 SSH 协议 clone 一个带 LFS 对象的仓库时Git 先通过 SSH 访问 GitHub 仓库LFS 也会尝试通过 SSH 通道做握手但实际的数据下载/上传仍然走 HTTPS。这意味着即便你的 SSH key 配置得丝滑无比LFS 传输仍然要求 HTTPS 端点的认证可用。所以我在公司内部遇到过一种诡异局面SSH clone xxx 成功仓库代码完整但所有 LFS 文件都是指针空壳拉取报 401。排查了一圈是公司的代理规则对 GitHub HTTPS 敏感SSH 偶尔能通但 HTTPS 流量不稳定。如果你也遇到SSH 一切正常、LFS 不行的情况先单独用 curl 测一下 HTTPS 接口的连通性curl -I https://github.com如果不通那就是网络层对 HTTPS 请求有限制跟 LFS 本身无关。反之如果 HTTPS 能通再看是不是凭据的问题用git config --list | grep credential检查一下有没有配好 GitHub token。6.4 CI 环境与自动化脚本中的 LFS 安装最后提醒一个团队协作中非常容易炸的点CI。本地开发机装了 git-lfs不代表构建服务器也有。GitHub Actions 里actions/checkoutv4默认会执行 LFS checkout因为 checkout action 内部会读到.gitattributes里的 filter 配置并自动调用 git-lfs但前提是 runner 预装了 git-lfs并且执行过一次git lfs install。自建 GitLab CI 或者 Jenkins 里更常见构建脚本一般都要显式处理before_script: - apt-get update apt-get install -y git-lfs - git lfs install如果把 LFS 对象下载放在构建步骤里建议加上git lfs pull而不是依赖 checkout 自动恢复这样报错时定位也更清晰。我自己在写流水线时习惯这么干拉代码时跳过 LFS然后在单独的 stage 里按需拉取资源文件既避免构建镜像蹭蹭变大也不容易踩到配额供应商的带宽坑。Git LFS 这套东西原理说穿了很简单——就是用一个洗洁精瓶子装上洗洁精溶液瓶身还是原来的瓶子配方里的核心活性物被单独存在了仓库外的库房里。但真正用起来坑都藏在细节里.gitattributes的匹配规则、历史迁移的哈希重写、配额计算方式、CI 环境的安装步骤每一个都值得提前想清楚。我个人建议是新仓库从第一笔提交就用 LFS 把资源型文件纳入管理别等仓库膨胀了再做手术老仓库实在要迁移务必按顺序走完备份、通知、迁移、验证、强制推送那几步能少失眠好几个晚上。
