📘 GitHub 仓库复用：Fork、Template 与 Import
复用别人的 GitHub 仓库有三条路：Fork（保留历史、保留关联）、Template（只要文件、不要历史）、Import（从别处迁过来）。选错会导致后面要么丢历史、要么没法跟进上游。
🎯 选型：先用这张表
| 你的需求 | 用哪个 | 入口 |
|---|---|---|
| 给上游提 PR、贡献代码 | Fork | 仓库主页右上角 Fork |
| 以别人项目为基础二次开发 | Fork | 仓库主页右上角 Fork |
| 保留历史，且以后要跟进上游更新 | Fork | 同上 |
| 以此仓库为脚手架起新项目，不需要历史 | Template | 仓库主页右上角 Use this template |
| 从 GitLab / Bitbucket / 裸 Git URL 迁到 GitHub | Import | 右上角 + → Import repository |
| 只是本地跑一下，不打算推回去 | 都不需要 | git clone 即可 |
一句话：想跟进上游用 Fork；想快速起新项目且不需要历史用 Template；换平台用 Import。
一、Fork
📌 Fork 是什么
在 GitHub 上把别人的仓库完整复制到自己账号下。你的 Fork 是独立仓库，拥有完整的提交历史、分支、标签，你对它有完全写权限。
关键特性：与源仓库保持关联，可以随时把上游的更新拉进来——这是 Fork 区别于 Template 的唯一本质。
🛠️ 基本流程
1. 在 GitHub 上 Fork
仓库主页右上角 Fork → 选你的账号/组织 → 等待完成。
你会得到 你的用户名/仓库名，URL 形如 https://github.com/你/仓库。
2. 本地克隆
git clone https://github.com/你/仓库.git
cd 仓库3. 配置上游（关键，别漏）
# 只需做一次
git remote add upstream https://github.com/原作者/仓库.git
# 验证：应该看到 origin 和 upstream 两个
git remote -v
# origin -> 你的 Fork (fetch/push)
# upstream -> 原作者仓库 (fetch)配完之后 origin 是你的 Fork，upstream 指原作者仓库。Fork 默认不带 upstream remote，不手动加就没有后续同步能力。
🔄 核心：跟进上游更新
这是用 Fork 最主要的维护成本。两条路：
方式 A：本地同步再推送（推荐）
# 1. 切到主分支
git checkout main # 或 master
# 2. 拉取上游最新
git fetch upstream
# 3. 把上游主分支并进来
git merge upstream/main # 方式 1：产生一个合并提交，保留「何时同步过」的痕迹
# git rebase upstream/main # 方式 2：历史线性，会重写提交
# 4. 推回你的 Fork
git push origin mainmerge 还是 rebase
| 情况 | 选择 | 原因 |
|---|---|---|
| 这个分支只有你一个人在用，且没推到 origin | rebase | 历史干净，无多余合并节点 |
| 已经推到 origin，或者别人可能基于你的分支工作 | merge | 不重写已发布的提交，别人 pull 不会出错 |
一句话：没推出去就 rebase，推出去了就 merge。
方式 B：GitHub 网页端「Sync fork」
- 打开你的 Fork 页面
- 上游有新提交时会出现 Sync fork 按钮
- 点击 → 选分支 → Update branch
⚠️ 网页端只帮你做了
merge这一步，本地还要git pull才能拿到最新。网页操作完不等于本地同步完了。
怎么知道该同步了
# 上游比本地领先多少提交
git log --oneline HEAD..upstream/main
# 本地比上游领先多少（你自己的私有改动）
git log --oneline upstream/main..HEAD🧱 冲突处理
你在本地改了文件，上游也改了同一行时：
git fetch upstream
git merge upstream/main
# 或者
git rebase upstream/mainGit 会报冲突并停下：
# 编辑冲突文件，删掉 <<<<<<< ======= >>>>>>> 标记，保留正确内容
git add .
git commit # merge 走到这
# 或 git rebase --continue # rebase 走到这减少冲突的做法：
- 不要在
main/master上直接开发，开feature/xxx分支 - 同步上游前先把自己的改动
commit或stash - 同步得越勤，冲突越小。攒三个月再同步会很痛
二、Template（模板仓库）
📌 什么是模板仓库
把某个仓库标记为 Template 后，别人可以用它一键创建新仓库。适合 starter kit、脚手架、样板项目。
✅ 如何把仓库设为模板
- 进入该仓库的 Settings
- 左侧菜单 General → 找到 Template repository 复选框
- 勾选并保存
需要仓库 owner 或 Admin 权限。
🎯 设为模板后的效果
| 特性 | 说明 |
|---|---|
| 绿色按钮 | 仓库主页右上角出现 Use this template，点它就能基于此仓库创建新仓库 |
| 不保留提交历史 | 新仓库只有一个 Initial commit，原仓库的历史、分支、标签都不带过来 |
| 完全解耦 | 新仓库与模板仓库再无关联，模板后续更新不会同步到已创建的仓库 |
| 分支可选 | 创建时可勾选「Include all branches」，默认只带默认分支 |
💡 模板仓库的最佳实践
- README 写清楚怎么用：目录结构、怎么跑、怎么部署
- 提供
TEMPLATE.md或CONTRIBUTING.md，告诉使用者哪些地方要改成自己的 - 用 GitHub Actions 做初始化：创建后自动
npm install、替换占位符等 - 版本化模板：打
v1.0、v2.0标签，README 里写明「基于v1.2模板创建」
三、Import（迁移到 GitHub）
📌 什么时候用
把不在 GitHub 上的仓库迁进来：从 GitLab、Bitbucket、Azure DevOps，或一个裸 git:// / https:// 地址。
右上角 + → Import repository → 粘贴源仓库 URL → 导入。
保留完整提交历史，但导入后与源平台不再有自动关联，之后各自独立演进。
📊 Fork vs Template vs Import 完整对比
| 维度 | Fork | Template | Import |
|---|---|---|---|
| 与源仓库关联 | ✅ 保留 | ❌ 切断 | ❌ 切断 |
| 提交历史 | 完整保留 | ❌ 仅 Initial commit | ✅ 完整保留 |
| 分支/标签 | ✅ 全部带过去 | ❌ 仅默认分支 | ✅ 全部带过去 |
| 后续跟进源更新 | ✅ 可同步 | ❌ 不可能 | ❌ 不可能 |
| 给源仓库提 PR | ✅ 可以 | ❌ | ❌ |
| 源不在 GitHub | ❌ | ❌ | ✅ 支持 |
| 典型用途 | 贡献代码、二开、长期跟进上游 | starter kit、脚手架、样板 | 换平台迁移 |
🛡️ 最佳实践清单
- Fork 后立刻
git remote add upstream，否则后面没法同步 -
main/master保持干净，只用来同步上游，不直接提交 - 功能开发都开
feature/xxx分支 - 定期同步上游，别攒太久
- 提 PR 前先
git fetch upstream && git rebase upstream/main，确保基于最新上游 - 如果上游重写了历史（force push），本地可能对不上，考虑重新 Fork
🔧 命令速查
# 远程配置
git remote -v # 看有哪些远程
git remote add upstream <url> # 加上游（只需一次）
# 同步上游
git fetch upstream # 拉上游最新
git merge upstream/main # 合并上游（已推送分支用这个）
git rebase upstream/main # 变基上游（未推送分支用这个）
git push origin main # 推回自己的 Fork
# 查差距
git log --oneline HEAD..upstream/main # 上游领先我多少
git log --oneline upstream/main..HEAD # 我比上游多什么
# 放弃本地修改，完全对齐上游（危险）
git fetch upstream
git reset --hard upstream/main
git push origin main --force-with-lease🔗 相关
最后更新：2026-10-05