Git LFS需手动安装启用，通过git lfs install写入.git/config，用git lfs track配置.gitattributes并提交，CI/CD须显式执行git lfs install && git lfs pull才能获取大文件。
Git LFS 客户端安装与全局启用
Git LFS 不是 Go 语言内置能力，它完全依赖 Git 的钩子和过滤器机制。你写的是 Go 项目，但 LFS 配置发生在 Git 层，Go 编译器和 go mod 对它完全无感。
常见错误是以为在 go.mod 或 main.go 里加点配置就能让大文件走 LFS —— 实际上，git lfs install 没跑，LFS 根本不工作，所有“大文件”仍会以原始二进制塞进 Git 历史。
- 先确认已安装 Git LFS：
git lfs version，没输出就去 git-lfs.com 下载安装 - 在项目根目录运行：
git lfs install --local（推荐加--local，避免污染全局配置） - 别跳过这步：
git lfs install会在.git/config里写入filter.lfs.*配置，没它，git add时根本不会触发 LFS 上传逻辑
哪些文件该用 LFS？Go 项目里的典型目标
不是所有“看起来大”的文件都适合 LFS。LFS 适合**极少变更、体积大、不参与构建过程**的资源。Go 项目里常见的误用场景是把 vendor/、go.sum 或编译产物塞进去 —— 这些反而会拖慢 clone 和 CI。
- ✅ 推荐托管：模型权重文件（
model.bin）、测试用音视频样本（test_data.mp4）、图标集（assets/icons.zip） - ❌ 明确避开：
vendor/（应由go mod vendor生成）、bin/、dist/、go.mod、go.sum - ⚠️ 注意路径匹配：LFS 规则按 glob 匹配，
*.bin会同时匹配model.bin和tmp.bin；更安全写法是models/*.bin或**/weights/*.pt
git lfs track 的实际行为与陷阱
git lfs track 本质只是往 .gitattributes 里追加一行规则，它本身不修改任何文件，也不上传内容。很多人执行完就以为“搞定了”，结果 git add 时文件还是普通 blob。
立即学习“go语言免费学习笔记（深入）”；
- 必须手动提交
.gitattributes：git add .gitattributes && git commit -m "track large files via LFS" - 已加入暂存区的文件不会自动转为 LFS：如果先
git add bigfile.zip再git lfs track "*.zip"，那个bigfile.zip依然在 Git 历史里是普通对象；得git rm --cached bigfile.zip && git add bigfile.zip才能触发 LFS 重写 - 规则顺序有影响：
.gitattributes是从上到下匹配，如果前面有* text=auto，后面*.bin filter=lfs可能被覆盖；建议把 LFS 规则放在文件顶部
CI/CD 中拉取 LFS 文件的必要操作
GitHub Actions、GitLab CI 默认只做浅克隆（--depth=1），且不自动运行 git lfs pull。如果你的 Go 测试或构建步骤依赖 LFS 文件，不显式拉取就会 panic：“no such file or directory”。
- GitHub Actions 必须加一步：
git lfs install && git lfs pull（注意顺序，install要在pull前） - GitLab CI 需在
before_script加：git lfs install && git lfs fetch && git lfs checkout - 本地开发也别偷懒：clone 新仓库后，记得
git lfs install && git lfs pull，否则go test ./...可能因缺资源文件失败
LFS 的核心复杂点在于它游离于 Go 工具链之外：没有 go lfs init，没有 go mod lfs sync，所有动作都是 Git 命令 + 文件系统约定。一旦漏掉某个环节（比如忘了提交 .gitattributes 或 CI 里少了一行 git lfs pull），问题就表现为“文件存在但读不到”或者“第一次 clone 特别慢但后续又快了”——其实是 LFS 指针没解析。
