G
GitIgnore.pro
🎯Git LFS Production Playbook

Git LFS 最佳实践:大文件管理与 .gitignore 策略

Git LFS 不是「装上就完事」的插件,而是一套牵涉 .gitignore、.gitattributes、CI/CD 存储预算的流程。本指南覆盖从初次启用到团队协作、自动化审计的完整路径,帮助你把大文件管理做成可复用的规范。

01. 何时使用 Git LFS?两道判断题

✅ 必用场景

  • • 二进制资产 > 10 MB(设计稿、3D 模型、音视频、训练模型权重)
  • • 需要版本追踪但不能压缩 diff 的文件(Office、CAD)
  • • 多人合作且需要在 CI/CD 中下载同一份大文件

⚠️ 不建议场景

  • • 每次构建都能自动生成的产物(前端打包、编译输出)
  • • 小于 1 MB 且随代码改动频繁的配置文件
  • • 已经存放在外部对象存储(S3、OSS)且有有效引用的资源

✳️ 如果「放入版本库」不是刚需,请优先考虑外部对象存储,以免拉低 clone 速度并触发 GitHub 带宽限制。

02. 初始化流程:.gitignore + .gitattributes 双轨更新

Git LFS 配置分两步:.gitattributes 负责将匹配到的文件替换为 LFS 指针;.gitignore 继续挡住可重新生成的缓存、临时文件。

# 1. 初始化 Git LFS(一次性)
git lfs install

# 2. 针对模型 / 设计稿 / 纹理等大文件建立追踪规则
git lfs track "*.psd"
git lfs track "*.glb"
git lfs track "assets/models/**"

# 3. 提交更新后的 .gitattributes
git add .gitattributes
git commit -m "chore: track binary assets with Git LFS"

💡 建议将 LFS 规则写在独立段落,并配合注释说明用途,降低团队成员误删的概率。

.gitignore 配合策略

  • • 忽略缓存目录(如 assets/cache/
  • • 保留 .gitattributes 的追踪范围可控,避免与忽略规则冲突
  • • 对大型导出目录使用 `!` 反选,保留 README 或 manifest

常见陷阱

  • • 忽略规则写在 LFS track 之后,导致指针文件也被忽略
  • • 仅在本地执行了 git lfs track,但忘记提交 .gitattributes
  • • 忽略目录时未保留 metadata,CI 获取资源失败

03. 存储预算:容量、带宽与镜像同步

容量规划

  • • GitHub 免费版:1 GB LFS + 每月 1 GB 流量
  • • 企业版:建议按每个项目年度预算测算
  • • 定期执行 git lfs ls-files -s 输出容量报表

带宽控制

  • • CI/CD 尽量使用缓存或镜像,避免重复下载
  • • 对外发布的构建资源使用对象存储 Instead of 仓库
  • • 对大型资源使用分层 Track(原始 + 处理后)

镜像同步

  • • 若使用多 Git 托管,请确保 LFS endpoint 同步
  • • 定期执行 git lfs fetch --all + git lfs push --all 校验
  • • 为 LFS server 增加对象存储备份

04. CI/CD 中的 LFS:避免「Pipeline 被吸干」

  1. 构建缓存: 配置 CI 缓存(如 GitHub Actions cache、GitLab Cache),避免每次克隆都全量下载。
  2. 只拉需要的文件: 借助 GIT_LFS_SKIP_SMUDGE=1 只在需要时下载,减少冗余流量。
  3. 自建镜像: 对频繁下载的模型/素材,放到内网对象存储并在流水线中链接。
  4. 配额监控: 使用 GitHub API 或 `git lfs env` 获取剩余配额,超过阈值自动告警。
# GitHub Actions 示例
- name: Checkout repo (skip LFS)
  uses: actions/checkout@v4
  with:
    lfs: false

- name: Download required assets
  run: |
    git lfs fetch --include="assets/models/**"
    git lfs checkout assets/models

- name: Cache LFS objects
  uses: actions/cache@v4
  with:
    path: .git/lfs
    key: lfs-\${{ runner.os }}-\${{ hashFiles('.gitattributes') }}

05. 自动化审计脚本(防止误入仓)

分支评审前跑一次脚本,即可找出未进入 LFS 的超大 blob,防止被意外合并。

# scripts/check-lfs.sh
#!/usr/bin/env bash

set -euo pipefail

THRESHOLD_MB=80
echo "Checking objects larger than ${THRESHOLD_MB}MB that are not tracked by LFS..."

git rev-list --objects --all   | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)'   | awk -v limit=$((THRESHOLD_MB * 1024 * 1024)) '      $1 == "blob" && $3 > limit { print $2 " " $3/1024/1024 "MB " $4 }'   | while read -r oid size path; do
      if ! git check-attr filter -- "${path}" | grep -q 'filter: lfs'; then
        echo "::warning file=${path}::${size}(未加入 Git LFS)"
      fi
    done

将脚本加入 pre-push hook 或 CI 任务,输出的 `::warning` 可在 GitHub Actions 日志中直接显示。

06. 团队协作清单

上线前

  • ☑️ 约定命名规范(哪些目录属于 LFS)
  • ☑️ 更新项目 README / 贡献指南,说明拉取 LFS 的命令
  • ☑️ 建立 LFS 使用配额的监控/提示渠道

运行中

  • ☑️ 每周输出 LFS 容量报表,标记增长最快的文件夹
  • ☑️ 定期核查 `.gitattributes` 与 `.gitignore` 是否同步
  • ☑️ 结合 Git hooks/CI 自动执行上文的 blob 审计脚本

07. 进阶资源导航

  • Monorepo + LFS:将多包仓库的忽略策略与 LFS 结合,参考《Monorepo .gitignore 架构》, 为每个包补充 `.gitignore` 与 `.gitattributes`。
  • 流水线联动:在部署阶段执行忽略校验与 artifacts 上传,可沿用CI/CD 友好型 .gitignore 指南 中的脚本和缓存策略。
  • 模板组合:通过 模板生成器 选择 Unity、Terraform、Next.js 等栈, 形成一份共享的 LFS + .gitignore 基线,再交给Analyzer 做自动审计。

08. 常见问题 FAQ

如何确认一个文件已经被 LFS 追踪?

运行 git lfs ls-files | grep <文件名>。 如果没有结果,可检查 `.gitattributes` 是否覆盖路径,或使用Analyzer 查看缺失规则。

LFS 配额不足如何处理?

优先删除可再生产物(build、缓存),并将模型等大文件迁移到对象存储。 可在 Search Console 周报中记录容量趋势,必要时升级 GitHub LFS 套餐。

已经提交的大文件怎么回滚?

使用 git lfs migrate import 将历史提交转换为 LFS 指针, 重新推送后执行本文的审计脚本,确认仓库不再带有大文件。

下一步:把 LFS 与流程接通

生成大文件安全的 .gitignore

把 LFS 追踪规则、fallback 模板和团队标准放进一个文件里。