企业官网建设流程全解析

1. 搞懂 upstream 和 origin 到底是什么关系

1.1 从 fork 开始说起：一份代码的三种副本

Git 的使用场景里，有一个非常经典但又容易让新手绕晕的问题：你在某个开源项目里点击了 Fork，然后 clone 到本地，改了几行代码，突然发现别人已经给上游项目提交了很多新功能。你想把这些新功能同步下来，却不知道从何下手。这背后的核心，其实是要搞清楚一份代码存在的三个不同位置。

先说最远端那个正儿八经的项目仓库，通常我们叫它“上游”（upstream）。比如你在某代码托管平台上看到了一个很火的开源项目，这个项目本身属于原作者维护，所有人都会以它为基准来提 PR。第二个位置是你自己的远程仓库，也就是你 Fork 出来的那份，托管在你自己的用户名下。第三个位置才是你本地电脑上的仓库，也就是 clone 到磁盘里的那一份。

注意，这三个位置之间的默认连接关系是这样的：本地仓库默认只认识你 Fork 出来的那个远程仓库，也就是 origin。至于最上游那个原始项目，Git 并不认识它。很多人一开始忽略了“本地仓库并不自动关联上游”这个事实，导致后面一切同步操作都无从谈起。

1.2 remote 是什么，为什么默认叫 origin

remote 在 Git 里就是一个“远程仓库的别名”，它本质上保存的是一个 URL，只是给这个 URL 起了一个好记的名字。你运行 git remote -v 的时候，会看到类似 origin https://example.com/you/project.git 这样的内容，意思就是“我记住了这个 URL，以后你说 origin，我就知道去哪拉代码”。

origin 这个名字是克隆的时候 Git 自动起的默认名，它只是约定俗成，并没有任何强制含义。同样，upstream 这个名字也是社区约定出来的，你可以把上游仓库起名成任何名字，比如 project、official、base，甚至叫 nice，Git 都无所谓。但既然大家都约定叫 upstream，你最好也这么用，因为很多脚本和文档默认搜的就是这个名字。

理解了 remote 就是一个键值对，后面添加 upstream 的操作其实就一句话：给“上游仓库的 URL”起一个叫 upstream 的别名，然后保存到本地配置里。这个配置保存在仓库的 .git/config 文件里，你可以直接打开看，甚至可以手工编辑。

1.3 不同步会带来哪些坑

有些人不理解，我 Fork 完又不是非要跟着上游更新，自己的代码自己维护不就行了？事实上，你 Fork 出来的仓库和上游是两棵独立的树，从 Fork 那一刻起，它们各自的历史就开始分叉。如果你长期不跟上同步，会出现这些麻烦事。

上游新增了某个依赖接口，或者修了一个漏洞，而你的代码还建立在老版本之上。当你终于想提交 PR 时，项目维护者会要求你先解决冲突，这时你发现自己和上游的差异已经大到无从下手。更现实一点，你自己项目里引用的某些包、配置文件、CI 脚本，可能已经和上游完全不兼容了，你甚至得重新 clone 一份再重新应用自己的改动，那之前维护的分支意义就大打折扣。

所以，定期和上游同步，并不是什么高级玩法，而是 Fork 之后的基本卫生习惯。同步的目的不是让你抛弃自己的改动，而是让你始终站在一个能被上游接受的基础上，减少后续合并的摩擦成本。

2. 给本地仓库添加 upstream 远程地址

2.1 先看看当前本地仓库的远程配置

在动手之前，先花十秒钟看看自己手头的仓库到底认识哪些远程地址。打开终端，进入你的本地项目目录，运行：

git remote -v

正常情况下你会看到类似这样的输出：

origin https://example.com/you/project.git (fetch) origin https://example.com/you/project.git (push)

如果只看到 origin，说明你的本地仓库确实没有关联上游仓库。有些人会问，为什么有些人的 git remote -v 会显示好几条，甚至还带 fetch 和 push 分开的 URL？那是远程仓库配置的一种细分方式，比如有的公司会用只读地址去 fetch，用另一个带凭证的地址去 push。但目前对我们来说，只要知道 fetch 是拉取、push 是推送就行。

还有一种情况：如果你是在一个别人已经 clone 过的目录里，可能别人已经配置过 upstream。这时候你运行 git remote -v 会看到类似：

upstream https://example.com/upstream/project.git (fetch) upstream https://example.com/upstream/project.git (push)

看到这些，你就可以跳过下一步，直接进入同步操作。但如果你不确定，建议继续看完确认步骤。

2.2 添加 upstream 的正确姿势

添加 upstream 的命令很简单：

git remote add upstream https://example.com/upstream/project.git

这里的关键点在于，后面的 URL 是“上游原始项目的地址”，而不是你自己 Fork 出来的地址。怎么确认？打开上游项目的仓库页面，复制 HTTPS 或者 SSH 地址都可以。建议优先用 HTTPS，除非你配置好了 SSH key，否则每次拉代码可能都要输入凭证。

如果你已经添加过一次 upstream，再执行上面的命令会收到报错：fatal: remote upstream already exists。说明仓库里已经有这个别名了，你不需要重复添加。有时候你添加错了地址，想改掉，可以用：

git remote set-url upstream https://example.com/correct/project.git

这条命令只改 URL，不增删 remote，速度也快。

2.3 验证配置并理解两条 fetch 和 push 的含义

添加完成后，再执行一次：

git remote -v

你应该能看到四行输出，分别是 origin 的 fetch 和 push，以及 upstream 的 fetch 和 push。如果 URL 和你预期一致，说明配置成功。这一步虽然简单，但很有必要，因为很多后续报错都源于这里配错 URL。

这里特意说一下为什么同一 remote 要显示两遍。Git 允许 fetch 和 push 使用不同的地址，所以它分别展示。大多数情况下两边是一样的，你可以简单认为每条 remote 就是两行记录。如果你在配置时发现 upstream 的 push 地址不期望存在，也无所谓，毕竟你只是同步代码，不太会直接向别人的上游仓库推送。即使误操作，push 到别人仓库的权限通常不在你手里，会被拒绝。

3. 同步上游更新：两大主流方式

3.1 最可控的方式：git fetch + git merge

同步上游标准操作分两步：先抓取，再合并。抓取命令很简单：

git fetch upstream

这个命令会把上游仓库的所有最新提交连同分支信息拉到本地，但不会动你当前工作区的任何文件。你可以把它理解为“下载了一份上游的最新状态放到缓存区”，本地代码完全不受影响。

抓取完成后，你本地的 Git 里就多了一批以 upstream/ 开头的远程分支引用，比如 upstream/main、upstream/develop。然后你切到自己的目标分支，把这个远程分支合并进来。假设你用的是 main 分支：

git checkout main git merge upstream/main

如果你本地 main 分支没有改动，这一步通常会表现为 fast-forward——直接把 main 的指针往前移动，没有任何冲突。如果你在 main 上改过东西，那就可能产生一次合并提交，或者冲突。但没关系，这正是可控的体现：你可以在 merge 之前查看到底会合并进来哪些提交，还可以决定要不要现在合并。

3.2 一条命令的便捷与真相：git pull upstream main

很多人喜欢偷懒，直接运行：

git pull upstream main

这条命令实际上就是上面 fetch + merge 的缩写。它先把 upstream 的 main 抓到本地，再尝试把 upstream/main 合并到你当前所在的分支。没有比这更快的方式了，一行搞定。

但便捷是有代价的。第一个风险是它隐式执行了 merge，如果当前分支不是你的目标分支，或者当前工作区有未提交的改动，可能会出现意想不到的冲突或 “Your local changes would be overwritten by merge” 的报错。第二个风险是它可能会在历史上产生一个额外的 merge commit，让提交记录看起来多出一个“合并点”。如果你想要的是干净线性的历史，pull 这种方式就不太合适。

我个人的建议是：在刚开始接触同步的时候，尽量用 fetch + merge 两步走。养成习惯之后，再考虑用 pull 来提速。毕竟同步这个动作频率不高，多打一条命令不算什么。

3.3 到底用 merge 还是 rebase，别被教条带偏

关于同步上游，网络上一直有 merge 和 rebase 之争。merge 忠实地记录“我合并了上游的修改”，会留下分支交叉的痕迹；rebase 会把你在本地做的提交“重新放到”上游最新提交的后面，让历史看起来像一条直线。

两者没有绝对的好坏，只有适不适合你的场景。如果是你自己维护的长期分支，希望以后给上游提 PR 时干净一点，用 rebase 会比较好。如果你们团队在同一个仓库协作，大家都用统一分支，我更倾向于用 merge，因为它不会改写历史，不会让别人的提交凭空消失。还有一个很实际的原因：rebase 冲突一旦出现，需要逐个提交解决，每个提交都可能遇到冲突，心理压力大；而 merge 冲突只需要解决一次。

我通常的做法是：同步上游的 main 分支到我自己仓库的 main 分支时，用 merge，因为我不在乎 main 分支上多一个 merge commit；而把我自己的功能分支整理成可提 PR 的状态时，用 rebase 重新放到最新的上游之上。两者配合，而不是互相排斥。

4. 从零到一的完整同步实操

4.1 一次完整的同步命令串

假设你已经配置好 upstream，并且当前本地仓库一切正常，那么一次标准的同步过程就是这几行命令：

git status git checkout main git fetch upstream git merge upstream/main git push origin main

第一行 git status 是为了确保没有未提交的改动，后面会解释为什么不建议在脏工作区直接合并。第二行切到 main 分支，保证我们是在目标分支上操作。第三行抓取上游更新，第四行把上游 main 合并到本地 main，第五行把更新推送到你自己名下的远程仓库。

注意，最后一步推送并不是“和上游同步”的必要条件，但却是让自己远程 Fork 里的代码也跟着更新的关键。如果你只想本地看看上游的最新代码，完全可以不 push。但你要为后续提交 PR，想让自己远端仓库看起来和上游一致，那这步不能少。

4.2 遇到 Not a git repository 或者 no tracking information 怎么办

新手最容易踩的坑之一，是在克隆完仓库、第一次 git merge upstream/main 时报错：fatal: upstream/main is not a commit。这通常是因为你还没执行过 git fetch upstream，Git 并不知道 upstream/main 这个引用是什么。看过前面的内容就知道，先 fetch 再 merge，顺序不能乱。

还有一种是执行 git pull 时出现类似这样的提示：

There is no tracking information for the current branch. Please specify which branch you want to merge with.

原因是你当前分支和远程分支之间没有建立追踪关系。Git 不知道你 pull upstream/main 之后，要不要 push 到 origin/main。解决办法很简单，先把它关联上：

git branch --set-upstream-to=origin/main main

设置之后，你以后直接 git push 和 git pull，Git 就会自动按照这个追踪关系操作。当然，这个命令只影响你本地分支和远端分支的关联，不影响 upstream。

4.3 同步后推送时被拒绝怎么办

本地合并完了，想推送到自己的远程仓库，却遇到错误：! [rejected] main -> main (non-fast-forward)。出现这个的原因通常是你的远程仓库 origin/main 已经领先于本地 main。换句话说，别人的改动已经到了远端，而你本地的 main 是从更早的起点合过来的。

Git 拒绝这种“非快进”的推送，是为了防止你覆盖远程已存在的提交。解决办法分两种。第一，如果远程的改动你确实想要，先执行 git pull origin main 把远程更新拉下来，再 push。第二，如果你确定本地才是正确的，远程那些提交都不要了，可以考虑 git push --force 或者更安全的 git push --force-with-lease。

这里我必须强调：push --force 要谨慎。不要拿它随便覆盖你同事正在用的分支。force-with-lease 是一个相对安全的版本，它会检查远程分支的引用是否和你预期的值一致，只有一致时才会强制覆盖，能在一定程度上避免覆盖别人的新提交。

4.4 同步频率：多久做一次比较科学

同步不是越频繁越好，但也不能拖。我见过有人为了“保持最新”，每天同步三次，结果大部分时间都在处理冲突。如果是跟着一个非常活跃的开源项目，比如每天几十个 commit，那每周同步一次是比较舒服的频率。如果上游一个月才更新一两次，那每次发布 release 后再同步就足够。

更合理的判断方式是：当你准备开始在新需求上动代码之前，先同步一次；提交 PR 之前再同步一次；如果中途遇到某次合并特别痛苦，那就说明你同步得太晚了。记住，同步的成本和距离成正比。你落后上游越多，合并冲突的规模就越可观。

5. 同步冲突详解：遇到就按这个思路来

5.1 冲突为什么会发生

合并冲突本质上就是两个分支对同一个文件的同一个位置做出了不同的修改，Git 不知道以谁为准，只能交给用户来裁决。拿生活里的事类比，就是两人同时往一张表格的同一个空格里填了不同的值，最后得由管理员来定填哪个。

同步上游尤其容易发生冲突，因为上游项目天天被很多人贡献，而你 fork 出来的副本也改过某些文件。比如上游把某个配置文件的 key 从 A 改成了 B，而你的代码里恰好也在用那个 key，调整方式还不一样，Git 就会把两个版本都展示出来，让你自己选择。冲突并不可怕，它是版本控制系统的正常防线，真正可怕的是遇到冲突后手忙脚乱地乱改。

5.2 解决冲突的标准流程

当你执行 merge 时，Git 会提示冲突文件，并把冲突标记写到文件里。打开那些文件，你会看到类似这样的标记：

<<<<<<< HEAD 你的代码 ======= 上游的代码 >>>>>>> upstream/main

标准解法是给这个区域一个最终答案：保留其中一边，或者两边都改改。删掉 <<<<<<<、=======、>>>>>>> 这些标记行，然后把文件保存。记住一个原则：你解决冲突的时候，不是在“选择谁对谁错”，而是让改动最终符合项目的整体设计。比如上游改了一个方法签名，你本地代码还调用旧签名，那你就应该把调用处改成新签名，而不是硬保留旧调用。

文件都改完之后，执行：

git add . git commit

git commit 会自动补上 merge 信息。如果你用的是 Visual Studio Code，它会提供一个图形化界面，用红绿蓝三栏展示“当前”“进入”和“合并结果”，比命令行可视化很多。但我不建议完全依赖 GUI，理解冲突标记仍然是底层能力。

5.3 常见错误信息速查表

下面这张表整理了我见过频率最高的几种同步相关报错，以及对应的处理思路。

这个表的核心价值是让你在报错时能快速定位，而不是瞎搜。尤其是 refusing to merge unrelated histories，很多情况其实是你把 upstream 地址配错了，配成了自己另一个完全无关的项目，所以加 --allow-unrelated-histories 之前一定要先确认 URL。

5.4 使用 rebase 同步时要特别留意的坑

如果你选择了 git rebase upstream/main 而不是 merge，那要记住几条保命原则。

第一，绝不要对已经推送到公共仓库的分支做 rebase。假设你把 feature 分支推到了 origin/feature，然后 rebase 上游，再用 force push 更新远程分支，历史会变得和同事本地完全不同，他们的工作区会瞬间崩溃。第二，rebase 过程中每个提交都可能触发冲突，解决完一个冲突后要执行 git add，然后 git rebase --continue，直到完成。如果想放弃整次 rebase，可以用 git rebase --abort 回到最初状态。

第三，rebase 之后，原先的提交 commit id 会全部改变。这很直观：你把提交挪到了一个不同的起点上，哈希值当然会变。如果有人基于你旧提交继续开发，你的 rebase 会让他很难受。所以，我的建议是，rebase 只用于整理自己的个人分支，别动公共分支。

6. 提升效率的几招：脚本与习惯

6.1 同步命令速查表

为了方便大家抄作业，我把最常用的场景和命令列在下面。

这些命令覆盖了 95% 的日常操作。剩下的，要么是特殊情况，要么就是该去查文档解决的对象。

6.2 写一个简单的同步函数

同步的步骤如此固定，完全可以写成脚本。我自己在 shell 配置文件里放了一个简短的函数，每次同步只需要敲一个 sync-up 命令。内容大致如下：

sync-upstream() { git status --porcelain | grep -q '^.[^ ]' && echo "有未提交的改动，先处理一下再同步" && return 1 git checkout main git fetch upstream git merge upstream/main git push origin main }

这段脚本的核心逻辑是先检查工作区是否干净。注意我用了一个有点绕的 grep 来判断是否有未提交的变更，你也可以直接用 git diff --quiet 来判断。如果工作区不干净，脚本会提示你先处理，避免合并时出现额外错误。然后切换到 main，fetch + merge + push 一气呵成。虽然有点偷懒，但对个人项目来说省事很多。

如果你用的不是 main 分支，而是 master 或者 develop，把脚本里的分支名改掉就行。如果希望同步完还能保留自己的开发分支，可以在脚本末尾加一句 git checkout 你平时的工作分支，自动切回去。

6.3 把同步变成一种习惯而不是一项任务

工具用久了你会发现，和 upstream 保持同步最大的障碍不是命令不会写，而是想不起来去做。很多人都是到了提交 PR 的时候才临时抱佛脚，发现冲突大到想骂人。

这里分享几个我踩过几次坑之后沉淀下来的习惯。第一，每开始一个新分支前，先同步一次上游 main，然后从最新的 main 切出功能分支。第二，功能分支开发期间，不要频繁把上游 main 合并进来，只在重要节点做一两次，减少无谓的冲突。第三，提交 PR 前的那次同步，优先用 rebase，这样你的 PR 提交历史会清晰。

还有一个很多人忽视的点：同步的时候不要光顾着合并代码，也要注意上游项目的 release 标签或 CHANGELOG。有时候上游更新了依赖版本或者迁移了配置，不仔细看说明，可能合并代码后项目直接起不来。每次同步后，最好马上跑一遍测试或构建，确认基础功能仍然正常。

回到最初的问题：如何与 upstream 代码同步？其实本质就是配置好 remote，然后 fetch 再 merge，最后 push。整个过程用不到一分钟。我在实际使用中的体会是，真正需要小心的往往不是命令本身，而是你的工作区是否干净、你的历史是否被别人依赖、你合的是哪个分支。只要把这些前提确认好，同步代码就是个常规动作，完全不需要有心理负担。