本文介绍了在 GitHub 推送超过 100MB 文件时的限制及错误处理方法。主要提供两种解决方案：一是使用 Git LFS 管理大文件，通过迁移历史将大文件替换为指针；二是使用 filter-repo 或 BFG 工具彻底移除历史中的大文件记录，或分割文件存储于外部。操作涉及重写 Git 历史，需强制推送并通知协作者注意分支保护规则。
当你执行 git push 时，可能会遇到类似以下错误提示：
remote: error: File data/wmt_zh_en_training_corpus.csv is 1968.67 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.
! [remote rejected] master -> master (pre-receive hook declined)
GitHub 对单个文件的大小限制为 ≤ 100MB。即使你在后续提交中删除了该大文件，它在 Git 的历史记录中仍然存在，导致推送失败。解决此问题的关键在于清理仓库历史中的大文件记录，或者使用 Git LFS（Large File Storage）来管理大文件。
Git LFS 的核心思想是将仓库中的大文件替换为轻量级的指针文件，实际的大文件内容则存储在远端的 LFS 服务器上。这样，你的 Git 仓库体积就能保持轻量。
安装完成后，在终端（命令行）中执行一次全局初始化：
git lfs install
假设你的大文件是 .csv 格式（请根据实际情况替换扩展名或路径），使用以下命令跟踪：
git lfs track "*.csv" # 或者精确指定文件路径
# git lfs track "data/wmt_zh_en_training_corpus.csv"
此命令会在你的仓库根目录生成或修改 .gitattributes 文件。必须将此文件加入版本库并提交：
git add .gitattributes
git commit -m "chore: 配置 Git LFS 跟踪 csv 文件"
由于大文件已经存在于之前的提交历史中，我们需要使用 git lfs migrate 命令重写历史，将这些文件替换为 LFS 指针：
git lfs migrate import --include="data/wmt_zh_en_training_corpus.csv" --everything
--include：指定要转换的文件路径（支持逗号分隔多个文件，也支持通配符 *）。--everything：转换所有分支和标签的历史记录。执行后，验证迁移结果：
git lfs ls-files # 应列出被 LFS 管理的文件
由于本地仓库的历史记录已被重写，必须使用 --force 选项覆盖远程仓库的分支：
git push origin master --force
master）设置了保护规则，你可能需要先在 GitHub 仓库的 Settings → Branches 中临时禁用分支保护，才能执行强制推送。也可以尝试使用更安全的 --force-with-lease。其他协作者在拉取更新前，需要执行：
git fetch --all
git reset --hard origin/master # 强制将本地分支重置到远程状态
或者，更推荐的做法是让协作者重新克隆仓库（git clone），以确保历史记录完全一致。克隆后，使用 git lfs pull 来拉取 LFS 管理的实际文件内容。
如果不想使用 Git LFS，或者文件过大超出 LFS 配额限制，可以考虑以下方法。⚠️ 注意：这些方法会丢失该大文件在 Git 中的版本历史，仅保留最后一次提交的快照。
git filter-repo / BFG)使用强大的 git filter-repo 工具（需单独安装）从所有历史提交中删除指定的大文件：
git filter-repo --path data/wmt_zh_en_training_corpus.csv --invert-paths
git push --force)。split 命令或 Windows 的 7-Zip）将大文件分割成多个小于 100MB 的分片文件（例如 file.part1, file.part2）。README.md 文件说明如何合并这些分片（例如使用 cat file.part* > original_file 或 7-Zip 解压）。git lfs migrate 或 git filter-repo 等工具重写历史才能彻底解决。git push --force) 会覆盖远程历史。务必通知所有协作者。建议他们备份本地更改后，重新克隆仓库 (git clone)，或者极其谨慎地使用 git fetch --force 配合 git reset --hard。master）在 GitHub 上受保护，默认禁止强制推送。需要在仓库的 Settings → Branches 中临时调整分支保护规则，或者使用 --force-with-lease（它会在覆盖前检查远程分支是否是你期望的状态，相对安全一些）。如果你刚刚不小心提交了一个大文件，并且还没有进行任何 git push 操作，也没有其他协作者拉取过你的这次提交，那么一个简单的回退方法是：
git reset --soft HEAD~1 # 撤销上一次提交，但保留工作区的文件改动
撤销后，你可以按照方案一的步骤（安装 LFS、跟踪文件、添加 .gitattributes、提交），或者用 git rm --cached 彻底移除大文件（如果不需要它）后再做一次新的提交。然后正常推送（无需强制）。
# 1. 初始化 LFS
git lfs install
# 2. 跟踪大文件 (以 .csv 为例，根据实际情况修改)
git lfs track "*.csv"
git add .gitattributes
git commit -m "setup lfs"
# 3. 迁移历史中的大文件 (替换路径)
git lfs migrate import --include="data/*.csv" --everything
# 或者只针对单个文件
# git lfs migrate import --include="data/wmt_zh_en_training_corpus.csv" --everything
# 4. 强制推送
git push origin master --force
# 5. 验证
git lfs ls-files
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online