Git LFS 上传大文件避坑指南：从忽略报错到成功推送的完整流程

在使用 Git LFS 管理大文件时，很多人会遇到 "文件被 .gitignore 忽略导致无法 add""推送仍触发大小限制" 等问题。本文以 "上传 385MB 的模型文件" 为例，详细拆解从配置 LFS 到成功推送的每一步，包含常见报错的解决方法，所有路径和命令可直接复用。

一、场景背景：为什么需要 Git LFS？

日常开发中，若需提交超过 100MB 的大文件（如模型文件、数据集、设计源文件），普通 Git 提交会被远程仓库拦截 ------ 多数仓库（公司内部 Git 或 GitHub）会设置 100MB 大小限制，避免仓库体积膨胀。

本文案例 ：需上传大文件 model/ai/bert_base_v2.bin（385MB）到分支 feature-bert-model，通过 Git LFS 绕过大小限制，过程中解决 "文件被 .gitignore 忽略" 的核心问题。

二、前置检查：确认 Git LFS 已配置

在处理大文件前，先确保本地已正确配置 Git LFS，避免后续步骤报错。

1. 检查 Git LFS 是否安装

打开终端，执行以下命令查看是否已安装 Git LFS：

git lfs install --version

• 若输出类似 git-lfs/3.5.1 (GitHub; darwin amd64; go 1.21.1)，说明已安装；

• 若提示 "command not found"，需先安装（按系统类型选择命令）：

  • Mac（Homebrew） ：brew install git-lfs
  • Linux（Ubuntu） ：sudo apt-get update && sudo apt-get install git-lfs
  • Windows ：从 Git LFS 官网 下载安装包，双击下一步完成。

2. 初始化 Git LFS（关键步骤）

进入项目根目录，执行初始化命令，让 Git 识别 LFS 扩展：

git lfs install

出现 Git LFS initialized. 提示，说明初始化成功 ------ 此时 Git 会自动添加 LFS 相关的钩子（hook），后续提交大文件时会触发 LFS 逻辑。

3. 配置 LFS 追踪大文件

告诉 Git "这个大文件要用 LFS 管理"，通过 git lfs track 命令配置追踪规则：

# 格式：git lfs track "大文件的完整路径"
git lfs track "model/ai/bert_base_v2.bin"

执行后会自动生成 / 更新 .gitattributes 文件（LFS 规则清单），该文件会记录 "哪些文件用 LFS 管理"，后续需提交到仓库。

验证追踪是否生效

执行以下命令查看 LFS 追踪列表：

git lfs track

若输出类似内容，说明追踪成功：

Listing tracked patterns
    model/ai/bert_base_v2.bin (.gitattributes)
Listing excluded patterns

三、核心问题：文件被 .gitignore 忽略，无法 add

当执行 git add model/ai/bert_base_v2.bin 时，终端可能抛出以下错误：

The following paths are ignored by one of your .gitignore files:
model/ai/bert_base_v2.bin
hint: Use -f if you really want to add them.
hint: Turn this message off by running
hint: "git config advice.addIgnoredFile false"

问题原因

之前可能为了避免误提交大文件，将 model/ai/bert_base_v2.bin 路径写入了 .gitignore，Git 会严格遵守该规则，默认拒绝添加被忽略的文件。但此时我们需要用 LFS 提交该文件，必须绕开 .gitignore 限制。

两种解决方案：强制添加 vs 修正 .gitignore

方案 1：强制添加（最快捷，推荐）

用 git add -f 命令（-f 即 force）强制将被忽略的大文件加入暂存区，临时覆盖 .gitignore 规则：

# 强制添加大文件到暂存区
git add -f model/ai/bert_base_v2.bin

• 优点：无需修改 .gitignore，仅本次 add 生效，后续 git add . 仍会忽略该文件，避免误提交；
• 注意：强制添加不会破坏 .gitignore 原有规则，只是针对当前文件 "例外处理"。

方案 2：修正 .gitignore（更规范，适合长期管理）

若希望该大文件后续能正常 add（无需每次强制），可删除 .gitignore 中该文件的路径，再正常添加：

# 步骤 1：删除 .gitignore 中的大文件路径（以 macOS/Linux 为例）
# 用 sed 命令直接删除包含该路径的行，避免手动编辑
sed -i '' '/model/ai/bert_base_v2.bin/d' .gitignore

# 步骤 2：正常添加大文件和更新后的 .gitignore
git add model/ai/bert_base_v2.bin
git add .gitignore  # 提交 .gitignore 的修改，确保团队其他人同步规则

• 优点：后续提交该文件无需再用 -f，适合大文件需要长期迭代更新的场景；
• 注意：若 .gitignore 中是通过通配符（如 *.bin）忽略文件，需调整通配符规则（如改为 !model/ai/bert_base_v2.bin 排除该文件）。

四、提交与推送：确保 LFS 正常工作

解决 ignore 问题后，按正常 Git 流程提交并推送，LFS 会自动处理大文件上传。

1. 提交代码（包含 LFS 规则和大文件）

# 提交时备注清晰，说明是 LFS 大文件
git commit -m "feat: 用 Git LFS 提交 bert 模型文件（385MB）"

提交成功后，终端会显示类似日志（包含 LFS 相关信息）：

[feature-bert-model 8a7b3c9] feat: 用 Git LFS 提交 bert 模型文件（385MB）
 2 files changed, 1 insertion(+)
 create mode 100644 .gitattributes
 create mode 100644 model/ai/bert_base_v2.bin

2. 推送分支到远程

# 推送当前分支（feature-bert-model）到远程
git push origin feature-bert-model

推送过程中，Git LFS 会自动将大文件上传到远程 LFS 服务器，终端会显示 LFS 上传进度：

Locking support detected on remote "origin". Consider enabling it with:
  $ git config lfs.https://code.example.com/your-repo.git/info/lfs.locksverify true
Uploading LFS objects: 100% (1/1), 385 MB | 5.2 MB/s, done.  # LFS 大文件上传成功
Enumerating objects: 10, done.
Counting objects: 100% (10/10), done.
Delta compression using up to 10 threads
Compressing objects: 100% (8/8), done.
Writing objects: 100% (9/9), 1.2 KB | 1.2 KB/s, done.
Total 9 (delta 3), reused 0 (delta 0), pack-reused 0
To code.example.com:your-repo.git
 * [new branch]      feature-bert-model -> feature-bert-model

关键验证：推送是否成功

• 若终端无 "文件超过 100MB 限制" 的错误，且显示 Uploading LFS objects: 100%，说明推送成功；
• 若仍报错 "blob 超过限制"，需检查本地分支历史是否残留大文件记录（参考文末 "常见问题" 部分）。

五、验证：确认大文件已被 LFS 管理

推送成功后，可通过以下命令验证大文件是否由 LFS 正确接管，避免后续出现隐患。

1. 查看本地 LFS 管理的文件

git lfs ls-files

若输出类似内容，说明大文件已被 LFS 管理：

a1b2c3d456 - model/ai/bert_base_v2.bin

2. 从远程拉取大文件（可选，验证协作可用性）

切换到其他目录克隆仓库，检查能否正常拉取 LFS 大文件：

# 克隆仓库
git clone https://code.example.com/your-repo.git
cd your-repo

# 切换到包含大文件的分支
git checkout feature-bert-model

# 拉取 LFS 大文件（若克隆时未自动拉取）
git lfs pull

拉取后查看文件大小，确认与原文件一致（385MB），说明 LFS 协作正常。

六、常见问题与解决方案

1. 推送时仍提示 "文件超过 100MB 限制"

原因 ：本地分支历史中残留大文件的普通 Git 记录（之前用普通 git add 提交过），远程检测到历史中的超限 blob。解决：清理分支历史中的大文件记录：

# 彻底删除历史中的大文件
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch model/ai/bert_base_v2.bin" \
  --prune-empty --tag-name-filter cat -- feature-bert-model

# 强制推送清理后的历史
git push origin feature-bert-model --force-with-lease

2. 克隆仓库后，大文件显示为 "链接" 而非实际文件

原因 ：克隆时未自动拉取 LFS 大文件，本地仅保留 LFS 引用链接。解决 ：执行 git lfs pull 手动拉取大文件。

七、总结

用 Git LFS 上传大文件的核心流程可总结为：

1. 安装并初始化 Git LFS；
2. 用 git lfs track 配置大文件追踪规则；
3. 解决 .gitignore 忽略问题（强制添加或修正 ignore）；
4. 提交并推送，LFS 自动上传大文件。

关键避坑点：确保大文件从一开始就用 LFS 管理 ，避免先用普通 Git 提交导致历史残留；遇到 ignore 报错时，优先用 git add -f 快速解决，无需修改原有 ignore 规则。按本文步骤操作，即可顺利绕过 Git 大文件限制，实现高效提交。