很多团队在项目早期会把前端构建产物（例如 dist/、build/、web/assets/）直接提交进仓库。短期看省事，但随着版本迭代，这些产物会在历史里不断重复出现，让仓库变得越来越大：克隆慢、CI 慢、拉分支也慢。
这篇文章整理一套通用做法：既把仓库体积真正降下来，也避免以后再膨胀。
一、先搞清楚：删文件为什么不一定能让仓库变小？
你在当前分支里把 dist/ 删除、再提交一个 commit，这只能说明“从现在开始不再包含它”。
但 Git 的体积主要来自 历史对象：只要这些大文件或构建产物曾经被提交过，它们通常仍然存在于历史里（blob/tree/commit 对象）。所以仓库想真正变小，关键是：
把这些路径从历史中移除（重写历史）
然后再做一次 GC（垃圾回收） 让对象真正被清理掉
二、动手前的注意事项（很重要）
“重写历史”意味着：
分支/标签对应的 commit SHA 会变化
旧 PR 里引用的 SHA 可能失效
协作者需要重新同步（最省事是重新 clone）
因此建议在开始前做两件事：
给远端做备份（例如 fork 一份或建一个
repo-backup）找个维护窗口执行（避免有人在你强推时继续推提交）
三、找出体积大户（可选，但很有帮助）
下面这段命令能帮助你确认到底哪些文件在“吃空间”。
git clone --mirror <REPO_URL> repo.git
cd repo.git
git count-objects -vH
# 查看最大的对象（git 新版本效果更好）
git rev-list --objects --all \
| git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
| sort -k3 -n \
| tail -100
一般会看到两类常见问题：
构建产物：
dist/、build/、web/assets/、.next/、coverage/……误提交的大文件：比如某个二进制、压缩包、日志包、数据库文件等
四、推荐方案：用 git filter-repo 清理全历史（最通用、也最稳）
git filter-repo 是现在更推荐的历史清理工具（相比老的 filter-branch 更快更安全）。
1) 镜像克隆（建议用 mirror）
git clone --mirror <REPO_URL> repo.git
cd repo.git
2) 安装 git-filter-repo
pipx install git-filter-repo || python3 -m pip install --user git-filter-repo
3) 从历史中删除构建产物目录（示例）
假设你希望移除 dist/ 与 build/：
git filter-repo \
--path dist \
--path build \
--invert-paths
如果你还要顺手删掉某个误提交的大文件（示例叫 bigfile.zip）：
git filter-repo \
--path dist \
--path build \
--path bigfile.zip \
--invert-paths
小提示：
--invert-paths的意思是“这些路径不要，其余都保留”。
4) 让体积真正收缩：GC
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git count-objects -vH
5) 强推回远端（历史已改写）
git remote add origin <REPO_URL>
git push --force --mirror origin
五、避免以后再犯：忽略规则 +（可选）CI 卡口
1) .gitignore（阻止未来再提交产物）
在正常工作仓库（不是 --mirror 那个）里加上常见规则：
dist/
build/
web/assets/
.coverage/
coverage/
node_modules/
*.log
*.zip
*.tgz
提交即可：
git add .gitignore
git commit -m "chore: ignore build artifacts"
git push
2) CI/钩子（可选，但很推荐）
如果团队曾经反复把产物提交进来，可以加两类约束：
禁止特定目录（例如
dist/）出现在 PR 变更里限制单文件大小（例如超过 10MB 直接失败）
这样就算有人误操作，CI 也会及时拦住。
六、协作者同步方式（重写历史后必须处理）
最省心：重新 clone。
如果不想重拉，可以用“重置到远端”的方式（以 main 为例）：
git fetch --all --prune
git checkout main
git reset --hard origin/main
git clean -fd
个人分支如果有未合并的工作，通常建议：
先把改动
cherry-pick到新历史上或把本地分支
rebase到新main（视团队习惯）
七、构建产物更适合放哪里？
如果现在仓库的定位是“只放源码”，构建产物通常更适合：
GitHub Releases 的 assets（按版本挂载）
制品仓库/包管理（npm/pnpm registry）、Docker 镜像仓库
真需要 Git 管理大文件：Git LFS（但如果历史里已经塞过大文件，仍要先做迁移/重写）
八、快速检查清单
已备份远端
已确认需要清理的目录/文件
使用
git filter-repo清理历史运行
git gc收缩对象git push --force --mirror推回远端添加
.gitignore与（可选）CI 检查通知协作者重新 clone 或 reset 同步