Git 完全指南 / 14 - Git LFS：大文件管理、迁移、存储限制
第十四章：Git LFS（Large File Storage）
Git LFS 解决了 Git 处理大文件的痛点，让二进制文件和大型资源也能优雅管理。
14.1 LFS 概述
Git LFS 是 Git 的扩展，用于管理大型文件。它用指针文件替代大文件的实际内容，将大文件存储在单独的服务器上。
传统方式：
.git/objects/ → 存储完整文件内容（每次修改都存储完整副本）
Git LFS：
.git/objects/ → 存储指针文件（几百字节）
LFS 服务器 → 存储实际大文件（去重存储）
指针文件示例
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345678
| 字段 | 说明 |
|---|
version | LFS 规范版本 |
oid | 文件内容的 SHA-256 哈希 |
size | 文件大小（字节） |
14.2 安装与配置
14.2.1 安装 Git LFS
# Ubuntu/Debian
$ sudo apt install git-lfs
# macOS
$ brew install git-lfs
# Windows (随 Git for Windows 一起安装，或)
$ choco install git-lfs
# 验证安装
$ git lfs version
git-lfs/3.4.0 (GitHub; linux amd64; go 1.21.0)
# 初始化（每个用户只需执行一次）
$ git lfs install
Git LFS initialized.
14.2.2 跟踪文件类型
# 跟踪特定文件类型
$ git lfs track "*.psd"
$ git lfs track "*.zip"
$ git lfs track "*.mp4"
# 跟踪特定目录下的文件
$ git lfs track "assets/**"
# 跟踪特定文件
$ git lfs track "data/dataset.csv"
# 跟踪大于指定大小的文件（Git LFS 2.10+）
$ git lfs track --above=50MB
14.2.3 查看跟踪配置
# 查看当前跟踪规则
$ git lfs track
Listing tracked patterns
*.psd (.gitattributes)
*.zip (.gitattributes)
assets/** (.gitattributes)
# 查看已追踪的文件
$ git lfs ls-files
abc1234 * assets/logo.psd
def5678 * data/video.mp4
# 查看 LFS 对象状态
$ git lfs status
14.3 LFS 日常操作
14.3.1 基本工作流
# 1. 配置跟踪规则
$ git lfs track "*.psd"
# 2. 确保 .gitattributes 被提交
$ git add .gitattributes
$ git commit -m "chore: add LFS tracking for PSD files"
# 3. 正常添加和提交大文件
$ git add assets/design.psd
$ git commit -m "feat: add design assets"
# 4. 正常推送
$ git push origin main
14.3.2 拉取 LFS 内容
# 克隆仓库（自动拉取 LFS 文件）
$ git clone https://github.com/user/repo.git
# 只获取 LFS 指针（不下载实际文件）
$ git lfs install --skip-smudge
$ git clone https://github.com/user/repo.git
# 手动拉取特定 LFS 文件
$ git lfs pull --include="*.psd"
# 拉取所有 LFS 文件
$ git lfs pull
14.3.3 LFS 过滤器
# 只拉取特定目录的 LFS 文件
$ git lfs pull --include="assets/**"
# 排除特定文件
$ git lfs pull --exclude="*.mp4"
# 浅克隆 + 部分 LFS
$ git clone --depth 1 --filter=blob:none https://github.com/user/repo.git
$ git lfs pull --include="src/**"
14.4 LFS 存储管理
14.4.1 查看存储使用
# 查看 LFS 对象列表
$ git lfs ls-files --size
abc1234 * assets/logo.psd (15.2 MB)
def5678 * data/video.mp4 (256.0 MB)
# 查看 LFS 对象总数和大小
$ git lfs ls-files --size | wc -l
$ git lfs ls-files --size | awk '{sum += $(NF-1)} END {print sum " MB"}'
14.4.2 清理 LFS 缓存
# 查看本地 LFS 缓存大小
$ du -sh .git/lfs/
# 清理未引用的 LFS 对象
$ git lfs prune
# 清理前预览
$ git lfs prune --dry-run
# 保留最近 N 天的对象
$ git lfs prune --recent=7d
# 强制清理（包括锁定的对象）
$ git lfs prune --force
14.4.3 LFS 文件锁定
# 锁定文件（防止他人修改）
$ git lfs lock assets/design.psd
Locked assets/design.psd
# 查看锁定的文件
$ git lfs locks
assets/design.psd john@example.com ID:12345
# 解锁文件
$ git lfs unlock assets/design.psd
# 推送时强制解锁（换人维护）
$ git lfs unlock --force assets/design.psd
14.5 迁移到 LFS
14.5.1 将现有文件迁移到 LFS
# 使用 git-lfs-migrate 工具
# 1. 安装 git-lfs-migrate（通常随 Git LFS 一起安装）
# 2. 迁移历史中的大文件
$ git lfs migrate import --include="*.psd,*.zip,*.mp4" --everything
# 3. 查看迁移状态
$ git lfs migrate info --everything
14.5.2 从 LFS 迁移回 Git
# 将文件从 LFS 迁移回普通 Git 对象
$ git lfs migrate export --include="*.psd" --everything
14.5.3 迁移注意事项
| 步骤 | 操作 | 说明 |
|---|
| 1 | 备份 | git clone --mirror 备份完整仓库 |
| 2 | 迁移 | git lfs migrate import |
| 3 | 验证 | git lfs ls-files 确认 |
| 4 | 强制推送 | git push --force --all |
| 5 | 通知团队 | 所有人需要重新克隆 |
⚠️ 迁移会重写历史，必须与团队协调。
14.6 LFS 存储平台
| 平台 | 免费存储 | 说明 |
|---|
| GitHub | 1 GB + 1 GB/月带宽 | GitHub Free |
| GitHub Pro | 2 GB + 2 GB/月带宽 | 付费计划 |
| GitLab | 5 GB | 免费计划 |
| Bitbucket | 1 GB | 免费计划 |
| 自建 | 无限制 | MinIO、Ceph 等 |
自建 LFS 服务器
# 使用 lfs-test-server（GitHub 官方测试服务器）
$ git clone https://github.com/git-lfs/lfs-test-server.git
$ cd lfs-test-server
$ go build
# 配置使用自建服务器
$ git config lfs.url https://your-server.com/lfs
14.7 LFS 常见问题
| 问题 | 原因 | 解决方案 |
|---|
| 文件未被 LFS 追踪 | .gitattributes 未提交 | git add .gitattributes |
| 克隆很慢 | LFS 文件太大 | --skip-smudge 后按需 git lfs pull |
| 推送失败 | LFS 存储空间不足 | 清理或升级存储计划 |
| 指针文件被提交 | LFS 未安装 | 安装后 git lfs checkout |
| 团队无法拉取 | 未安装 LFS | 安装 git lfs 并 git lfs install |
业务场景
| 场景 | 推荐方案 |
|---|
| 游戏开发资源 | LFS 追踪纹理、模型、音频 |
| 设计文件管理 | LFS 追踪 PSD、Sketch、Figma 导出 |
| 数据集管理 | LFS 追踪大型 CSV、Parquet 文件 |
| 视频/音频项目 | LFS 追踪媒体文件 |
| 二进制构建产物 | CI/CD 产物使用 LFS 或制品库 |
扩展阅读
🔗 上一章：13 - Git Hooks | 下一章：15 - GitHub 工作流