Git 是当今最流行的分布式版本控制系统但它有一个众所周知的软肋——处理大文件。当你的仓库里有几百兆的设计稿、几个 G 的模型权重、或者大量的二进制资源时Git 会变得迟缓、臃肿甚至难以正常使用。Git LFSLarge File Storage就是为了解决这个问题而诞生的。它由 GitHub 在 2015 年开源目前已经成为业界处理大文件版本控制的事实标准。本文将从底层原理出发深入剖析 Git LFS 的工作机制、使用方法和最佳实践。一、为什么 Git 不擅长处理大文件要理解 Git LFS 的价值必须先理解 Git 在处理大文件时的固有问题。1.1 Git 的对象存储模型Git 在底层将所有内容存储为四种对象blob文件内容、tree目录结构、commit提交记录、tag标签。每个对象都通过 SHA-1或新版本的 SHA-256哈希值唯一标识存储在.git/objects/目录中。这意味着每次你修改一个文件并提交Git 都会存储一份新的 blob 对象。Git 通过 packfile 中的 delta 压缩在一定程度上减少冗余但对于二进制文件——尤其是已经压缩过的文件如 PNG、MP4、ZIP——delta 压缩几乎完全失效。1.2 历史不可变带来的累积效应Git 的核心设计哲学之一是历史不可变。这意味着即使你在新提交中删除了一个 500MB 的文件它仍然永远存在于.git目录中。当你git clone时Git 默认会下载完整历史包括所有曾经存在过的大文件版本。一个真实的例子某游戏团队的仓库工作目录只有 2GB但.git目录达到了 80GB——因为他们多次替换过纹理资源文件。1.3 性能瓶颈大文件会从多个维度拖累 Gitgit status需要计算工作目录中所有文件的哈希git diff对二进制文件意义不大但仍会消耗资源git clone需要下载完整历史git gc在打包大文件时会消耗大量内存更糟糕的是由于 Git 的设计仓库一旦胖了就很难瘦下来。任何改写历史的操作filter-branch、filter-repo都会让所有协作者的本地仓库失效。二、Git LFS 的核心思想Git LFS 的解决思路非常优雅让大文件本身离开 Git 仓库但在 Git 中保留对它们的引用。2.1 指针文件Pointer FileGit LFS 的核心是一个叫指针文件的小文本文件。当你将一个文件交给 LFS 管理时Git 仓库里实际存储的不再是原文件内容而是一个类似这样的文本version https://git-lfs.github.com/spec/v1 oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393 size 12345这个指针文件只有寥寥几行记录了LFS 协议版本真实文件内容的 SHA-256 哈希OID Object ID文件大小字节真正的文件内容存储在 LFS 服务器上通过这个 OID 进行寻址。2.2 智能过滤器clean 和 smudgeGit LFS 利用了 Git 的一个高级特性——filter driver。Git 允许你在文件进入仓库staging和检出到工作目录checkout时插入自定义过滤器。clean 过滤器当文件被git add时触发。LFS 将真实文件内容上传到 LFS 存储然后在 Git 仓库中只保存指针文件。smudge 过滤器当文件被git checkout时触发。LFS 读取指针文件从 LFS 存储下载真实内容替换到工作目录。这个机制的精妙之处在于对开发者完全透明。你像平常一样git add、git commit、git push但底层实际上是 LFS 在搬运大文件。2.3 工作流示意开发者本地 Git 仓库 LFS 服务器 ───────── ──────── ────────── 工作目录 (大文件) │ │ git add ──[clean filter]──→ 指针文件 │ │ │ │ git push │ ↓ │ 远程 Git 仓库 │ │ └────────── 大文件内容 ─────────────┴───────→ LFS 对象存储 另一开发者: 远程 Git 仓库 ── git pull ──→ 指针文件 │ │ [smudge filter] ↓ 从 LFS 拉取大文件 ──→ 工作目录2.4 LFS 的传输协议Git LFS 使用一套独立的 HTTP API叫做Batch API来上传下载文件不走 Git 的 smart HTTP 协议。流程大致是客户端发送一批 OID 给 LFS 服务器POST /objects/batch服务器返回每个对象的上传/下载 URL通常是预签名的 S3 URL客户端直接与对象存储交互绕过 Git 服务器这种设计让 LFS 服务器本身成为一个轻量级的协调者真正的大流量传输交给专门的对象存储扩展性极佳。三、安装与初始化3.1 安装Git LFS 是 Git 的扩展需要单独安装# macOSbrewinstallgit-lfs# Ubuntu/Debiansudoaptinstallgit-lfs# Windows# 通常 Git for Windows 已自带或从 https://git-lfs.com 下载# CentOS/RHELsudoyuminstallgit-lfs安装完成后需要执行一次全局初始化把 LFS 的 filter 配置写到全局 Git 配置中gitlfsinstall这会在~/.gitconfig添加[filter lfs] clean git-lfs clean -- %f smudge git-lfs smudge -- %f process git-lfs filter-process required true3.2 在仓库中启用进入你的仓库告诉 LFS 哪些文件需要交给它管理gitlfs track*.psdgitlfs track*.zipgitlfs trackassets/models/*.glbgit lfs track实际上是在编辑.gitattributes文件*.psd filterlfs difflfs mergelfs -text *.zip filterlfs difflfs mergelfs -text assets/models/*.glb filterlfs difflfs mergelfs -text重要.gitattributes必须被提交到仓库否则其他协作者拉下来后不知道哪些文件应当走 LFS。gitadd.gitattributesgitcommit-mchore: track large assets via LFS之后正常使用git add、git commit、git push即可。第一次 push 时LFS 会先把大文件上传到 LFS 服务器再 push Git 提交。四、核心命令详解4.1git lfs track与git lfs untrack管理跟踪规则gitlfs track# 列出当前所有跟踪规则gitlfs track*.bin# 添加跟踪规则gitlfs untrack*.bin# 移除跟踪规则不会影响已提交的文件注意untrack只是从.gitattributes移除规则。已经被 LFS 管理的历史文件依然以指针形式存在于历史中。4.2git lfs ls-files查看当前分支被 LFS 管理的文件$gitlfs ls-files 4d7a214614 * assets/hero.psd 9f8e3c2a18 * dist/release.zip加上-s显示大小加上--all查看所有历史中的 LFS 文件。4.3git lfs migrate这是迁移现有仓库到 LFS 时最重要的命令。它会改写历史把符合条件的大文件从 Git 历史中提取到 LFS# 预览将所有 *.psd 迁移到 LFS仅当前分支gitlfs migrateimport--include*.psd# 迁移所有大于 50MB 的文件作用于所有分支和标签gitlfs migrateimport--above50MB--everything# 反向操作把 LFS 文件迁回 Git如果你后悔了gitlfs migrateexport--include*.psd警告migrate import会改写 Git 历史所有 commit hash 都会变。这意味着所有协作者必须重新 clone否则会一片混乱。在共享仓库上做这个操作前一定要协调好团队。4.4git lfs fetch/pull/pushgit lfs fetch下载 LFS 对象但不检出到工作目录git lfs pull相当于git pullgit lfs fetch checkoutgit lfs push推送 LFS 对象通常git push已自动触发加--all可以获取所有历史中的 LFS 对象加--recent仅获取最近的。4.5git lfs prune清理本地 LFS 缓存中不再需要的对象gitlfs prune# 清理本地未引用的对象gitlfs prune --dry-run# 预览将要删除的内容gitlfs prune --verify-remote# 删除前验证远程存有副本LFS 的本地缓存在.git/lfs/objects/中可能会越积越大定期 prune 是必要的。4.6git lfs fsck检查 LFS 对象的完整性哈希校验gitlfsfsck4.7git lfs lock/unlock文件锁定下文详细介绍。五、文件锁定处理不可合并的二进制文件5.1 为什么需要锁定文本文件可以三方合并但二进制文件不能。如果两个人同时修改同一个 PSD 文件并各自提交合并时其中一个人的工作必定丢失——Git 没法智能地合并两张图。LFS 提供了文件锁定机制当你打算修改某个二进制文件时先把它锁住告诉团队我正在动这个文件。5.2 使用方法首先在.gitattributes标记可锁定的文件*.psd filterlfs difflfs mergelfs -text lockablelockable属性会让这些文件在工作目录中默认是只读的chmod -w强制开发者锁定后才能编辑。gitlfs lock assets/hero.psd# 加锁文件变为可写# ... 编辑、提交、推送 ...gitlfs unlock assets/hero.psd# 解锁gitlfs locks# 查看当前所有锁gitlfs unlock--forcefile.psd# 强制解锁管理员特权5.3 强制服务端验证为了让锁真正生效防止有人无视锁可以开启服务端验证gitconfig lfs.https://github.com/owner/repo.git/info/lfs.locksverifytrue开启后push 时如果发现你修改了别人锁定的文件服务器会拒绝。六、迁移策略把已有仓库改造为 LFS这是 LFS 使用中最容易踩坑的环节。常见场景是仓库里已经有大量大文件现在想用 LFS 管理。6.1 新文件用 LFS最简单的情况——只把未来新增的大文件交给 LFSgitlfs track*.psdgitadd.gitattributesgitcommit-mchore: enable LFS for psd files这种方式不改写历史零风险但仓库的历史包袱依然存在。6.2 改写历史彻底瘦身如果你想让仓库真正瘦下来就必须改写历史# 备份备份备份gitclone--mirrorgitgithub.com:org/repo.git repo-backup# 进入工作仓库cdrepo# 迁移把历史中所有 *.psd 提取到 LFSgitlfs migrateimport--include*.psd--everything# 强制推送会改写远程历史需要管理员权限gitpush--force--allgitpush--force--tags执行后仓库的.git目录会显著缩小但记住所有协作者必须重新 clone。他们本地的 commit hash 全变了。PR/MR 可能失效。基于旧 hash 的 Pull Request 需要重建。CI 缓存可能要清理。GitHub/GitLab 的 Releases、Issues 引用 commit 的地方仍指向旧 hash会变成missing。因此改写历史是核武器能不用尽量不用。6.3 折中方案BFG Repo-CleanerBFG 是一个独立工具专门用来从 Git 历史中删除大文件或敏感数据。它比git filter-branch快很多。常见用法bfg --strip-blobs-bigger-than 50M repo.git注意 BFG 是把大文件直接从历史中抹掉不是迁移到 LFS。如果你想保留这些文件应该用git lfs migrate import。七、服务端与存储后端7.1 主流托管平台的支持平台免费配额备注GitHub1 GB 存储1 GB/月 带宽超出需购买 Data Pack5 美元/50GBGitLab取决于实例和套餐Self-host 没有限制Bitbucket1 GB / 仓库流量另计Gitea自托管无硬性限制需要配置后端需要特别注意LFS 流量在大型团队中会很快耗尽。每次 CI 跑测试都可能拉一遍大文件。务必关注配额监控。7.2 自建 LFS 服务器LFS 协议公开有许多开源实现lfs-test-server官方参考实现仅限测试用Gitea和Gitea LFS开箱即用Gitaly GitLab企业级方案Harbor LFS Server轻量RudolfsRust 实现性能好7.3 对象存储后端LFS 服务器通常只是协调器真实文件存到对象存储里。常见后端AWS S3业界标准MinIO自托管 S3 兼容存储Azure Blob StorageGoogle Cloud Storage本地文件系统仅小规模或测试配置思路通常是LFS 服务器收到上传请求后生成预签名 URL 返回给客户端客户端直接 PUT 到对象存储。下载同理。这种模式让 LFS 服务器自身负载极轻。八、性能与成本优化8.1 部分检出节省克隆时间如果你只关心当前版本的大文件不需要历史可以这样做# 克隆时跳过 LFS 下载GIT_LFS_SKIP_SMUDGE1gitclone gitgithub.com:org/repo.gitcdrepo# 只拉取当前 checkout 需要的 LFS 对象gitlfs pull或者结合 Git 的 partial clonegitclone--filterblob:none gitgithub.com:org/repo.git8.2 包含/排除模式通过lfs.fetchinclude和lfs.fetchexclude控制只下载部分 LFS 文件gitconfig lfs.fetchincludeassets/models/*gitconfig lfs.fetchexclude*.psd,*.mov适用于CI 只需要部分资源或者前端开发者不需要拉服务端用的模型文件。8.3 并发数调整LFS 默认并发 8 个传输gitconfig lfs.concurrenttransfers16提升并发可以加快传输但要注意服务器和带宽限制。8.4 标准 IO 与文件锁对于超大仓库可以开启lfs.standalonetransferagent自定义传输代理也可以把.git/lfs目录放到独立 SSD 上提升 IO 性能。九、常见陷阱与排查9.1 忘记安装 LFS 的协作者某个同事 clone 后看到一堆几行文本的 PSD 文件——这是因为他没装 LFS。指针文件被当作普通文本检出了。解决让他执行git lfs install然后git lfs pull。9.2.gitattributes没有提交最常见的为什么我的 LFS 没生效问题。.gitattributes必须在仓库中且必须早于或同时于大文件的添加。9.3 已经提交了非 LFS 的大文件如果你忘记先git lfs track直接git add了大文件那它已经进入 Git 仓库本体。此时git lfs track不会追溯。需要# 撤销这次提交重新来过gitreset HEAD~1gitlfs track*.bingitadd.gitattributesgitaddfile.bingitcommit-m...如果已经 push 了要么用git lfs migrate import改写历史要么接受这次的包袱。9.4 GitHub 的 100MB 硬限制GitHub 的 Git 仓库有 100MB 的单文件硬限制不是 LFS。如果你忘记 track 就 push 了一个 150MB 的文件GitHub 会直接拒绝。这其实是个保护机制提醒你该用 LFS 了。9.5 LFS rate limitGitHub 对 LFS 有速率限制CI 频繁拉取可能触发。解决方案在 CI 中缓存.git/lfs/objects目录用 GitHub Actions 的lfs: truecache: true减少不必要的 fetch9.6 合并冲突中的指针文件合并两个分支时如果两边都修改了同一个 LFS 文件会在指针文件层面产生冲突。需要手动选择保留哪个 OID或者重新 add 一份新内容。这种冲突通常意味着工作流问题——这就是文件锁定要解决的场景。十、与其他方案的对比10.1 git-annexgit-annex 是更早、更强大的方案。它支持多种后端S3、本地、WebDAV…、智能去重、跨仓库分布式存储。但学习曲线陡峭工作流和 Git 差异较大。对比LFS 简单透明git-annex 灵活强大。多数团队选 LFS。10.2 DVCData Version ControlDVC 是机器学习领域的版本控制工具专注于数据集和模型权重。它的设计哲学是与 Git 解耦——大文件元信息存在 Git但内容由 DVC 独立管理支持数据流水线、实验跟踪等高级功能。对比做 ML 推荐 DVC或 DVC LFS 混合普通项目用 LFS。10.3 Perforce / Helix Core商业方案游戏行业标准。从设计上就是中心化 大文件友好支持精细的文件锁、partial sync、流式工作区。性能极强但价格不菲。对比3A 游戏团队倾向 Perforce独立游戏和开源项目用 LFS。10.4 Git submodule把大文件单独放到一个仓库里主仓库通过 submodule 引用。优点是零依赖缺点是 submodule 本身的管理复杂度高且不解决那个仓库依然在变胖的问题。对比submodule 适合代码模块化不适合大文件管理。十一、最佳实践清单落地 Git LFS 时可以参照以下清单在项目最早期就启用 LFS。事后迁移代价高昂。维护好.gitattributes。把它当成项目配置的一部分严肃对待。定期审计。用git lfs ls-files -s看看哪些文件占用大是否合理。配额监控。把 LFS 存储和带宽用量纳入团队监控指标。CI 优化。能不拉 LFS 就不拉能缓存就缓存。培训。让每个新人都执行git lfs install并理解指针文件的概念。谨慎改写历史。git lfs migrate import是核武器团队必须协调。可锁定的二进制文件加lockable。强制只读 锁定流程避免合并悲剧。备份策略。LFS 对象不在 Git 仓库本体里备份方案要单独考虑。关注 OID 哈希。当前是 SHA-256如果你做镜像/同步要保证两端一致。十二、一些不那么明显的细节12.1 LFS 不是真的快很多人误以为 LFS 让大文件传输变快了。其实总传输量没变只是把传输从 Git 协议挪到了独立通道避免拖慢 Git 操作本身。git status、git log之类的元数据操作确实快了很多。12.2 LFS 的对象去重LFS 用 SHA-256 内容寻址相同内容的文件只会上传/存储一次。即使你在两个仓库里都有同一份大文件服务端也只存一份取决于实现。12.3 LFS 文件不能是符号链接某些场景下你可能想让 LFS 文件是软链接但默认 LFS 会把符号链接当成普通小文件处理。如果非要这么做需要显式配置或自定义 transfer adapter。12.4 git diff 对 LFS 文件的处理默认情况下git diff对 LFS 文件显示Binary files differ。可以注册自定义 diff driver 比如对图片用 ImageMagick 的compare对 PSD 用psd-tools提升评审体验。12.5 历史中存在的 LFS 对象不会自动回收哪怕你git lfs untrack并删除了文件已经在历史中的指针文件依然指向 LFS 服务器上的对象。这些对象不会被自动回收。GitHub 等平台有git lfs prune类似的服务端命令但通常需要管理员手动操作。结语Git LFS 不是一个完美的方案但它是一个简单、透明、被广泛接受的方案。它的核心创新——用指针文件 filter driver 替代真实内容——既保留了 Git 的工作流又解决了大文件的存储难题。理解 LFS 的关键是理解它做了什么和没做什么它把大文件挪出了 Git 对象数据库 ✓它让 Git 操作变快 ✓它提供了文件锁来弥补二进制文件不可合并的缺陷 ✓它没有改变 Git 的本质——历史依然不可变分布式依然成立它没有让传输变快——总流量不变它没有自动解决你历史里已经存在的大文件问题掌握了这些边界再结合你项目的具体场景团队规模、资源类型、CI/CD 复杂度、托管平台你就能做出合理的技术决策。对于大多数有大文件需求的团队Git LFS 是一个稳妥的起点如果将来需求复杂化再考虑 DVC、git-annex 或商业方案也不迟。
深入理解 Git LFS：大文件版本控制的完整指南
发布时间：2026/5/19 9:59:04
Git 是当今最流行的分布式版本控制系统但它有一个众所周知的软肋——处理大文件。当你的仓库里有几百兆的设计稿、几个 G 的模型权重、或者大量的二进制资源时Git 会变得迟缓、臃肿甚至难以正常使用。Git LFSLarge File Storage就是为了解决这个问题而诞生的。它由 GitHub 在 2015 年开源目前已经成为业界处理大文件版本控制的事实标准。本文将从底层原理出发深入剖析 Git LFS 的工作机制、使用方法和最佳实践。一、为什么 Git 不擅长处理大文件要理解 Git LFS 的价值必须先理解 Git 在处理大文件时的固有问题。1.1 Git 的对象存储模型Git 在底层将所有内容存储为四种对象blob文件内容、tree目录结构、commit提交记录、tag标签。每个对象都通过 SHA-1或新版本的 SHA-256哈希值唯一标识存储在.git/objects/目录中。这意味着每次你修改一个文件并提交Git 都会存储一份新的 blob 对象。Git 通过 packfile 中的 delta 压缩在一定程度上减少冗余但对于二进制文件——尤其是已经压缩过的文件如 PNG、MP4、ZIP——delta 压缩几乎完全失效。1.2 历史不可变带来的累积效应Git 的核心设计哲学之一是历史不可变。这意味着即使你在新提交中删除了一个 500MB 的文件它仍然永远存在于.git目录中。当你git clone时Git 默认会下载完整历史包括所有曾经存在过的大文件版本。一个真实的例子某游戏团队的仓库工作目录只有 2GB但.git目录达到了 80GB——因为他们多次替换过纹理资源文件。1.3 性能瓶颈大文件会从多个维度拖累 Gitgit status需要计算工作目录中所有文件的哈希git diff对二进制文件意义不大但仍会消耗资源git clone需要下载完整历史git gc在打包大文件时会消耗大量内存更糟糕的是由于 Git 的设计仓库一旦胖了就很难瘦下来。任何改写历史的操作filter-branch、filter-repo都会让所有协作者的本地仓库失效。二、Git LFS 的核心思想Git LFS 的解决思路非常优雅让大文件本身离开 Git 仓库但在 Git 中保留对它们的引用。2.1 指针文件Pointer FileGit LFS 的核心是一个叫指针文件的小文本文件。当你将一个文件交给 LFS 管理时Git 仓库里实际存储的不再是原文件内容而是一个类似这样的文本version https://git-lfs.github.com/spec/v1 oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393 size 12345这个指针文件只有寥寥几行记录了LFS 协议版本真实文件内容的 SHA-256 哈希OID Object ID文件大小字节真正的文件内容存储在 LFS 服务器上通过这个 OID 进行寻址。2.2 智能过滤器clean 和 smudgeGit LFS 利用了 Git 的一个高级特性——filter driver。Git 允许你在文件进入仓库staging和检出到工作目录checkout时插入自定义过滤器。clean 过滤器当文件被git add时触发。LFS 将真实文件内容上传到 LFS 存储然后在 Git 仓库中只保存指针文件。smudge 过滤器当文件被git checkout时触发。LFS 读取指针文件从 LFS 存储下载真实内容替换到工作目录。这个机制的精妙之处在于对开发者完全透明。你像平常一样git add、git commit、git push但底层实际上是 LFS 在搬运大文件。2.3 工作流示意开发者本地 Git 仓库 LFS 服务器 ───────── ──────── ────────── 工作目录 (大文件) │ │ git add ──[clean filter]──→ 指针文件 │ │ │ │ git push │ ↓ │ 远程 Git 仓库 │ │ └────────── 大文件内容 ─────────────┴───────→ LFS 对象存储 另一开发者: 远程 Git 仓库 ── git pull ──→ 指针文件 │ │ [smudge filter] ↓ 从 LFS 拉取大文件 ──→ 工作目录2.4 LFS 的传输协议Git LFS 使用一套独立的 HTTP API叫做Batch API来上传下载文件不走 Git 的 smart HTTP 协议。流程大致是客户端发送一批 OID 给 LFS 服务器POST /objects/batch服务器返回每个对象的上传/下载 URL通常是预签名的 S3 URL客户端直接与对象存储交互绕过 Git 服务器这种设计让 LFS 服务器本身成为一个轻量级的协调者真正的大流量传输交给专门的对象存储扩展性极佳。三、安装与初始化3.1 安装Git LFS 是 Git 的扩展需要单独安装# macOSbrewinstallgit-lfs# Ubuntu/Debiansudoaptinstallgit-lfs# Windows# 通常 Git for Windows 已自带或从 https://git-lfs.com 下载# CentOS/RHELsudoyuminstallgit-lfs安装完成后需要执行一次全局初始化把 LFS 的 filter 配置写到全局 Git 配置中gitlfsinstall这会在~/.gitconfig添加[filter lfs] clean git-lfs clean -- %f smudge git-lfs smudge -- %f process git-lfs filter-process required true3.2 在仓库中启用进入你的仓库告诉 LFS 哪些文件需要交给它管理gitlfs track*.psdgitlfs track*.zipgitlfs trackassets/models/*.glbgit lfs track实际上是在编辑.gitattributes文件*.psd filterlfs difflfs mergelfs -text *.zip filterlfs difflfs mergelfs -text assets/models/*.glb filterlfs difflfs mergelfs -text重要.gitattributes必须被提交到仓库否则其他协作者拉下来后不知道哪些文件应当走 LFS。gitadd.gitattributesgitcommit-mchore: track large assets via LFS之后正常使用git add、git commit、git push即可。第一次 push 时LFS 会先把大文件上传到 LFS 服务器再 push Git 提交。四、核心命令详解4.1git lfs track与git lfs untrack管理跟踪规则gitlfs track# 列出当前所有跟踪规则gitlfs track*.bin# 添加跟踪规则gitlfs untrack*.bin# 移除跟踪规则不会影响已提交的文件注意untrack只是从.gitattributes移除规则。已经被 LFS 管理的历史文件依然以指针形式存在于历史中。4.2git lfs ls-files查看当前分支被 LFS 管理的文件$gitlfs ls-files 4d7a214614 * assets/hero.psd 9f8e3c2a18 * dist/release.zip加上-s显示大小加上--all查看所有历史中的 LFS 文件。4.3git lfs migrate这是迁移现有仓库到 LFS 时最重要的命令。它会改写历史把符合条件的大文件从 Git 历史中提取到 LFS# 预览将所有 *.psd 迁移到 LFS仅当前分支gitlfs migrateimport--include*.psd# 迁移所有大于 50MB 的文件作用于所有分支和标签gitlfs migrateimport--above50MB--everything# 反向操作把 LFS 文件迁回 Git如果你后悔了gitlfs migrateexport--include*.psd警告migrate import会改写 Git 历史所有 commit hash 都会变。这意味着所有协作者必须重新 clone否则会一片混乱。在共享仓库上做这个操作前一定要协调好团队。4.4git lfs fetch/pull/pushgit lfs fetch下载 LFS 对象但不检出到工作目录git lfs pull相当于git pullgit lfs fetch checkoutgit lfs push推送 LFS 对象通常git push已自动触发加--all可以获取所有历史中的 LFS 对象加--recent仅获取最近的。4.5git lfs prune清理本地 LFS 缓存中不再需要的对象gitlfs prune# 清理本地未引用的对象gitlfs prune --dry-run# 预览将要删除的内容gitlfs prune --verify-remote# 删除前验证远程存有副本LFS 的本地缓存在.git/lfs/objects/中可能会越积越大定期 prune 是必要的。4.6git lfs fsck检查 LFS 对象的完整性哈希校验gitlfsfsck4.7git lfs lock/unlock文件锁定下文详细介绍。五、文件锁定处理不可合并的二进制文件5.1 为什么需要锁定文本文件可以三方合并但二进制文件不能。如果两个人同时修改同一个 PSD 文件并各自提交合并时其中一个人的工作必定丢失——Git 没法智能地合并两张图。LFS 提供了文件锁定机制当你打算修改某个二进制文件时先把它锁住告诉团队我正在动这个文件。5.2 使用方法首先在.gitattributes标记可锁定的文件*.psd filterlfs difflfs mergelfs -text lockablelockable属性会让这些文件在工作目录中默认是只读的chmod -w强制开发者锁定后才能编辑。gitlfs lock assets/hero.psd# 加锁文件变为可写# ... 编辑、提交、推送 ...gitlfs unlock assets/hero.psd# 解锁gitlfs locks# 查看当前所有锁gitlfs unlock--forcefile.psd# 强制解锁管理员特权5.3 强制服务端验证为了让锁真正生效防止有人无视锁可以开启服务端验证gitconfig lfs.https://github.com/owner/repo.git/info/lfs.locksverifytrue开启后push 时如果发现你修改了别人锁定的文件服务器会拒绝。六、迁移策略把已有仓库改造为 LFS这是 LFS 使用中最容易踩坑的环节。常见场景是仓库里已经有大量大文件现在想用 LFS 管理。6.1 新文件用 LFS最简单的情况——只把未来新增的大文件交给 LFSgitlfs track*.psdgitadd.gitattributesgitcommit-mchore: enable LFS for psd files这种方式不改写历史零风险但仓库的历史包袱依然存在。6.2 改写历史彻底瘦身如果你想让仓库真正瘦下来就必须改写历史# 备份备份备份gitclone--mirrorgitgithub.com:org/repo.git repo-backup# 进入工作仓库cdrepo# 迁移把历史中所有 *.psd 提取到 LFSgitlfs migrateimport--include*.psd--everything# 强制推送会改写远程历史需要管理员权限gitpush--force--allgitpush--force--tags执行后仓库的.git目录会显著缩小但记住所有协作者必须重新 clone。他们本地的 commit hash 全变了。PR/MR 可能失效。基于旧 hash 的 Pull Request 需要重建。CI 缓存可能要清理。GitHub/GitLab 的 Releases、Issues 引用 commit 的地方仍指向旧 hash会变成missing。因此改写历史是核武器能不用尽量不用。6.3 折中方案BFG Repo-CleanerBFG 是一个独立工具专门用来从 Git 历史中删除大文件或敏感数据。它比git filter-branch快很多。常见用法bfg --strip-blobs-bigger-than 50M repo.git注意 BFG 是把大文件直接从历史中抹掉不是迁移到 LFS。如果你想保留这些文件应该用git lfs migrate import。七、服务端与存储后端7.1 主流托管平台的支持平台免费配额备注GitHub1 GB 存储1 GB/月 带宽超出需购买 Data Pack5 美元/50GBGitLab取决于实例和套餐Self-host 没有限制Bitbucket1 GB / 仓库流量另计Gitea自托管无硬性限制需要配置后端需要特别注意LFS 流量在大型团队中会很快耗尽。每次 CI 跑测试都可能拉一遍大文件。务必关注配额监控。7.2 自建 LFS 服务器LFS 协议公开有许多开源实现lfs-test-server官方参考实现仅限测试用Gitea和Gitea LFS开箱即用Gitaly GitLab企业级方案Harbor LFS Server轻量RudolfsRust 实现性能好7.3 对象存储后端LFS 服务器通常只是协调器真实文件存到对象存储里。常见后端AWS S3业界标准MinIO自托管 S3 兼容存储Azure Blob StorageGoogle Cloud Storage本地文件系统仅小规模或测试配置思路通常是LFS 服务器收到上传请求后生成预签名 URL 返回给客户端客户端直接 PUT 到对象存储。下载同理。这种模式让 LFS 服务器自身负载极轻。八、性能与成本优化8.1 部分检出节省克隆时间如果你只关心当前版本的大文件不需要历史可以这样做# 克隆时跳过 LFS 下载GIT_LFS_SKIP_SMUDGE1gitclone gitgithub.com:org/repo.gitcdrepo# 只拉取当前 checkout 需要的 LFS 对象gitlfs pull或者结合 Git 的 partial clonegitclone--filterblob:none gitgithub.com:org/repo.git8.2 包含/排除模式通过lfs.fetchinclude和lfs.fetchexclude控制只下载部分 LFS 文件gitconfig lfs.fetchincludeassets/models/*gitconfig lfs.fetchexclude*.psd,*.mov适用于CI 只需要部分资源或者前端开发者不需要拉服务端用的模型文件。8.3 并发数调整LFS 默认并发 8 个传输gitconfig lfs.concurrenttransfers16提升并发可以加快传输但要注意服务器和带宽限制。8.4 标准 IO 与文件锁对于超大仓库可以开启lfs.standalonetransferagent自定义传输代理也可以把.git/lfs目录放到独立 SSD 上提升 IO 性能。九、常见陷阱与排查9.1 忘记安装 LFS 的协作者某个同事 clone 后看到一堆几行文本的 PSD 文件——这是因为他没装 LFS。指针文件被当作普通文本检出了。解决让他执行git lfs install然后git lfs pull。9.2.gitattributes没有提交最常见的为什么我的 LFS 没生效问题。.gitattributes必须在仓库中且必须早于或同时于大文件的添加。9.3 已经提交了非 LFS 的大文件如果你忘记先git lfs track直接git add了大文件那它已经进入 Git 仓库本体。此时git lfs track不会追溯。需要# 撤销这次提交重新来过gitreset HEAD~1gitlfs track*.bingitadd.gitattributesgitaddfile.bingitcommit-m...如果已经 push 了要么用git lfs migrate import改写历史要么接受这次的包袱。9.4 GitHub 的 100MB 硬限制GitHub 的 Git 仓库有 100MB 的单文件硬限制不是 LFS。如果你忘记 track 就 push 了一个 150MB 的文件GitHub 会直接拒绝。这其实是个保护机制提醒你该用 LFS 了。9.5 LFS rate limitGitHub 对 LFS 有速率限制CI 频繁拉取可能触发。解决方案在 CI 中缓存.git/lfs/objects目录用 GitHub Actions 的lfs: truecache: true减少不必要的 fetch9.6 合并冲突中的指针文件合并两个分支时如果两边都修改了同一个 LFS 文件会在指针文件层面产生冲突。需要手动选择保留哪个 OID或者重新 add 一份新内容。这种冲突通常意味着工作流问题——这就是文件锁定要解决的场景。十、与其他方案的对比10.1 git-annexgit-annex 是更早、更强大的方案。它支持多种后端S3、本地、WebDAV…、智能去重、跨仓库分布式存储。但学习曲线陡峭工作流和 Git 差异较大。对比LFS 简单透明git-annex 灵活强大。多数团队选 LFS。10.2 DVCData Version ControlDVC 是机器学习领域的版本控制工具专注于数据集和模型权重。它的设计哲学是与 Git 解耦——大文件元信息存在 Git但内容由 DVC 独立管理支持数据流水线、实验跟踪等高级功能。对比做 ML 推荐 DVC或 DVC LFS 混合普通项目用 LFS。10.3 Perforce / Helix Core商业方案游戏行业标准。从设计上就是中心化 大文件友好支持精细的文件锁、partial sync、流式工作区。性能极强但价格不菲。对比3A 游戏团队倾向 Perforce独立游戏和开源项目用 LFS。10.4 Git submodule把大文件单独放到一个仓库里主仓库通过 submodule 引用。优点是零依赖缺点是 submodule 本身的管理复杂度高且不解决那个仓库依然在变胖的问题。对比submodule 适合代码模块化不适合大文件管理。十一、最佳实践清单落地 Git LFS 时可以参照以下清单在项目最早期就启用 LFS。事后迁移代价高昂。维护好.gitattributes。把它当成项目配置的一部分严肃对待。定期审计。用git lfs ls-files -s看看哪些文件占用大是否合理。配额监控。把 LFS 存储和带宽用量纳入团队监控指标。CI 优化。能不拉 LFS 就不拉能缓存就缓存。培训。让每个新人都执行git lfs install并理解指针文件的概念。谨慎改写历史。git lfs migrate import是核武器团队必须协调。可锁定的二进制文件加lockable。强制只读 锁定流程避免合并悲剧。备份策略。LFS 对象不在 Git 仓库本体里备份方案要单独考虑。关注 OID 哈希。当前是 SHA-256如果你做镜像/同步要保证两端一致。十二、一些不那么明显的细节12.1 LFS 不是真的快很多人误以为 LFS 让大文件传输变快了。其实总传输量没变只是把传输从 Git 协议挪到了独立通道避免拖慢 Git 操作本身。git status、git log之类的元数据操作确实快了很多。12.2 LFS 的对象去重LFS 用 SHA-256 内容寻址相同内容的文件只会上传/存储一次。即使你在两个仓库里都有同一份大文件服务端也只存一份取决于实现。12.3 LFS 文件不能是符号链接某些场景下你可能想让 LFS 文件是软链接但默认 LFS 会把符号链接当成普通小文件处理。如果非要这么做需要显式配置或自定义 transfer adapter。12.4 git diff 对 LFS 文件的处理默认情况下git diff对 LFS 文件显示Binary files differ。可以注册自定义 diff driver 比如对图片用 ImageMagick 的compare对 PSD 用psd-tools提升评审体验。12.5 历史中存在的 LFS 对象不会自动回收哪怕你git lfs untrack并删除了文件已经在历史中的指针文件依然指向 LFS 服务器上的对象。这些对象不会被自动回收。GitHub 等平台有git lfs prune类似的服务端命令但通常需要管理员手动操作。结语Git LFS 不是一个完美的方案但它是一个简单、透明、被广泛接受的方案。它的核心创新——用指针文件 filter driver 替代真实内容——既保留了 Git 的工作流又解决了大文件的存储难题。理解 LFS 的关键是理解它做了什么和没做什么它把大文件挪出了 Git 对象数据库 ✓它让 Git 操作变快 ✓它提供了文件锁来弥补二进制文件不可合并的缺陷 ✓它没有改变 Git 的本质——历史依然不可变分布式依然成立它没有让传输变快——总流量不变它没有自动解决你历史里已经存在的大文件问题掌握了这些边界再结合你项目的具体场景团队规模、资源类型、CI/CD 复杂度、托管平台你就能做出合理的技术决策。对于大多数有大文件需求的团队Git LFS 是一个稳妥的起点如果将来需求复杂化再考虑 DVC、git-annex 或商业方案也不迟。
![Hyperf的#[Aspect]的庖丁解牛](http://pic.xiahunao.cn/yaotu/Hyperf的#[Aspect]的庖丁解牛)
