Git LFS 大文件存储

FreeGuideOnline 19阅读 2026-07-11

什么是 Git LFS？

Git LFS（Large File Storage）是一种将大型文件与 Git 仓库分离管理的扩展工具。它用文本指针文件替换实际的大文件，并将这些大文件存储在远程服务器上（如 GitHub、GitLab、Bitbucket），从而保持仓库体积轻量、克隆和拉取操作高效。

为什么需要 Git LFS？

传统 Git 在处理二进制文件或大型文件时存在明显缺陷：

  • 仓库体积膨胀：每提交一个大文件，即使后续删除，历史中仍保留该文件，导致仓库无限增大。
  • 克隆缓慢：克隆仓库时需要下载所有历史版本的大文件，耗时且浪费带宽。
  • 协作困难：多人频繁修改大型二进制文件时，极易产生冲突。

Git LFS 正是为解决这些问题而设计，它只下载实际所需版本的大文件，极大优化了存储和传输效率。

Git LFS 的工作原理

  1. 追踪规则：通过 .gitattributes 文件指定哪些文件使用 LFS 管理。
  2. 替换存储：当匹配的文件被添加到暂存区时，Git LFS 将其替换为一个文本指针文件（包含文件哈希和大小），并上传实际文件到远端 LFS 存储。
  3. 按需下载：克隆仓库时默认只下载指针文件；实际大文件在需要时（如执行 git lfs pull 或检出对应版本）才从远端拉取。

安装与配置

安装 Git LFS

在继续之前，请确保本地已安装 Git（版本 ≥ 1.8.5）。然后根据操作系统选择安装方式：

macOS（Homebrew）

brew install git-lfs

Windows（Scoop 或 Chocolatey）

# 使用 Scoop
scoop install git-lfs

# 使用 Chocolatey
choco install git-lfs

Linux（Debian/Ubuntu）

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

Linux（CentOS/RHEL）

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.rpm.sh | sudo bash
sudo yum install git-lfs

初始化 Git LFS

安装完成后，在终端中运行一次全局初始化：

git lfs install

该命令会在 Git 配置中添加 filter.lfs 相关的过滤器，使所有仓库都具备 LFS 能力。

快速上手：在现有仓库中使用 Git LFS

1. 进入仓库并设置 LFS 追踪规则

使用 git lfs track 命令指定要管理的大文件模式，例如追踪所有 .psd 文件：

cd your-repo
git lfs track "*.psd"

这会在仓库根目录创建或更新 .gitattributes 文件。请务必将该文件提交到仓库，以便团队共享追踪配置。

2. 添加并提交大文件

操作与普通 Git 流程相同，但文件会被自动替换为 LFS 指针：

git add design.psd
git commit -m "Add design source file"

此时可通过 git lfs ls-files 查看当前所有由 LFS 管理的文件及版本。

3. 推送到远程仓库

确保远程仓库支持 LFS（大多数代码托管平台默认支持）。执行普通推送命令：

git push origin main

Git LFS 会先将大文件上传至 LFS 存储，再推送指针文件的更新。

4. 克隆 LFS 仓库

其他协作者克隆时，默认只会下载指针文件。需要实际大文件时，执行：

git clone <repository-url>
cd repository
git lfs pull   # 下载当前分支的最新大文件

也可以使用 GIT_LFS_SKIP_SMUDGE=1 跳过自动下载，仅获取指针文件。

常用命令一览

命令 作用
git lfs track "*.zip" 追踪所有 .zip 后缀文件
git lfs track "images/**" 追踪 images 目录下所有文件
git lfs untrack "*.zip" 取消对指定模式的追踪
git lfs ls-files 列出当前分支所有 LFS 管理文件
git lfs status 显示暂存区中 LFS 文件状态
git lfs pull 拉取当前分支所需的 LFS 文件
git lfs fetch --all 获取所有分支的 LFS 文件（不自动检出）
git lfs prune 删除本地未引用的 LFS 文件以回收空间

迁移已有仓库到 Git LFS

如果仓库中已积累了大量大文件，需要将其历史提交中的大文件转换为 LFS 指针。可使用 git lfs migrate 命令谨慎操作（务必先备份仓库）。

示例：将 master 分支历史中所有 .mp4 文件迁移至 LFS

git lfs migrate import --include="*.mp4" --include-ref=master

常用选项：

  • --include：指定要迁移的文件模式，可重复使用添加多个模式。
  • --include-ref：指定要迁移的分支或引用（如 master、refs/heads/*）。
  • --everything：迁移所有本地和远程引用。
  • --verbose：显示详细信息。

执行迁移后，原始的 .mp4 文件会被 LFS 指针替换，历史记录被重写。需要用 git push --force 推送到远端（注意：这会改写共享历史，请与团队成员充分沟通）。

最佳实践与注意事项

制定合理的追踪规则

避免追踪不需要版本的衍生文件或临时文件。常见的大文件类型包括：

  • 图片与设计源文件（.psd、.sketch、.ai）
  • 音视频素材（.mp4、.mov、.wav）
  • 二进制数据文件（.zip、.tar.gz、.bin）
  • 训练模型或数据集文件

及时提交 .gitattributes

确保 .gitattributes 在首次添加大文件前提交，否则大文件可能以传统方式被直接存储到 Git 对象库。

仓库托管限制与定价

不同平台对 LFS 免费存储和带宽有一定限额，请根据项目规模选择合适的方案：

  • GitHub：每仓库免费 1 GB 存储 + 1 GB/月带宽，超出需购买数据包。
  • GitLab：免费提供 10 GB 存储，不限带宽（依具体计划可能调整）。
  • Bitbucket：免费 1 GB 存储，超出需升级。

协作中保持一致性

所有协作者必须安装 Git LFS 并正确配置，否则会导致指针文件被误当作普通文本处理。

检查 LFS 状态与清理

定期使用 git lfs status 检查暂存文件是否被正确管理，使用 git lfs prune 移除本地不再需要的 LFS 缓存文件以减少磁盘占用。

常见问题排查

1. 推送时提示 “This repository is over its data quota”

说明仓库 LFS 使用量超过了平台限额。解决方法：

  • 删除不再需要的 LFS 文件并执行 git lfs prune（注意历史仍占用空间）。
  • 联系平台升级数据计划。
  • 移除部分大文件的历史记录（使用 git lfs migrate export）或重写历史。

2. 克隆后文件无法打开，看起来是乱码文本

文件中仅包含类似 version https://git-lfs.github.com/spec/v1 ... 的内容，说明未下载实际文件。运行：

git lfs pull

或全局启用自动下载：

git config --global filter.lfs.smudge "git-lfs smudge %f"
git config --global filter.lfs.process "git-lfs filter-process"

3. git lfs track 命令无效，文件仍被当作普通文件提交

确认以下几点：

  • .gitattributes 文件已提交并推送，其他协作者已经拉取。
  • 文件路径符合模式匹配（可使用 git check-attr -a <file> 检查属性）。
  • 该文件未被 .gitignore 忽略（忽略文件不会进入暂存区）。
  • 文件未被之前以传统方式提交过（如已存在，需清理缓存：git rm --cached <file> 后重新添加）。

4. 如何在服务器端启用 LFS？

自托管 Git 服务器（如 Gitea、GitLab CE）需要单独配置 LFS 后端。通常需要在服务器配置文件中指定 LFS 存储路径或使用对象存储服务。请参考对应服务器的官方文档。

结语

Git LFS 是管理大型二进制文件的最佳伴侣，它无缝融入 Git 工作流，有效控制仓库体积并提升协作效率。通过合理配置追踪规则、遵循最佳实践，你可以轻松将游戏资源、设计稿、样本数据等大文件纳入版本控制，同时保持仓库的敏捷与健康。