根本原因是凭证失效或lfs endpoint地址错配；git lfs需先向服务器发起batch请求获取上传地址，该http步骤失败（如401/403/eof）即导致“lfs: upload failed”，与网络或文件大小无关。
git push 时提示 “LFS: Upload failed” 或 “batch request failed”
根本原因通常是凭证失效或 LFS endpoint 地址错配，而不是网络慢或文件太大。Git LFS 不会把大文件塞进 git push 流程里，而是先通过 HTTP 向 LFS 服务器发起 POST /info/lfs/objects/batch 请求获取上传地址，再单独上传——这一步失败了，git push 就会卡在 “LFS: Upload failed”。
常见现象包括：
- 终端输出类似
LFS: Upload failed: 401 Unauthorized或batch request failed: EOF -
git lfs ls-files能列出文件，但git push始终不上传 LFS 对象 - 克隆新仓库时能拉下指针，但
git lfs pull报 403
实操建议：
- 运行
git config --get-regexp 'lfs.*url'，确认值是形如https://gitlab.example.com/group/project.git/info/lfs的地址，不是原始 Git URL（比如以.git结尾但没/info/lfs） - 用
git credential reject清掉旧凭据：echo "protocol=https\nhost=gitlab.example.com" | git credential reject - 重新触发认证：执行一次
git lfs fetch或git lfs pull，它会弹出登录框或读取 token；GitHub 需read:packages+write:packages，GitLab 私有化部署需api权限的 personal access token - 企业自建 Git 服务要检查是否部署了
git-lfs-authenticate钩子，且返回的 JWT 未过期
git clone 时跳过大文件下载，只拉指针
这不是错误，是 Git LFS 的正常行为。默认 git clone 只下载指针文件（几 KB），实际大文件需额外执行 git lfs pull 才会下载。如果你只是想快速检出代码结构、跑 CI 或查 commit 历史，跳过 LFS 下载反而更高效。
但要注意：
- 若项目依赖 LFS 文件才能编译（如预编译的 so、模型权重 bin），不
git lfs pull会导致构建失败 - 某些 CI 环境（如 GitLab Runner）默认不自动执行
git lfs pull，需显式加在脚本里 - 用
git clone --filter=blob:none（稀疏克隆）可进一步减少初始下载量，但和 LFS 无关，别混用
如果真想“一并拉全”，克隆后立刻执行：
git lfs pull
或者克隆时加 -c filter.lfs.smudge=true 参数（仅适用于已配置好凭据的环境）：
git clone -c filter.lfs.smudge=true https://gitlab.example.com/group/project.git
误提交大文件到普通 Git，如何补救
一旦 git add + git commit 把几百 MB 的 data.bin 提交进历史，它就永久留在对象库中，即使后续用 git lfs track 也无济于事——指针只对新 commit 生效。
必须重写历史才能清理已提交的大文件：
- 先确保本地没未推送的敏感变更，否则重写后无法合并
- 运行
git lfs migrate import --include="*.bin,*.zip" --everything（Git LFS v2.11+ 支持） - 该命令会扫描所有 commit，把匹配的文件替换成 LFS 指针，并重写 tree 和 commit 对象
- 完成后强制推送到远端：
git push --force --all && git push --force --tags - 所有协作者必须重新克隆，旧 clone 中的
git pull会失败
注意：git lfs migrate 不支持 Windows 路径通配符（如 **/*.psd），得拆成多个 --include；且迁移后原文件名不能带空格或 Unicode，否则指针解析可能出错。
git lfs track 后文件没被识别为 LFS 类型
最常被忽略的是 .gitattributes 文件没被提交。Git LFS 依赖这个文件声明规则，但它本身是文本，容易被漏掉 git add。
验证步骤：
- 执行
git lfs track "*.pdf"后，检查是否生成或更新了.gitattributes，内容应含*.pdf filter=lfs diff=lfs merge=lfs -text - 运行
git status，确认.gitattributes在待提交列表里；若没出现，手动git add .gitattributes - 提交后，再
git add report.pdf，此时git lfs ls-files应显示该文件
另一个坑是路径匹配优先级：如果 .gitattributes 里已有 *.pdf -filter 这类禁用规则，会覆盖 filter=lfs。用 git check-attr -a report.pdf 查看最终生效的 attr 值。
真正麻烦的从来不是“怎么开 LFS”，而是团队成员各自凭据状态不一致、历史重写后协作断层、以及指针文件被编辑器误删导致 LFS 对象丢失——这些点没有自动修复机制，只能靠流程卡点和定期 git lfs fsck 校验。
