企业官网建设流程全解析

前几天在某个内部项目里，提交代码的时候突然弹出一串报错，提示大文件超过限制，推送被远程仓库拒绝。更麻烦的是本地提交记录已经写好了，工作区里还堆着一堆改动，整个提交流程被卡死。这类问题几乎每个用过git的人都会撞上一次，尤其是当项目里不小心混入了安装包、素材文件或者构建产物的时候。这篇内容就围绕“git提交大文件出错后，如何继续提交代码”这个场景，把报错原因、紧急处理、历史清理和预防手段一次讲清楚，适合刚接触git的开发者，也适合团队里负责维护仓库的老手参考。

1. 先搞明白：大文件提交为什么会把仓库搞崩

1.1 git大文件提交失败的4种典型报错

我统计了一下自己遇到和帮同事处理过的大文件提交报错，最常见的有这几种形态：

1. error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413
2. fatal: the remote end hung up unexpectedly
3. remote: error: File xxx.zip is 234.00 MB; this exceeds the file size limit
4. remote rejected (pre-receive hook declined)

这些报错不一定会直接写明“文件太大”。第一种是HTTP层报错，说的是请求体超过服务器能接受的长度；第二种是连接被中断，通常是传输数据量过大导致连接超时或被服务端掐断；第三种最直白，远程仓库明确告诉你某个文件超限；第四种则是服务端钩子主动拒绝了这次推送，可能是文件大小，也可能触发的是其他规则。

拿到报错先别慌，第一件事是看两处：报错里有没有点名具体文件，报错发生在本地还是远端。如果出现了具体文件名，那基本就是大文件问题跑不了；如果只有“hung up unexpectedly”这种话，说明传输层已经扛不住了，大概率也是因为对象体积过大。

1.2 git为什么对大文件这么敏感

git的设计核心是快照。每次commit，git都会把文件内容以完整对象的形式写入对象库，而不是只记录“这次改了什么”。文件一旦被提交进去，.git目录里就躺着这个文件的一个完整副本，后续无论哪个协作者clone、pull、push，都可能需要把这个对象整体传输一遍。

用一个生活化的类比来说：git的每个提交就像你出一次门就得把整个行李箱带一遍，哪怕这次只是改了一个标点，行李箱也得跟着跑。普通源代码文件体积小，带就带了，没什么感觉；但当行李箱里塞进去一个5GB的安装包，每次出门都要拖着它跑，问题就来了。

还有一个很多人不太注意的点：git本身并不“排斥”大文件，本地提交一个5GB的文件，git也能老老实实存下。真正的限制来自远程仓库和传输层。代码托管平台出于存储成本、带宽和服务器安全考虑，都会设置单文件大小上限，HTTP服务器和负载均衡层也会限制请求体大小。所以“提交失败”本质上是协作链路上某一环不让你这么干，而不是git本地出了问题。

1.3 大文件是怎么混进提交的

结合我见过的情况，大文件混进项目的原因无非这几种：

• 用git add .一把梭，把dist、build、node_modules这种目录顺手加进去，里面往往藏着本地构建产物和依赖包。
• 项目里放了数据集、模型权重、音视频素材或离线安装包，一开始觉得“反正没多大”，过段时间就失控了。
• 从网上下载的素材压缩包，解压之后忘记删掉压缩包本体，一个几百MB的文件就这样留在了项目目录。
• 项目压根没有建.gitignore，或者建了但规则写得过于宽松，没能拦住某些特定类型的文件。
• IDE的本地缓存、临时文件、数据库导出文件被当作“代码”提交了。

说到底就是一句话：没有在提交之前设防。后面第4部分会详细讲怎么把防线补上，这里先记住一条原则——任何超过几十MB的文件，都不应该出现在git仓库里。

2. 紧急止血：先让当前提交恢复正常

2.1 提交还没推送时的处理方式

如果你只是本地commit了，还来得及撤销，这是最理想的情况。操作顺序我建议这样：

1. 先确认当前状态，不要乱敲命令。
2. 执行git reset --soft HEAD~1，把刚才的提交撤掉，但保留所有文件改动。
3. 用git rm --cached 大文件名把大文件移出暂存区。
4. 把大文件物理移动到项目目录之外，或者加入.gitignore。
5. 重新git add需要提交的文件，重新git commit。

这里重点解释一下为什么用--soft而不是--hard。--hard会把工作区的文件改动直接丢掉，如果你辛苦写了一天代码，一个回车下去全没了，想哭都来不及。--soft只移动HEAD指针，暂存区和工作区都不动，安全得多。至于--mixed（默认参数），它会同时把暂存区也重置掉，意味着所有文件都要重新add，没必要多此一举。

还有一个小场景：如果你只是git add了文件但还没commit，那就更简单，直接git rm --cached 大文件名，然后重新提交暂存区里的其他文件即可，不需要走reset。

2.2 提交已经推送但被拒绝时的处理方式

如果推送被远端拒绝，很多人会慌，其实这时候情况比想象中简单。推送失败意味着远端没有接受到这条提交记录，本地commit还在，远程分支没有变化。处理方式跟2.1完全一样：先git reset --soft HEAD~1，移出大文件，重新提交，再推送。

唯一需要确认的是远端确实没有产生这次提交。有一种比较尴尬的情况是推送前一半失败了，但服务端已经接收了一部分对象，虽然分支没有更新，对象库里却残留了无用的大文件对象。这种情况单靠本地清理解决不了，需要联系管理员做对象库清理，或者等gc自动回收。不过对开发者个人来说，先把本地仓库弄干净、把代码推上去才是眼前最重要的事。

注意：如果大文件已经推送到远端（哪怕只是一次失败的推送），光改当前提交是不够的，历史里仍然会有它的身影。要么接受仓库体积膨胀，要么狠下心做一次历史重写，这就是下一部分要讲的内容。

2.3 提交前检查文件列表的好习惯

处理妥当前面几步之后，我强烈建议你养成一个习惯：每次commit之前，先看一眼git status列出来的待提交文件，再确认一下git diff --stat，看看这次改动涉及哪些文件、规模多大。很多人用了git add -A之后根本不看结果，直到推送被拒才知道有大文件混进去了。事实上，只要在commit之前多花十秒钟扫一眼，绝大多数问题都能在源头拦下。

3. 彻底清理：把大文件从git历史中连根拔起

3.1 先找出历史里的大文件对象

如果大文件已经提交过，哪怕后续commit把文件删了，git历史里仍然保存着那个对象。仓库体积不会因为后来的删除而变小，这才是最麻烦的地方。要彻底解决，必须重写历史，把大文件对象从所有提交中抹掉。

动手之前，先确认仓库里到底藏了哪些大文件。我用的命令是：

git rev-list --objects --all | \ git cat-file --batch-check='%(objectname) %(objecttype) %(objectsize) %(rest)' | \ awk '$2 == "blob" && $3 > 52428800 {print $0}'

这条命令会把所有超过50MB的blob对象列出来，包括文件路径和大小。52428800就是50MB的字节数（50 * 1024 * 1024）。如果你怀疑大文件不止一个，可以把阈值调低，比如20MB，先摸个底。

另外还有一个更直白的方式：在本地仓库目录直接跑du -sh .git，如果发现.git目录体积远超代码总量的合理范围，那基本可以断定历史里有大文件了。

3.2 用git filter-branch清理（兼容老环境）

查出大文件之后，最传统的方法是用git filter-branch重写历史。基本命令是这样：

git filter-branch --index-filter \ 'git rm --cached --ignore-unmatch 大文件名' \ --prune-empty -- --all

解释一下几个参数的作用：

• --index-filter：只修改索引信息，不实际检出文件，运行效率高。
• --ignore-unmatch：如果某些提交里不存在该文件，不会报错中断。
• --prune-empty：清理掉因为移除大文件而变空的提交。
• -- --all：表示对全部分支执行。

这个方法能解决问题，但我还是提醒一句：官方文档明确提示filter-branch存在很多使用陷阱，运行速度也慢，如果仓库历史很深、提交很多，可能要等很久。所以在团队环境里我一般不建议用它，除非你的git版本太老、装不了更好的工具。

3.3 用git filter-repo清理（推荐方案）

我自己现在基本只用git filter-repo，这是一个专门用于git历史重写的工具，比filter-branch安全、速度快，设计上也更合理。安装方式：

pip install git-filter-repo

运行前务必先备份原始仓库，防止重写出问题没法回退。备份用mirror克隆：

git clone --mirror 原仓库地址 backup.git

清理大文件的命令极简：

git filter-repo --path 大文件相对路径 --invert-paths

--path指定要删除的路径，--invert-paths表示只保留“除了这个路径之外”的其他所有内容，也就是专门删掉这个大文件。执行过程中会自动重写所有涉及该文件的历史提交。

一个很关键的点：git filter-repo会把当前的remote配置删除，因为它认为“仓库已经被重写，旧的remote指向已经没有意义”。所以重写完之后，需要手动重新关联远程地址：

git remote add origin 仓库地址 git push origin --force --all

如果还有标签，也要推送一下：

git push origin --force --tags

3.4 清理后的推送与协作注意事项

--force推送会覆盖远端分支的历史，这不是一个轻松的决定，因为所有基于旧历史开发的人都会受到影响。实际操作时，这几条一定要做到位：

• 提前通知团队人员，约定一个时间窗口，让大家在窗口内不要往目标分支推送任何内容。
• 重写历史之前，在本地把当前HEAD和关键分支的引用记录下来，或者做一次mirror备份，万一出问题还能回滚。
• 推送完成后，让协作者不要执行git pull，而是直接重新clone仓库。原因很简单，旧历史和新历史已经分叉，pull会尝试合并两条完全不同的提交线，产生一堆莫名其妙的冲突。
• 如果远端配置了分支保护规则，force push会被拒，需要临时放开权限，推送完成后再重新加上。

另外建议在重写之前先导出一份完整备份的裸仓库，我是习惯性这么做的。虽然多数时候根本用不上，但一旦中途断电或者误操作，这份备份就是救命稻草。

4. 止损方案：以后怎么避免再踩坑

4.1 .gitignore规则怎么写得更稳

大文件问题的根源往往是.gitignore没写好。一份能挡住常见大文件的规则，至少要覆盖这些类别：

# 构建产物 build/ dist/ target/ out/ # 依赖目录 node_modules/ vendor/ Pods/ # 压缩包与镜像 *.zip *.tar.gz *.rar *.7z *.iso # 音视频文件 *.mp4 *.mov *.avi *.wav # 数据库与日志 *.sql *.log *.bak # 模型权重和数据集 *.h5 *.pkl *.onnx *.pt

写完规则之后要验证一下效果：新建一个大文件放到项目里，跑git status，如果它没有出现在未跟踪列表里，说明规则生效了。还有一个容易忽略的坑：如果文件已经被git跟踪，.gitignore对它没有作用。所以前面要先执行git rm --cached，把它移出版本控制，再靠ignore规则阻止后续重新加入。

4.2 提交前快速自查的工具与习惯

就我自己而言，每次代码提交前习惯跑三道检查：

git status git diff --stat find . -type f -size +50M -not -path './.git/*'

第一道看有哪些文件会被提交，第二道看改动文件的规模和数量，第三道直接在项目目录里扫出所有超过50MB的文件。三道检查本身都不耗时，加起来不到一分钟，但能拦下绝大多数大文件事故。

如果团队协作人数多，想把这件事制度化，可以引入pre-commit钩子。用pre-commit框架的话，配置一个local仓库的钩子，检查待提交文件的大小：

- repo: local hooks: - id: forbid-large-files name: forbid large files entry: > awk '{ if (NR > 2 && $4 >= 52428800) exit 1 }' language: system files: ''

简单粗暴的实现方式就行，不需要搞得太复杂。核心目标只有一个：超过阈值就直接拒绝提交，从流程上杜绝大文件进入版本库。

4.3 Git LFS到底要不要上、什么时候上

很多人一提到大文件问题就想到Git LFS，但实际上LFS不是万金油。先理解它的原理：启用LFS之后，git仓库里保存的只是一个文本指针，真正的文件内容被存到单独的LFS存储服务中。克隆仓库时默认只拉取指针，只有在需要时（比如检出某个版本）才会去拉取真实文件，这样仓库体积和传输压力都大幅下降。

那到底要不要上LFS？我的建议是分场景判断：

• 如果项目需要长期维护大量体积大、频率高的二进制资产，比如游戏美术资源、音频素材、大型数据集，那么LFS是合适的。
• 如果只是某次误提交了一个安装包，清掉就好，完全没必要为了一锤子买卖引入一套LFS，因为LFS本身有存储配额限制，还要求所有协作者安装对应插件，增加协作成本。
• 如果团队里有同学经常把素材丢进代码仓库，那与其上LFS，不如先把流程约束做好，用.gitignore和pre-commit钩子防止误提交。

如果决定上LFS，要注意在.gitattributes里声明哪些文件类型走LFS管理，比如：

*.psd filter=lfs diff=lfs merge=lfs -text *.mp4 filter=lfs diff=lfs merge=lfs -text

声明之后，所有协作者都要统一安装git-lfs插件，并且在第一次clone时执行git lfs install。

5. 常见问题与排查技巧实录

5.1 报错“RPC failed; HTTP 413 curl 22”

这个报错几乎是大文件推送的代名词。HTTP 413表示请求体太大，服务器拒绝处理。先别急着调整各种参数，按顺序排查：

1. 确认是不是某次提交引入了大文件，先本地查清楚。
2. 把协议换成SSH试一次。SSH不走HTTP层，很多413问题因此直接消失。
3. 如果还是要用HTTP协议，可以调大本地HTTP缓冲区：

   git config http.postBuffer 524288000

   这个设置把缓冲区从默认值调大为500MB，但注意这只是缓冲区大小，不是传输上限，文件本身超限依然会被拒。
4. 如果问题在代理或网关层，检查一下是否有网络代理干扰了请求体大小。

排查到最后，大概率还是要回到“移除大文件”这条路。

5.2 报错“remote rejected (pre-receive hook declined)”

这种属于服务端钩子主动拦截，常见于团队配置了自定义校验脚本。钩子被触发时，远端不会告诉你具体是哪条规则没有通过，只会甩一句“declined”。

排查思路是先确认是不是大文件导致的。最简单的办法：看看本地最近的提交里有没有可疑的大文件，用git log --stat结合文件大小检查。如果确认是钩子拦大文件，解决办法只有一个——把文件从提交历史中彻底移除。不要试图绕过钩子，那只会让问题越滚越大，等你下次推送时还是会卡住。

5.3 重写历史后同事的代码冲突了怎么办

这是force push之后最常出现的连锁反应。同事基于旧历史创建了分支，你重写历史之后，对方本地仓库里的旧分支和远程新历史之间没有共同基线，git pull会很难看。

最稳妥的做法是让同事放弃旧分支，重新基于新历史做开发。如果对方在旧分支上有尚未推送的本地提交，先把这些提交找出来，然后通过cherry-pick把它们逐个挂到新历史的对应位置上：

git fetch origin git checkout -b new-feature-branch origin/新分支 git cherry-pick 旧分支上的提交哈希

整个过程要提前沟通好，别让大家在同一时间对同一分支操作，否则又是一场事故。

5.4 误用reset删了提交怎么恢复

清理历史的过程中，偶尔会有人手滑用了git reset --hard，把一个还不想丢的提交给删掉了。这时候git reflog就是救命工具：

git reflog git reset --hard HEAD@{n}

reflog会记录HEAD指针的每一次移动，只要操作记录还在，就能用对应的索引恢复。有一点要注意：reflog默认保留一定时间，过期的记录可能被清理，所以误操作之后要尽快处理，别拖两天再想起来。

5.5 重写历史后仓库体积还是很大

有时候filter-repo或者filter-branch执行完了，提交历史里确实看不到大文件了，但.git目录体积没怎么降。这是因为旧的pack文件还残留在对象库里，只是没有被引用而已。需要手动做一次彻底回收：

git reflog expire --expire=now --all git gc --prune=now --aggressive

第一行让所有reflog条目立即过期，第二行触发垃圾回收，把所有没有被引用的对象从对象库中清除。这两步执行完之后，仓库体积会真正降下来。注意操作之前先在别的目录留一份备份，因为这两条命令一旦执行，被回收的对象就找不回来了。

踩过几次大文件提交的坑之后，我最大的体会是：不要等大文件推送到远端之后，再想着用各种“巧妙”的参数绕过限制。绕来绕去，最后你还是得回到清理历史这条路上。与其这样，不如把功夫花在提交之前的预防上。我个人现在写任何项目的第一步就是配置好.gitignore，提交之前扫一眼git status，看到不该出现的文件先停下来问一句这是什么东西。还有一个小习惯非常管用：给项目里所有超过阈值的文件建一份清单，定期用find命令扫一遍，从源头上杜绝大文件接近版本库的机会。真遇到问题时，记住顺序——先备份、再操作、后推送，按这个节奏来，大部分事故都能平稳解决。