模型文件硬塞进 Git，GitHub 直接打回原形：使用Git-LFS管理大文件-51CTO.COM

前言

最近接手了一个计算机视觉项目，代码是屎山就不说了，反正我也不看代码，主要就是构建一下 docker 镜像，测试一下部署的兼容性，这本来不难。

但是，国内服务器的网络环境实在是恶劣，需要配置各种镜像（docker镜像、apt镜像、pip镜像），这些镜像还各有各的问题，结果就是搭配下来一直无法构建成功。

之后我灵机一动，利用 GitHub Actions 来构建镜像，以 GitHub 的服务器网络，所有问题不就迎刃而解了吗？

试了之后果然可以成功构建出镜像

不过中途也踩了一些坑，比如大文件的问题

之前的项目没遇到过大文件，因为我从不把 PyTorch 的模型文件放在代码里跟着提交到 git 里！

能做出这种操作的，多少带点那啥😅

GitHub对大文件的限制

GitHub 文件大小限制：

单个文件 > 50MB 会有警告
单个文件 > 100MB 会直接被拒绝推送

结果就是:

Writing objects: 100% (304/304), 463.41 MiB | 3.23 MiB/s, done. Total 304 (delta 32), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (32/32), done. remote: warning: File fire_detection/yolov5l.pt is 88.50 MB; this is larger than GitHub's recommended maximum file size of 50.00 MB remote: error: Trace: 52267c96d371181694b02dad5eebead817ce6d985e2f8d356c2b458adfbb2a09 remote: error: See https://gh.io/lfs for more information. remote: error: File runs/detect/fire_smoke_detection/weights/best.pt is 166.91 MB; this exceeds GitHub's file size limit of 100.00 MB remote: error: File runs/detect/fire_smoke_detection/weights/best.pt is 250.32 MB; this exceeds GitHub's file size limit of 100.00 MB remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com. To github.com:cppstudio/fire-detection.git ! [remote rejected] master -> master (pre-receive hook declined) error: failed to push some refs to 'github.com:studio/fire-detection.git'

解决办法就是用 **Git LFS (Large File Storage)**，GitHub 官方提供的专门存储大文件（模型权重、二进制、音频视频）的功能。

不过这个也挺抠门的，GitHub LFS 免费额度只有 1GB 存储 + 1GB 流量，超出需要买额外配额（或者用 HuggingFace/百度网盘/OSS 等托管模型文件）。

如果只是存 .pt 模型，可以考虑把权重放 HuggingFace，然后在 README 里写下载链接。

安装 git-lfs 工具

每个系统都能很容易安装

# Linux (Ubuntu/Debian)
sudo apt install git-lfs

# macOS (brew)
brew install git-lfs

# Windows (scoop)
scoop install git-lfs

然后初始化

git lfs install

跟踪大文件类型

比如说在本文的场景里，.pt 模型文件很大，可以指定让 LFS 管理

git lfs track "*.pt"

这会在仓库生成一个 .gitattributes 文件，内容大概是

*.pt filter=lfs diff=lfs merge=lfs -text

记得把这个 .gitattributes 也提交进 git

git add .gitattributes
git commit -m "track large files with Git LFS"

重新提交大文件

之前的提交如果包含了大文件

需要把这些大文件重新提交到 LFS

好在 git-lfs 提供了很方便的命令来清理历史，不然就得用我之前发的那篇文章里的方法来清理大文件了。

# 用 git lfs migrate 自动替换历史中的大文件
git lfs migrate import --include="*.pt"

# 强制推送
git push origin master --force

之后正常执行推送操作就行了

git push origin master

GitHub 就会把大文件存到 LFS，而不是普通 Git 仓库里。

拉取大文件

用了 Git LFS 之后，仓库里保存的大文件（比如 .pt）在普通 git clone 的时候只会看到一个 指针文件（几十字节，记录了真实文件在 LFS 存储里的位置）。

要把大文件本体下载下来，必须要安装过 Git LFS。

具体情况

如果机器上没装 Git LFS：clone 下来后，大文件就是“指针文件”，打不开、用不了。
如果机器上装了 Git LFS：clone 时会自动替换成真正的大文件。
如果已经 clone 过但大文件没拉下来：可以手动执行：git lfs pull

所以通常项目 README 里会写一句提示：

## 注意

本项目使用 [Git LFS](https://git-lfs.github.com/ "Git LFS") 管理大文件（模型权重等）。

请先执行：

```bash
git lfs install
git lfs pull
```

小结

这次折腾 GitHub 大文件问题，其实给了我几点启发：

GitHub 的限制：超过 100MB 的文件是绝对过不去的，别想着强行提交。
Git LFS 的价值：官方解决方案简单好用，但免费额度很抠，适合小规模文件管理。
替代方案：如果模型文件动辄几百 MB，推荐放在 HuggingFace、OSS、百度网盘等专门的存储平台，再在代码里提供下载脚本或链接。
最佳实践：代码就是代码，模型就是模型，别混着提交；把仓库保持干净，后期协作和部署都省心。

简单一句话总结：学会用 Git LFS，能应急；但别把它当免费网盘用。

另外，再多嘴一句：这个项目看着就像典型的“大学生作业仓库”——代码像屎山，模型直接丢进 git 里，八成还是教授一拍脑袋甩给研究生的“科研成果”。说实话，能跑起来已经算奇迹了 😂。

参考资料

[1] 如何清理误提交到git的历史大文件？: https://blog.deali.cn/p/clean-git-history-large-files