Git LFS
约 1439 字大约 5 分钟
macgit
2026-03-25
什么是 Git LFS
Git LFS（Large File Storage）是 Git 的扩展，用于解决 Git 在管理大文件时的性能问题。它将大文件（如图片、视频、数据集、编译产物等）的实际内容存储在远端 LFS 服务器上，而在 Git 仓库中仅保留轻量级的文本指针。
为什么需要 Git LFS
Git 是为文本文件设计的版本控制系统，直接管理大型二进制文件会导致：
- 仓库体积膨胀：每次修改都会保存完整副本，历史记录越来越大
- 克隆速度变慢：
git clone需要下载全部历史版本的大文件 - 性能下降：
git status、git diff等命令会变得很慢
Git LFS 通过「指针替换 + 按需下载」的机制解决了这些问题。
工作原理
┌──────────────────────────────────┐
│ Git Repository │
│ │
│ file.psd → pointer (< 1KB) │
│ video.mp4 → pointer (< 1KB) │
│ code.js → 原始内容（不变） │
│ │
└──────────────┬───────────────────┘
│ push / pull
▼
┌──────────────────────────────────┐
│ LFS Server │
│ │
│ file.psd → 实际二进制内容 │
│ video.mp4 → 实际二进制内容 │
│ │
└──────────────────────────────────┘LFS 指针文件内容示例：
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345678安装与配置
安装 Git LFS
macOS
brew install git-lfsUbuntu/Debian
sudo apt install git-lfsWindows
# 通过 Git for Windows 自带，或手动下载安装
# https://git-lfs.com初始化
在当前用户的全局 Git 配置中启用 LFS：
git lfs install这会在 ~/.gitconfig 中添加 LFS 所需的 filter 和 hook 配置：
[filter "lfs"]
clean = git-lfs clean -- %f
smudge = git-lfs smudge -- %f
process = git-lfs filter-process
required = true基本使用
跟踪大文件
使用 git lfs track 指定要用 LFS 管理的文件模式：
# 按扩展名跟踪
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"
git lfs track "*.png"
# 跟踪特定目录下的所有文件
git lfs track "assets/videos/**"
# 跟踪单个文件
git lfs track "path/to/large-file.bin"执行后会自动创建或更新 .gitattributes 文件：
*.psd filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text注意
.gitattributes 文件必须提交到仓库中，这样其他协作者克隆时才能自动使用 LFS。
提交与推送
配置好跟踪规则后，正常使用 Git 工作流即可：
git add .gitattributes
git add assets/design.psd
git commit -m "add design file"
git push查看状态
# 查看当前跟踪规则
git lfs track
# 查看 LFS 管理的文件列表
git lfs ls-files
# 查看 LFS 文件的详细状态
git lfs status
# 查看 LFS 环境信息
git lfs env常用命令
文件管理
# 取消跟踪某类文件
git lfs untrack "*.psd"
# 手动拉取 LFS 文件内容
git lfs pull
# 仅拉取指定文件
git lfs pull --include="*.psd"
# 推送待上传的 LFS 文件
git lfs push origin main迁移已有文件
如果仓库中已有大文件，需要将其迁移到 LFS：
# 将已有的 .psd 文件迁移到 LFS（重写历史）
git lfs migrate import --include="*.psd"
# 迁移指定分支
git lfs migrate import --include="*.psd" --include-ref=refs/heads/main
# 查看哪些文件类型占用空间最多
git lfs migrate info注意
git lfs migrate import 会重写 Git 历史，在团队协作时需要谨慎使用，确保与所有协作者沟通后再执行。
清理与维护
# 清理本地缓存的 LFS 文件（保留指针）
git lfs prune
# 获取缺失的 LFS 文件
git lfs fetch --all
# 检查 LFS 文件的完整性
git lfs fsck进阶用法
自定义 LFS 服务器
默认使用远端 Git 仓库提供的 LFS 服务，可通过 .lfsconfig 指定自定义服务器：
# .lfsconfig
[lfs]
url = https://my-lfs-server.example.com/storage文件锁定
对不可合并的二进制文件使用锁定机制避免冲突：
# 锁定文件
git lfs lock assets/design.psd
# 查看已锁定的文件
git lfs locks
# 解除锁定
git lfs unlock assets/design.psd
# 强制解除他人的锁定
git lfs unlock assets/design.psd --force可在 .gitattributes 中设置默认需要锁定：
*.psd filter=lfs diff=lfs merge=lfs -text lockable克隆优化
# 跳过 LFS 文件下载（之后按需 pull）
GIT_LFS_SKIP_SMUDGE=1 git clone <repo-url>
# 之后再拉取需要的 LFS 文件
cd repo
git lfs pull --include="*.png"指定拉取范围
# 设置只获取指定类型的 LFS 文件
git config lfs.fetchinclude "*.png,*.jpg"
# 排除不需要的 LFS 文件
git config lfs.fetchexclude "*.mp4,*.zip"各平台配额
| 平台 | 免费存储 | 免费带宽 | 付费方案 |
|---|---|---|---|
| GitHub | 1 GB | 1 GB/月 | $5/月（50GB 存储 + 50GB 带宽） |
| GitLab | 5 GB | 不限 | 按计划升级 |
| Bitbucket | 1 GB | 不限 | 按计划升级 |
最佳实践
适合用 LFS 管理的文件
- 图片资源（PSD、PNG、JPG）
- 音视频文件（MP4、MP3、WAV）
- 压缩包（ZIP、TAR.GZ）
- 编译产物、二进制可执行文件
- 数据集（CSV、SQLite、HDF5）
- 字体文件（TTF、OTF、WOFF2）
不适合用 LFS 管理的文件
- 频繁变更的小型文本文件
- 需要 diff 和 merge 的源代码文件
- 已经用 CDN 等其他工具管理的资源
团队协作建议
- 项目初期就配置 LFS，避免后期迁移的复杂度
- 将
.gitattributes提交到仓库，确保规则对所有人生效 - CI/CD 中配置 LFS：
# GitHub Actions
- uses: actions/checkout@v4
with:
lfs: true- 善用文件锁定，避免多人同时修改二进制资源
- 定期清理本地 LFS 缓存：
git lfs prune
常见问题
LFS 文件显示为指针文本
打开文件看到 version https://git-lfs.github.com/spec/v1...，说明 LFS 文件未正确下载：
git lfs pull
# 或
git lfs checkout推送时 LFS 报错 403/413
- 403：检查是否有 LFS 写入权限，确认 Token 或 SSH Key 配置正确
- 413：文件超出服务器限制，检查平台的单文件大小限制
如何完全移除 LFS
# 将 LFS 文件还原为普通 Git 文件
git lfs migrate export --include="*.psd" --everything
# 卸载 LFS hook
git lfs uninstall
# 删除 .gitattributes 中的 LFS 规则