Git LFS 管理大文件

Git 天生不擅长存大文件。一个 100MB 的模型文件提交进去，从此每次 clone 都要拖这 100MB，哪怕后面已经删掉了——因为它永久留在了历史里。

Git LFS（Large File Storage）的思路是：仓库里只存一个指针文件，真身放到 LFS 服务上。

一、安装与初始化

git lfs install          # 全局装 hook，只需一次
git lfs track "*.psd"    # 指定要跟踪的类型
git add .gitattributes

.gitattributes 会产生一行：

*.psd filter=lfs diff=lfs merge=lfs -text

这行必须提交，否则别人拉下来还是按普通文件处理。

和普通文件没区别：

git add model.psd
git commit -m "art: 新增设计稿"
git push

之后就能看到：

git lfs ls-files        # 列出被 LFS 管理的文件
git lfs status          # 当前 LFS 状态

文件已经在历史里了，需要重写历史：

git lfs migrate import --include="*.psd,*.zip" --everything
git push --force-with-lease --all

⚠️ 这会重写所有提交的 hash，所有协作者必须重新 clone。做之前务必通知全员。

只有一两个文件比较小的话，更省事的做法是直接删掉历史里的它（git filter-repo），重新以 LFS 提交。

git clone https://xxx/art.git                 # 不拉 LFS 内容，只有指针
git lfs pull                                  # 补拉真身

只想拿部分文件：

GIT_LFS_SKIP_SMUDGE=1 git clone https://xxx/art.git
git lfs pull --include="assets/ui/*.png"

大仓库做 CI 时这个技巧很关键——能省掉几分钟的下载。

this exceeds GitHub's file size limit：还没配 .gitattributes 就提交了大文件，先把该类型加进 LFS，再 git add --renormalize . 重加。

smudge filter lfs failed：本地没装 lfs，git lfs install 后 git lfs pull。

batch response: Authentication required：LFS 走独立的鉴权端点，CI 里要把 token 传对（部分平台需要单独的 LFS 凭证）。

推上去但别人看不到内容：确认 .gitattributes 已经提交，且对方执行了 git lfs pull。

GitHub 免费额度是 1GB 存储 + 1GB/月流量，超了要付费；CNB 等平台的制品库对这类需求更宽松。

如果文件是构建产物、数据集、依赖包，其实更该放制品库或对象存储，仓库里只留下载脚本或校验和。LFS 适合的是"和源码一起版本化、体积中等（几 MB 到几百 MB）"的资源。