> 一文搞定 Git 仓库迁移，手把手教学，含常见问题和解决方案

在日常开发中，我们经常会遇到需要迁移 Git 仓库的场景：

  • 公司换了 Git 服务器（从 GitLab 迁到 Gitee，或者自建服务器迁移）
  • 代码仓库改名了
  • 从 HTTP 协议切换到 SSH 协议
  • 团队统一迁移到新的代码托管平台

今天我就来详细讲讲 Git 仓库迁移的几种方法，以及过程中可能遇到的坑和解决方案。

一、迁移前的准备工作

在开始之前，建议先做以下几件事：

1. 确认当前仓库状态

# 查看当前远程仓库地址
git remote -v

# 查看所有分支
git branch -a

# 查看最近的提交记录
git log --oneline -5

执行上述命令后，会看到类似下面的信息：

origin  https://old-server.com/repo.git (fetch)
origin  https://old-server.com/repo.git (push)
  main
  feature/login
  develop
abc1234 (HEAD -> main) 修复登录bug
def5678 添加用户模块
ghi9012 初始化项目

2. 确保工作区是干净的

git status

执行后应该看到：

nothing to commit, working tree clean

如果有未提交的修改，先提交或 stash 起来。

3. 备份当前仓库（可选但推荐）

# 直接把整个文件夹复制一份
cp -r your-repo your-repo-backup

二、方法一：直接修改远程地址（最常用）

这是最常规的方法，适用于新旧仓库代码一致的场景。

步骤 1：修改远程仓库地址

git remote set-url origin https://new-server.com/username/repo.git

步骤 2：验证修改是否成功

git remote -v

执行后输出：

origin  https://new-server.com/username/repo.git (fetch)
origin  https://new-server.com/username/repo.git (push)

步骤 3：推送所有分支和标签

# 推送所有分支
git push -u origin --all

# 推送所有标签
git push -u origin --tags

步骤 4：拉取验证

git pull

三、方法二：添加新远程，保留旧远程

如果你不想删除旧远程地址（比如需要保留备份），可以添加一个新远程：

# 添加新远程（不覆盖旧的）
git remote add new-origin https://new-server.com/username/repo.git

# 推送到新远程
git push -u new-origin --all
git push -u new-origin --tags

# 后续如果想切换默认远程
git remote set-url origin https://new-server.com/username/repo.git
git remote remove new-origin

这种方式的好处是：你可以同时向两个仓库推送代码，平滑过渡。

四、方法三：完整迁移（使用 –mirror）

这是最彻底的迁移方式，会复制包括 hooks、配置、所有引用在内的全部内容。

# 1. 克隆旧仓库的镜像（裸仓库）
git clone --mirror https://old-server.com/username/repo.git

# 2. 进入仓库目录
cd repo.git

# 3. 修改远程地址为新仓库
git remote set-url origin https://new-server.com/username/repo.git

# 4. 镜像推送到新仓库
git push --mirror

# 5. 清理临时文件
cd ..
rm -rf repo.git

注意：--mirror 会覆盖新仓库的所有内容，请确保新仓库是空的或者你确实想覆盖。

五、方法四：保留提交历史的合并迁移

如果新仓库已经有了提交，你想把旧仓库的代码合并到新仓库中：

# 1. 添加旧仓库为远程
git remote add old-origin https://old-server.com/username/repo.git

# 2. 拉取旧仓库的所有分支
git fetch old-origin

# 3. 切换到目标分支（比如 main）
git checkout main

# 4. 合并旧仓库的分支（允许不相关的历史）
git merge old-origin/main --allow-unrelated-histories

# 5. 处理可能的冲突后，推送到新仓库
git push -u origin main

六、各方法对比

方法适用场景优点缺点
方法一新旧仓库一致简单快速会覆盖旧远程配置
方法二需要同时保留新旧远程灵活，可双推需要多一步操作
方法三完整迁移，包括配置最彻底会覆盖新仓库所有内容
方法四新仓库已有代码可合并历史可能产生冲突

七、常见问题与解决方案

问题 1：认证失败（用户名/密码错误）

现象：

fatal: Authentication failed

解决方案：

# 方式一：在 URL 中嵌入用户名和密码（注意密码中的特殊字符要 URL 编码）
git remote set-url origin https://username:password%40encoded@server.com/repo.git

# 方式二：使用凭据管理器
git config credential.helper manager
git push  # 会弹窗让你输入密码

问题 2：SSL 证书错误

现象：

fatal: unable to access '...': SSL certificate problem

解决方案：

# 临时关闭 SSL 验证（仅用于测试）
git config http.sslVerify false

# 测试完后恢复
git config http.sslVerify true

问题 3：推送时提示 “remote: Repository not found”

原因：新仓库还没有创建，或者 URL 写错了。

解决方案：

  • 先去代码托管平台创建好空仓库
  • 确认 URL 是否正确（注意大小写和 .git 后缀）

问题 4：推送时提示非快进合并（non-fast-forward）

现象：

! [rejected] main -> main (non-fast-forward)

解决方案：

# 先拉取再推送
git pull origin main --rebase
git push origin main

# 或者强制推送（慎用！会覆盖远程历史）
git push -f origin main

问题 5：密码中有特殊符号导致 URL 解析失败

常见特殊字符编码对照表：

字符URL 编码
@%40
/%2F
,%2C
:%3A
#%23
&%26
?%3F

示例：密码 abc@123/ 编码后为 abc%40123%2F

八、迁移后的收尾工作

1. 验证迁移结果

# 查看远程地址
git remote -v

# 查看所有分支
git branch -a

# 查看最近的提交
git log --oneline -5

验证通过的标准：

  • 远程地址正确
  • 所有分支和标签都已推送
  • git pull 和 git push 正常工作

2. 更新团队成员的本地仓库

通知所有协作者更新本地仓库的远程地址：

git remote set-url origin https://new-server.com/username/repo.git

3. 更新 CI/CD 配置

如果使用了 Jenkins、GitHub Actions 等 CI/CD 工具，记得更新它们的仓库地址和凭据。

九、总结

Git 仓库迁移其实并不复杂，核心就是修改 remote URL + 推送代码。根据不同的场景选择合适的方法：

  • 日常换地址：直接用 git remote set-url
  • 完整迁移：用 git clone --mirror + git push --mirror
  • 合并迁移：用 fetch + merge --allow-unrelated-histories

最后提醒一下：迁移前一定要备份，迁移后务必验证，避免数据丢失。

如果过程中遇到问题，欢迎在评论区留言交流！

如果这篇文章对你有帮助，别忘了点赞、收藏、关注三连支持一下～