前言

最近接手了一个计算机视觉项目

代码是屎山就不说了，反正我也不看代码

主要就是构建一下 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 提供了很方便的命令来清理历史，不然就得用我之前发的那篇文章里的方法来清理大文件了。详见: ^[1]

# 用 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 大文件问题，其实给了我几点启发：

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

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

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

参考资料

[1]

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

解锁AI驱动的生产力跃迁

程序设计实验室专注前沿技术落地，每周解析代码级解决方案。

关注获取：

《DeepSeek极速上手手册》24页干货：零基础3天玩转智能编码

清华独家课程三部曲：

• 《DeepSeek从入门到精通》104页精讲（附30+代码实例）

• 《职场效能革命指南》35页实战：7大行业应用场景深度拆解

• 《AI红利捕获手册》65页秘籍：普通人快速构建竞争壁垒的5种路径

与万千技术人共建智能开发新范式。