GitHub 项目整体替换与大文件处理指南

本文适用于以下情况：

GitHub 上已经有旧版本项目；
电脑上有一套新的完整项目；
希望让原仓库的 main 分支显示新版内容；
同时希望保留旧版本和原有提交历史；
项目中可能存在超过 50 MB 的文件。

推荐做法：不要删除 GitHub 仓库，也不要直接强制覆盖历史。先给旧版本创建备份分支，再在 main 上提交一次"整体替换"。

一、准备工作

1. 安装并确认 Git

打开 PowerShell、终端或 Git Bash，执行：

bash 复制代码

git --version

如果能够显示版本号，说明 Git 已安装。

2. 准备三个通用变量

后续示例使用以下占位名称，请替换成自己的实际信息：

仓库地址：例如 https://github.com/用户名/仓库名.git
新版项目目录：电脑上新版项目所在目录
上传工作目录：用于克隆旧仓库的一个新目录

建议不要直接在唯一一份新版项目中试验。使用单独的"上传工作目录"，可以避免误删本地源码。

3. 上传前检查敏感内容

确认项目中没有准备公开的以下内容：

.env 中的真实 API Key；
Token、密码、私钥、证书；
数据库连接密码；
云服务凭证；
配置文件中直接写入的密钥；
用户数据、日志或隐私数据。

常用 .gitignore 示例：

gitignore 复制代码

node_modules/
dist/
build/
coverage/
tmp/
*.log

.env
.env.*
!.env.example

.DS_Store
Thumbs.db

.env.example 可以上传，但里面只能放变量名和示例占位值，不能放真实密钥。

二、推荐流程：保留旧版本并整体替换 `main`

第 1 步：克隆原 GitHub 仓库

在一个合适的父目录执行：

bash 复制代码

git clone https://github.com/用户名/仓库名.git 上传工作目录
cd 上传工作目录

注意：克隆地址以 .git 结尾，不要使用带 /tree/main 的网页地址。

第 2 步：备份旧版本

切换到原来的主分支：

bash 复制代码

git switch main

创建旧版本备份分支，并上传到 GitHub：

bash 复制代码

git branch archive-v1
git push origin archive-v1

archive-v1 可以改成更明确的名称，例如：

text 复制代码

archive-v1-before-v2
archive-2026-08-11
legacy-version

上传成功后，可以先在 GitHub 的 Branches 页面确认备份分支已经存在。

第 3 步：清除旧版的已跟踪文件

确保终端当前确实位于"上传工作目录"，然后执行：

bash 复制代码

git rm -r .

这一步只是在准备下一次提交；在执行 git commit 和 git push 之前，GitHub 上的内容不会改变。

第 4 步：复制新版项目

把新版项目文件复制到上传工作目录中，但不要复制以下内容：

.git/
.env
node_modules/
dist/、build/
coverage/
临时目录和日志

Windows PowerShell 可以使用：

powershell 复制代码

robocopy "新版项目目录" "上传工作目录" /E /XD .git node_modules dist build coverage tmp /XF .env

robocopy 返回代码 1 通常表示成功复制了文件，并不代表失败。

macOS 或 Linux 可以使用：

bash 复制代码

rsync -av \
  --exclude='.git' \
  --exclude='.env' \
  --exclude='node_modules' \
  --exclude='dist' \
  --exclude='build' \
  --exclude='coverage' \
  --exclude='tmp' \
  新版项目目录/ 上传工作目录/

也可以手动复制，但一定不要覆盖上传工作目录中的 .git 文件夹。

第 5 步：检查即将上传的内容

bash 复制代码

git add -A
git status

重点确认：

.env、密钥和密码没有出现；
node_modules、编译产物和临时文件没有出现；
应当删除的旧文件显示为 deleted；
新版文件显示为 new file 或 modified；
没有意外的大文件。

如果发现不该上传的文件：

把相应规则加入 .gitignore；
执行 git restore --staged 文件路径 取消暂存；
再次执行 git status 检查。

第 6 步：提交新版

bash 复制代码

git commit -m "feat: replace old version with new version"

第 7 步：上传到原仓库

bash 复制代码

git push origin main

完成后：

原仓库地址保持不变；
main 分支显示新版项目；
旧版保存在备份分支；
原有 Git 历史仍然可以查看。

三、如果 `main` 分支不允许直接上传

如果 GitHub 提示主分支受到保护，不要使用强制推送。创建新版分支：

bash 复制代码

git switch -c release-new-version
git push -u origin release-new-version

然后在 GitHub 上创建 Pull Request：

text 复制代码

release-new-version → main

检查无误后再合并。

四、单个文件超过 50 MB 怎么办

GitHub 对普通 Git 文件有以下重要限制：

超过 50 MiB：GitHub 会给出警告，仓库克隆和拉取也会逐渐变慢；
超过 100 MiB：普通 Git 推送会被 GitHub 拒绝；
大型二进制文件通常应使用 Git LFS，或者不放入源码仓库。

MB 和 MiB 略有差别。日常判断时可以近似理解为：超过 50 MB 就应该检查，接近或超过 100 MB 必须专门处理。

方案 A：文件不应该进入源码仓库

适合以下文件：

安装包、编译产物；
缓存、日志；
可重新下载的数据集；
自动生成的视频、音频、压缩包；
node_modules 等依赖目录。

把文件或目录加入 .gitignore：

gitignore 复制代码

large-data/
*.log
*.tmp
*.zip

如果文件已经被暂存：

bash 复制代码

git restore --staged 大文件路径

如果文件以前已经被 Git 跟踪，但希望保留本地文件：

bash 复制代码

git rm --cached 大文件路径

然后重新提交。

方案 B：使用 Git LFS

适合确实需要版本管理的大型二进制文件，例如：

模型文件；
PSD、视频、音频；
大型 PDF；
.zip、.bin、.onnx、.pt 等文件。

1. 初始化 Git LFS

先安装 Git LFS，然后在仓库目录执行：

bash 复制代码

git lfs install

2. 指定需要由 LFS 管理的文件类型

例如管理所有 .zip 文件：

bash 复制代码

git lfs track "*.zip"

也可以指定其他类型：

bash 复制代码

git lfs track "*.mp4"
git lfs track "*.onnx"
git lfs track "*.pt"

这会生成或修改 .gitattributes，必须一起提交：

bash 复制代码

git add .gitattributes
git add 大文件路径
git commit -m "chore: track large files with Git LFS"
git push origin main

Git LFS 有单独的存储和流量额度。上传大量文件前，应查看当前 GitHub 套餐的 LFS 配额。

方案 C：把大文件作为 Release 附件或放到外部存储

如果大文件只是供用户下载，而不需要参与每次代码克隆，可以考虑：

GitHub Releases 附件；
对象存储；
网盘或数据集托管平台；
在 README 中提供下载链接和校验值。

这种方式通常比把大文件直接放入 Git 历史更合适。

五、大文件已经提交后才发现怎么办

只把文件加入 .gitignore，不能清除它在旧提交中的历史记录。

情况 1：只存在于最后一次尚未推送的提交

先让 Git LFS 接管该类型，再重新暂存并修改最后一次提交：

bash 复制代码

git lfs track "*.大文件扩展名"
git add .gitattributes
git rm --cached 大文件路径
git add 大文件路径
git commit --amend --no-edit

然后正常推送。

情况 2：已经存在于多个提交或已经上传到远程

需要进行历史迁移，例如：

bash 复制代码

git lfs migrate import --include="*.大文件扩展名" --everything

这会重写 Git 历史，通常需要强制推送，并会影响其他协作者。执行前必须：

创建仓库备份；
通知所有协作者；
确认分支保护规则；
让协作者在迁移后重新克隆仓库。

不熟悉 Git 历史重写时，不建议独自执行。

六、常见问题

1. `git push` 要求登录

根据提示通过浏览器登录 GitHub，或使用 GitHub CLI：

bash 复制代码

gh auth login

GitHub 不再接受使用账户密码直接进行 Git 推送；HTTPS 通常使用浏览器授权或 Personal Access Token。

2. 提示远程包含本地没有的提交

先不要强制推送。执行：

bash 复制代码

git fetch origin
git status

确认是否有人在你克隆之后更新了远程仓库。必要时先合并最新改动，或重新克隆后再进行替换。

3. 上传错了文件

如果尚未执行 git push，可以修改暂存内容后重新提交。如果已经公开了 API Key，即使之后删除文件，也应立即在对应服务中撤销并重新生成密钥，因为密钥可能仍存在于 Git 历史中。

4. 是否应该使用 `git push --force`

正常的整体版本替换不需要强制推送。只有明确需要重写历史、已经做好备份并了解协作影响时才考虑使用。

七、最终检查清单

上传前逐项确认：

GitHub 项目整体替换与大文件处理指南