Git 大文件阻断推送的成因与历史重写修复

摘要

在前端项目中引入高分辨率图片后，一次 git push 先后表现出网络连接失败和远端拒绝两种现象。初步判断容易停留在网络、代理或 GitHub 服务状态层面，但在网络恢复后，远端返回了更明确的错误：仓库历史中存在超过 100 MB 的文件。本文以此问题为案例，分析 Git 中"工作区已删除文件"与"历史仍保留文件对象"之间的差异，说明 GitHub 的大小限制为何会继续阻断推送，并给出一种兼顾最终内容完整性、旧历史可恢复性以及远端兼容性的历史重建方案。

修复过程没有使用强制推送，而是在远端基线 58371a2 上创建一个新的提交 c587108。该提交包含当前项目的最终文件状态，但不继承那些曾引入原始超限图片的本地提交。原有三个未推送提交被保留在本地备份分支 backup/pre-push-rewrite 中。最终推送以普通快进方式完成，远端与本地 main 同步。本文进一步讨论该方法的适用边界、潜在风险，以及避免问题再次出现的工程约束。

关键词： Git；提交历史；对象可达性；大文件；GitHub；历史重写

1. 引言

在版本控制实践中，开发者通常更关注当前工作区是否干净，而较少检查历史提交是否仍然可达。当图片、视频或构建产物曾经进入提交，即使之后在工作区中删除，它们仍可能作为 Git 对象保留在提交图中。对于 GitHub 这类设置了单文件大小上限的平台，这种"当前不可见、历史仍存在"的状态会直接表现为推送失败。

本次问题发生在一次正常的站点内容更新中。图片资源经过压缩后，工作区目录已从约 275 MB 降至不足 1 MB，但推送仍然被远端拒绝。本文将依次回答三个问题：第一，为什么删除当前文件不能解决历史大文件问题；第二，如何在不对远端造成破坏的前提下恢复可推送状态；第三，新的提交流程在什么条件下仍然可能再次触发同样的问题。

2. 问题现象与定位

最初的错误信息为：

text 复制代码

fatal: unable to access 'https://github.com/...':
Failed to connect to github.com port 443

这一阶段表现为网络不可达。获得联网权限后继续推送，请求进入 GitHub 的服务端检查环节，错误随之变为：

text 复制代码

remote: error: File src/assets/images/awards/award-hnnu-1.png is 120.04 MB;
        this exceeds GitHub's file size limit of 100.00 MB
remote: error: File src/assets/images/awards/award-hnnu-2.png is 107.95 MB;
        this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected.

此时可以确认，问题并非单纯由网络造成。GitHub 在接受提交之前检查了待推送的对象，并发现两个超过限制的 PNG 文件。值得注意的是，当前项目目录中已经没有这两个文件，页面也已经改为引用压缩后的 JPG。因此，问题只能位于提交历史，而不是当前文件系统。

通过查看本地历史，可以得到操作前的结构：

text 复制代码

origin/main：58371a2
local main： 58371a2 → 4554ed1 → ab67672 → fcb3641

其中，4554ed1 和 ab67672 曾引入原始大图；fcb3641 虽然在最终树中删除了它们，但其父提交仍然保留了大文件对象。提交图并未因为最后一次删除而"忘记"此前的内容。

3. 机制分析

Git 的提交不是对当前目录的简单覆盖，而是由提交对象、树对象和文件对象共同构成的不可变快照。每个提交都记录父提交，并通过树对象描述当时的目录状态。只要一个提交可以从分支、标签或其他引用出发被遍历到，它和它引用的文件对象就仍然属于可推送历史。

因此，"在当前提交中删除文件"和"从历史中删除文件"是两个不同操作：

操作	当前工作区	当前提交树	历史对象
删除文件并提交	文件消失	文件消失	旧提交仍保留
改写历史	文件消失	文件消失	可达历史中不再包含

当执行 git push origin main 时，Git 会发送从 main 可达、且远端尚未拥有的对象。若 main 的历史仍指向包含大文件的旧提交，GitHub 就会在这些对象到达服务端前执行限制检查并拒绝整个推送。

这里可以采用"引用到对象"的可达性视角理解。操作开始时，main 和备份目标都指向旧的提交链：

text 复制代码

main → 58371a2 → 4554ed1 → ab67672 → fcb3641

目标不是修改远端已有历史，而是让 main 从远端基线重新出发，同时保留当前工作区的最终内容。只要新提交的父节点是 origin/main，远端就可以通过普通快进完成更新。

4. 修复方案

4.1 设计原则

修复过程遵循三个原则：第一，不改变当前页面所需的任何文件；第二，在重写本地 main 前保留旧提交入口；第三，不强制覆盖远端历史。由于这些提交尚未推送，对本地历史进行重建不会影响其他协作者。

4.2 保存旧历史

首先在当前 HEAD 上创建备份分支：

bash 复制代码

git branch backup/pre-push-rewrite

该命令不复制文件，也不改变当前分支，只为旧提交链增加一个名称。此时即使 main 随后被移动，旧链仍可通过 backup/pre-push-rewrite 访问。

4.3 将 main 移回远端基线

确认工作区处于干净状态后，执行：

bash 复制代码

git reset --soft origin/main

--soft 只移动分支指针，不修改工作区，也不清空暂存区。因此，压缩后的图片、页面改动和其他最终文件都被完整保留，只是 main 不再以包含大图的三个提交为祖先。

这一步容易被误解为"删除提交"。严格来说，旧提交并没有立即消失，而是由备份分支继续引用；main 只是改从 origin/main 继续生长。

4.4 重建一个干净的提交

基于当前暂存内容创建新提交：

bash 复制代码

git commit -m "feat: 完善XXX展示并压缩图片资源"

得到新提交 c587108。它不是 git merge 生成的合并提交，也不是对三个旧提交的逐条重放，而是把三个提交共同形成的最终文件状态重新保存为一个提交。其父节点为 58371a2，因此新的历史为：

text 复制代码

origin/main：58371a2
local main： 58371a2 → c587108

此时 main 的可达历史中只包含压缩后的 JPG，不包含原始 PNG。

4.5 普通推送

最后执行：

bash 复制代码

git push origin main

远端已有的 58371a2 仍是新提交的父节点，因此 Git 可以进行普通的快进更新，而不需要 --force。推送完成后，远端与本地历史一致：

text 复制代码

main / origin/main → 58371a2 → c587108

5. 结果

修复后，远端 main 从 58371a2 快进到 c587108，工作区保持干净，本地与远端分支同步。原来的三个未推送提交仍保存在本地备份分支中：

text 复制代码

main / origin/main        → 58371a2 → c587108
backup/pre-push-rewrite   → 58371a2 → 4554ed1 → ab67672 → fcb3641

这种方式同时满足了三个目标：页面最终内容未发生回退；远端历史没有被强制覆盖；旧提交仍可在本地恢复。需要说明的是，本地 .git 目录仍会保留旧对象，直到备份分支被删除、Reflog 过期并执行垃圾回收。因此，"推送成功"和"本地旧对象被物理删除"并不是同一件事。

6. 讨论与风险边界

该方法适用于"含大文件的提交尚未推送，且只存在于本地"的情形。如果旧提交已经进入共享远端，直接改写历史可能影响其他协作者，应改用 Git LFS、git filter-repo 或 BFG Repo-Cleaner，并事先协调所有使用该仓库的人员。

即使当前 main 已经干净，以下操作仍可能重新暴露旧历史或引入新的超限文件：

执行 git push --all，尝试推送备份分支。
将旧提交重新合并进 main。
推送仍指向旧提交的标签。
从旧提交创建新分支并继续开发。
再次提交单张超过 100 MB 的文件。

若不再需要旧历史，可以在确认备份价值已经消失后删除备份分支，并清理 Reflog 与不可达对象：

bash 复制代码

git branch -D backup/pre-push-rewrite
git reflog expire --expire=now --all
git gc --prune=now

这组命令具有不可逆性。执行后，旧提交可能无法再次恢复，因此应在确认远端内容完整、本地没有遗漏之后再进行。

对于图片资源本身，更稳妥的长期策略是：在提交前限制分辨率与文件体积；证书照片优先使用压缩后的 JPEG 或 WebP；将原图与网页资源分开保存；必要时使用 Git LFS。这样可以减少历史清理的频率，也能避免仓库体积随着素材增加而持续膨胀。

7. 结论

本次推送失败表面上经历了"网络不可达"和"远端拒绝"两个阶段，但根本原因是本地提交历史中的超大文件违反了 GitHub 的单文件限制。仅删除当前文件、修改页面引用或压缩工作区资源，都不足以改变历史对象的可达性。

通过在保存旧历史的前提下，将 main 软重置到远端基线，并以最终文件状态创建新的提交，可以在不强制覆盖远端的情况下恢复普通快进推送。该方法兼顾了当前内容、远端兼容性和本地可恢复性，但其适用范围严格限定于尚未共享的本地历史。理解提交图与对象可达性，比记住某一条修复命令更重要。