企业官网建设流程全解析

1. 从一次仓库初始化说起：为什么默认分支这件事值得单独聊

很多人第一次接触代码托管平台，注意力都放在提交、推送、拉取这些动作上，默认分支叫什么名字，基本不会多看一眼。直到某天你克隆了一个老项目，敲下git push origin main却报错说远端没有这个分支，或者团队里有人用master、有人用main，合并请求的目标分支总是选错，你才会意识到：分支命名这件小事，其实是个不大不小的坑。

这篇内容就围绕两件事展开：一是代码托管平台的基础使用逻辑，二是把默认分支从main改回master的完整操作。注意，这里说的是“改回”，因为近几年新注册的账号和新建的仓库，默认分支大多已经被设定为main，而不少存量项目、内部规范、老旧的持续集成脚本仍然认master这个名字。两种命名本身没有对错，问题出在“不一致”上。只要团队内部、本地环境和远端平台三者的默认分支名对不齐，就一定会有人踩坑。

适合读这篇的人大概有三类：刚学会git commit和git push、还没搞明白分支模型的新手；接手了老项目、发现默认分支名和习惯不符的开发者；以及需要统一团队仓库规范、批量调整默认分支的维护者。我会把平台侧的操作、本地命令行的配合、以及改完之后容易忽略的收尾工作都讲清楚，尽量做到照着做就能复现。

先说一个基本认知：默认分支名只是一个“约定”，它不影响 Git 这个工具本身的任何功能。main和master在技术层面完全等价，都是指向某次提交的可变指针。真正会出问题的，是所有“默认值”依赖它的地方——克隆时检出的分支、合并请求的默认目标、持续集成配置里的分支过滤、部署脚本里的分支判断。所以改默认分支从来不是改一个名字那么简单，而是一次涉及多处的同步操作。

2. 代码托管平台的基础使用逻辑拆解

2.1 仓库、分支、提交三者的关系

要理解默认分支，得先把仓库的结构想清楚。你可以把一个仓库想象成一棵不断生长的树，提交是树上的节点，分支是从某个节点伸出去的枝条，而默认分支就是这棵树的主干。主干只有一个，其他枝条最终要么合并回主干，要么被剪掉。

具体到操作层面，一次典型的协作流程是这样的：从远端克隆仓库到本地，本地会自动检出一个分支，这个被自动检出的分支就是默认分支。你在它上面修改、提交，然后推送回远端。如果要做新功能，就从当前分支切一条新分支出去，开发完再发起合并请求，请求把新分支合回默认分支。整个链路里，默认分支出现了至少三次：克隆时的检出目标、合并请求的目标分支、以及很多自动化工具默认监听的分支。

这里有个容易被忽略的点：默认分支是仓库级别的设置，不是账号级别的。也就是说，你可以在同一个账号下，让 A 仓库用main，B 仓库用master，互不影响。但正因为它是仓库级别的，批量管理多个仓库时就得逐个确认，不能想当然。

2.2 为什么平台会把默认分支从 master 改成 main

早些年，几乎所有平台的默认分支都叫master。后来陆续有平台把新仓库的默认值改成了main，动机主要是用词层面的考量，跟技术实现无关。这个改动本身是合理的，但它带来的副作用是：新老仓库的默认分支名出现了分裂。

对个人开发者来说，这种分裂影响不大，自己改一下就行。但对团队来说，麻烦就来了。假设团队有二十个仓库，一半是老的master，一半是新的main，那么任何脚本、文档、新人培训材料都得写两套逻辑。更麻烦的是持续集成配置，很多流水线文件里会写死分支名，比如只在master分支推送时触发构建，结果新仓库推的是main，流水线根本不跑，排查半天才发现是分支名对不上。

所以“把默认分支改回 master”这个需求，本质上不是怀旧，而是为了统一。当团队决定以master作为标准命名时，把所有仓库的默认分支都对齐到master，能省掉大量沟通成本和配置维护成本。

2.3 改默认分支前必须确认的三件事

动手之前，有三件事必须先确认，否则容易改出问题。

第一，确认远端仓库当前是否已有master分支。如果已经有，那改默认分支只是切换指向，相对简单；如果没有，就需要先把main的内容推一份到master，再切换默认分支，最后才能删掉main。

第二，确认本地仓库的当前分支和远端默认分支是否一致。很多人本地还停在main上，远端默认分支已经改成master了，这时候直接推送会推错地方。

第三，确认所有协作者的本地环境。默认分支改了之后，其他人本地的origin/HEAD引用不会自动更新，需要他们手动执行一次同步命令，否则他们克隆或检出时拿到的还是旧的分支信息。

提示：改默认分支属于仓库级操作，建议在团队内提前通知，最好选一个没有正在进行的合并请求的时间窗口，避免有人正在提交时目标分支突然变了。

3. 把默认分支从 main 改为 master 的完整实操

3.1 平台侧操作：先建分支再切默认

不同平台的界面措辞略有差异，但逻辑是一致的。下面按通用流程讲，你对照自己用的平台找对应入口即可。

第一步，进入目标仓库的设置页面，找到“分支”或“默认分支”相关的设置项。这里会显示当前默认分支，通常是main。

第二步，如果仓库里还没有master分支，需要先创建。有两种做法：一是直接在平台的分支管理界面里，基于main新建一个名为master的分支；二是通过命令行推送一个master分支上去。两种都行，命令行方式更可控，后面会讲。

第三步，在默认分支设置里，把默认分支从main切换为master。切换后，仓库首页展示的、克隆时检出的、合并请求默认指向的，都会变成master。

第四步，确认切换成功后，再考虑是否删除main分支。这里要特别谨慎：如果main上还有master没有的提交，删除会丢内容。稳妥的做法是先对比两个分支的差异，确认master完全包含main的内容后再删。

3.2 命令行侧操作：本地分支的同步与重命名

平台侧改完，本地也得跟上。假设你本地当前在main分支上，远端默认分支已经改成了master，推荐的操作顺序如下。

先拉取远端最新状态，把远端的分支信息同步到本地：

git fetch origin

然后查看远端分支列表，确认master已经存在：

git branch -r

如果本地还没有master分支，基于远端创建一个并切换过去：

git checkout -b master origin/master

如果你希望把本地的main直接重命名为master，可以用：

git branch -m main master

重命名之后，需要重新设置上游分支，让本地master跟踪远端master：

git push -u origin master

这里有个细节：git branch -m只是改本地分支名，不会动远端。如果远端还有main，你需要单独决定是否删除它。删除远端分支的命令是：

git push origin --delete main

执行前务必确认master已经包含了main的全部提交，否则这个操作不可逆。

3.3 参数与命名选择的背后逻辑

有人会问，为什么不干脆保留main，把团队的规范改成main呢？这其实是个纯粹的取舍问题，没有标准答案。选择改回master的常见理由有这么几个。

一是存量项目多。很多老项目的持续集成配置、部署脚本、文档里写的都是master，改这些的成本远高于改一个新仓库的默认分支名。二是团队习惯。有些团队从很多年前就用master，肌肉记忆和内部文档都是围绕它建立的，强行切换反而增加出错概率。三是工具兼容。少数自建的工具链在默认配置里硬编码了master，改起来牵扯面大。

反过来，如果团队是从零开始、没有历史包袱，那顺应平台默认值用main也完全合理。关键不在于选哪个，而在于选定之后全团队统一，并且把选择写进团队规范文档里，让新人一进来就知道。

注意：无论选main还是master，都不要在两个名字之间反复横跳。每切换一次，所有协作者都要重新同步，成本很高。定下来就别轻易改。

4. 改完之后容易踩的坑与排查技巧

4.1 协作者本地引用不更新

这是最常见的问题。你把远端默认分支改成了master，但同事本地执行git checkout main依然能切过去，或者克隆新仓库时检出的还是main。原因在于本地缓存的origin/HEAD引用没有更新。

解决办法是让每位协作者执行一次：

git remote set-head origin -a

这条命令会重新从远端读取默认分支信息，更新本地的origin/HEAD指向。执行完之后，再用git branch -r查看，origin/HEAD应该指向origin/master了。

如果同事本地还有基于旧默认分支的本地分支，建议他们按 3.2 节的流程重命名或重新检出，避免本地和远端命名不一致。

4.2 持续集成与自动化配置失效

默认分支改名后，所有监听分支名的自动化配置都可能失效。典型表现是：代码推上去了，但流水线不触发；或者触发了，但部署脚本报错说找不到分支。

排查思路是逐个检查配置文件里的分支名。常见的位置包括流水线配置文件、部署脚本、代码质量扫描配置、以及各种钩子脚本。把里面写死的main改成master，或者改成通配写法，避免以后再因为改名而失效。

4.3 合并请求与保护规则的处理

如果仓库设置了分支保护规则，比如要求合并请求必须经过审核才能合入默认分支，那么改默认分支后，保护规则也要跟着调整。有些平台的保护规则是绑定在具体分支名上的，默认分支从main改成master后，原来的规则还挂在main上，master反而没有保护。

处理办法是进入分支保护设置，把规则迁移到master上，或者重新为master配置一套。同时检查是否有正在进行的合并请求，它们的目标分支可能需要手动改到master。

还有一个细节：如果仓库开了“自动删除已合并分支”之类的功能，删除main之前要确认没有未合并的内容，否则可能触发意外的清理行为。

4.4 独家避坑经验几条

第一条，改默认分支前先打一个标签或记下当前提交哈希。万一改完发现有问题，可以快速回退到已知状态。命令是git rev-parse HEAD，把输出记下来。

第二条，如果仓库有多个协作者，改完之后发一条简短的通知，附上同步命令，比让他们自己摸索效率高得多。通知里写清楚：远端默认分支已改为master，请执行git remote set-head origin -a并检查本地分支。

第三条，删除main分支不要急。可以先保留一段时间，比如一周，确认没有任何流程依赖它之后再删。保留期间在分支描述里标注“待删除”，避免有人误用。

第四条，如果团队同时管理很多仓库，建议写一个检查脚本，定期扫描各仓库的默认分支名，发现不一致就告警。这样能避免新仓库创建时又用了平台默认的main，导致规范被慢慢侵蚀。

5. 关于分支命名的长期维护建议

分支命名这件事，短期看是一次配置调整，长期看是团队规范的一部分。我的建议是把它写进仓库的说明文档里，明确写出：本仓库默认分支为master，新建分支的命名规则是什么，合并请求的目标分支是什么。新人入职时看一眼文档就能对齐，不用靠口口相传。

另外，新建仓库时要养成习惯，创建后第一件事就是检查默认分支名是否符合团队规范。如果平台默认给的是main，而团队规范是master，那就立刻改掉，别等仓库里堆了提交再改，那时候牵扯的东西更多。

对于个人项目，其实怎么命名都行，自己顺手就好。但如果你打算把项目开源，或者未来可能和别人协作，那最好一开始就选一个和主流平台默认值一致的名字，减少别人的上手成本。这也是为什么很多新项目直接用main的原因——不是因为它更好，而是因为它更省事。

最后分享一个我自己的做法：在本地 Git 配置里设置一个别名，把常用的分支同步操作封装成一条短命令，改默认分支或者切换仓库时敲一下就行，省得每次记一长串参数。配置写在全局配置文件里，换机器时同步过去，长期下来能省不少事。