使用 Git LFS 管理大文件并上传至 GitHub 的完整实践
在嵌入式 SDK 或 BSP 项目中，经常包含工具链压缩包（如 .tar.xz、.img、.elf 等），这些文件远超 GitHub 的 100MB 限制。本文记录了完整的 Git LFS 配置、迁移和使用流程，适合用于大型 Linux SDK、芯片 BSP 上传。
🧱 一、什么是 Git LFS？
Git LFS（Large File Storage）是 Git 官方支持的大文件扩展，能够将大文件内容托管在 Git 仓库外部，同时只保存指针在 Git 中，大大减少仓库体积，并解决 GitHub 100MB 文件限制。
🔧 二、初次配置 Git LFS（只需一次）
# 安装 Git LFS（Linux 环境）
sudo apt install git-lfs
git lfs install
# 配置需要托管的文件类型（一次性添加）
git lfs track "*.img" "*.bin" "*.hex" "*.elf" "*.tar.gz" "*.tar.xz" "*.tar.bz2" "*.zip" "*.gz" "*.xz" "*.iso"
# 提交 .gitattributes 记录
git add .gitattributes
git commit -m "配置 Git LFS 跟踪大文件"
♻️ 三、迁移历史大文件为 LFS（首次上传前执行）
如果你的项目中之前已经提交了大文件，必须执行以下命令将历史记录中这些大文件转换为 Git LFS 托管：
git lfs migrate import --include="*.img,*.bin,*.hex,*.elf,*.tar.gz,*.tar.xz,*.tar.bz2,*.zip"
然后强制推送到远程仓库：
git push origin master --force
⚠️ 说明：仅 git lfs track 是不够的，历史文件不会被自动转换为 LFS，需要用 migrate import 扫描历史并替换为 LFS 对象，否则仍会出现 GitHub 上传失败的问题。
📦 四、日常使用（添加新大文件）
配置完 Git LFS 后，后续添加 .img/.bin/... 等大文件时，无需额外操作，直接执行普通 Git 命令即可：
git add 路径/大文件
git commit -m "添加 xxx 大文件"
git push
LFS 会自动生效。
🔍 五、查看当前托管的 LFS 文件
git lfs ls-files
📝 六、补充说明
-
若添加新的类型大文件（例如
.iso），需执行：git lfs track "*.iso" git add .gitattributes git commit -m "新增 iso 类型到 Git LFS" -
.gitattributes是 Git LFS 生效的关键配置文件，需提交并推送。 -
GitHub 限制单个文件大小：
- 未启用 LFS：最大 100MB
- LFS 后：单文件最大推荐不超过 2GB（超大也可能失败）
-
Git LFS 免费额度为：每月 1GB 存储 + 1GB 带宽（可付费扩展）
🧨 七、问题与实战中踩过的坑
-
remote: error: GH001: Large files detected：说明文件未被 LFS 管理。
解决方法：使用git lfs migrate import --include=...处理旧记录。 -
.gitattributes忘记提交：本地看似 LFS 正常，但远程实际上传了大文件，导致 push 被 GitHub 拒绝。 -
多次执行
git lfs track后未重新 commit：.gitattributes未更新，LFS 不生效。 -
大文件处理后仓库太大，推送极慢：建议搭配
git gc或git prune清理未引用对象：git gc --aggressive git prune -
修改
.gitattributes后需重新执行git lfs migrate import和强制 push，否则原文件仍然未进入 LFS。
🚀 八、建议配合使用的脚本（可选）
#!/bin/bash
# add_lfs_file.sh
git add "$1"
git commit -m "添加大文件 $1"
git push
📚 九、总结
| 步骤 | 是否必须 | 说明 |
|---|---|---|
| git lfs install | ✅ 一次性 | 安装并初始化 LFS |
| git lfs track | ✅ 一次性 | 跟踪文件后缀（*.img等） |
| .gitattributes 提交 | ✅ 一次性 | 记录 LFS 跟踪规则 |
| git lfs migrate import | ⚠️ 如有历史大文件需执行 | 迁移旧记录为 LFS |
| git add/commit/push | ✅ 每次使用 | 正常使用 Git 推送 |
如你正在进行 BSP 或 SDK 上传管理，本文方案可为你节省大量时间，避免反复 push 失败。如需帮助可留言交流。
