企业官网建设流程全解析

1. 为什么培训上库流程：散装 Git 习惯带来的真实混乱

1.1 一次发版前的“事故”复盘

我之前在项目里带过几个新同事，也接手过一个连分支规范都没有的老仓库。真实场景比网上教程写的要狼狈得多：有人喜欢把一周的工作攒成一次提交，提交信息就写“update”；有人把自己本地的一堆实验文件连同 .idea 配置一起 push 到公共分支；更有人分不清当前在哪个分支，迷迷糊糊往主干上推了一版未完成代码。

印象最深的一次，是发版前一天。某同事下午往公共开发分支推了一波代码，刚好没跑本地测试，其他人晚上拉取合并，第二天早上编译直接挂掉。那个节点正好卡在联调阶段，整个小组的进度都停在那儿。当时我们花了接近三小时，才从一条信息写着“some changes”的提交里排查出问题——他提交了一个非法的配置文件，覆盖了别人已经改好的内容。

那件事成了导火索。团队次日专门开了一个小时的会，讨论一件事：上库，也就是本地代码提交并推送到远程仓库这个动作，到底应该统一成什么样的流程。不是命令不会敲，而是大家“各自为政”的习惯，导致每个人对公共仓库的理解都不一样。于是，我牵头把上库流程整理成一份培训文档，并在团队里试跑了几轮。

1.2 这份培训文档的边界与适用对象

这份文档的核心，不是从 git init 开始讲 Git 历史，也不是把 git 的所有命令罗列一遍，而是聚焦在“从本地工作区到远程公共分支”这一条链路上。它回答的问题非常具体：

• 上库之前要检查什么？
• 分支怎么命名、提交信息怎么写？
• push 之前怎么和远程同步？
• 被拒绝时怎么排查？
• 冲突怎么解决？
• 推错了怎么挽救？

这也决定了适用对象分成两类。第一类是刚接触 Git 的新人，需要一套可照着敲的安全流程，避免一上来就犯错；第二类是团队里负责把关代码质量、制定仓库规范的老成员，他们需要知道每个环节背后的判断依据，而不只是执行命令。如果团队规模很小，只有两三个人，这套流程可以适当精简；一旦超过五人，或者开始有发布、有联调、有外部协作，就值得全员统一规则。

还有一个容易被忽略的点：我写这份文档时没有把命令当成最终目标，而把“习惯”当成目标。因为命令是固定的，但习惯不对，再规范的流程也会被绕过。后文的每一步，都在刻意强化一个核心观念——上库不是个人动作，而是面向整个团队的一次“公开发言”。

2. 上库前的自查：分支状态、提交信息与代码差异

2.1 第一关：确认自己的分支与跟踪关系

大多数低级事故，都出在“我根本不知道自己在哪个分支”这件事上。所以我要求所有人上库前先跑一个固定组合：

git status git branch -vv

git status看工作区是否干净、有哪些改动；git branch -vv看当前分支名，以及该分支是否已经和远程某个分支建立了跟踪关系。输入结果里，第一行带*号的就是当前分支。

判断逻辑很简单：

• 如果当前在main或develop这类公共分支上直接改代码，先停下来。除非是经过授权的热修，否则应该切到独立功能分支再改。
• 如果git branch -vv里分支后面没有[origin/xxx]这样的跟踪信息，说明这个分支还没推到远程，或者本地分支和远程分支断开了关联。这时需要确认自己是打算创建新分支，还是想推送到一个已有远程分支。
• 如果本地分支落后远程几个提交，后面会明确显示behind数字，这意味着需要先同步，不能直接盲推。

这一步看似基础，但在培训时我会让每个人刻意练习一星期。因为很多冲突并不是代码本身难解，而是有人推了一个与远程毫无关联、甚至已经过时的分支上来，导致合并时出现莫名其妙的重复差异。

2.2 第二关：提交信息就是小型说明书

上库前必须写的，是提交信息。相比之下，很多人在这一步极其随意，写出“fix”“update”“asdf”这种毫无检索价值的信息。对于个人开发，这种信息也许能忍；但在协作仓库里，它会把排查历史变成一场灾难。

我这里给团队定了一个不复杂的消息规范，结构是：

<type>(<scope>): <subject>

其中type表示提交类型，scope表示影响模块，subject是一句话描述。常用类型如下：

示例提交写法：

git commit -m "feat(login): 增加验证码登录" -m "关联单号: #A-1024"

我会要求正文最好再带一行关联单号或需求描述。这样以后用git log --oneline扫历史，或者用git blame追某一行代码时，能直接倒推出改动动机，不用再翻聊天记录。

还有一条容易被新同事忽略的纪律：一次提交只做一件事。不要把一个新功能和无关的格式调整混在一起，也不要把两个互不相干的 bug 修复放进同一个提交。混合提交会让撤销变得异常困难——你没办法只回滚其中一半而不伤及另一半。

2.3 第三关：diff 自查与调试残留

我见过太多人把console.log、临时代码、敏感配置、甚至生成的二进制包一起推到远程。所以流程中专门增加一步：在 commit 之前，先看差异。

git diff # 查看工作区与暂存区的差异 git diff --cached # 查看已暂存内容与当前 HEAD 的差异 git status --short # 快速扫一眼改动文件列表

自查时重点关注三类东西：

• 带有TODO、FIXME、debugger、console.log字样的临时代码；
• .env、配置文件里的真实密钥、本地数据库地址；
• IDE 目录、编译产物，比如.idea/、node_modules/、dist/、target/。

如果是敏感文件，最稳妥的办法是用.gitignore提前排除，而不是走后一条“这次先不提交”的路。因为一旦手滑提交过，这条文件的历史记录里就可能残留密钥，光是删除当前版本还不够。

这里分享一个我实际用过的笨但有效的做法：在大型提交前，先把git diff --cached的统计数字核一遍，然后问自己三个问题——这个改动是否属于当前需求？是否有不属于这个需求的文件混进来了？如果有，立刻git reset摘出暂存区重新整理。这套习惯训练两周之后，基本就能戒掉“无脑git add .”的操作。

3. 分支模型、权限设置与合并策略：先定交通规则

3.1 适合中小团队的三层分支体系

没有分支规范的仓库，就像没有车道的马路。为了上库流程不混乱，我推荐一个相对轻量的分支体系，三层就够用：

• main（主分支）：只保留可发布的稳定版本，不允许直接推代码；
• develop（开发分支）：日常集成的公共分支，所有功能分支最终合到这里；
• feature/*（功能分支）：每个人开发新需求或修 bug 时使用的临时分支，命名建议feature/需求模块-简述。

这样拆分的逻辑在于：每个开发者在feature分支上工作是自由的，commit、push 频率都可以很高；但只有通过评审和 CI 检查，才能合并到develop；而develop积累到一定程度才合并到main进行发版。隔离性够强，链路又不会太复杂。

热修场景可以单独拉hotfix/版本号-简述分支，从main拉出，修完后先回main再反向合并到develop。这比在主分支上直接改要安全得多，也方便记录发布历史。

3.2 merge 与 rebase：按协作半径选择

分支之间如何整合，是不少新手最纠结的问题。merge和rebase都能把另一条分支的提交整合过来，但产生的历史形态完全不同。

• merge会生成一个合并提交，保留两条分支的真实分叉历史，适合公共分支之间的整合，因为不会有改写历史的动作。
• rebase会把当前分支的提交“重新放”到目标分支的最新提交上，改写提交顺序和哈希，历史更线性，适合自己功能分支与公共分支同步，或者整理自己的提交序列。

我在这套流程中定了一个简单规则：功能分支整合develop的新提交时，用 rebase；feature合并回develop时，用 merge。前者的好处是，自己的功能分支永远基于最新代码，冲突尽量在自己这边解决，不至于等到合并时才爆发；后者的好处是，公共分支上保留清晰的合入记录，评审和回溯都方便。

Reworks：

git fetch origin git rebase origin/develop

以上命令是我在上库前最常用的同步手段之一。注意，我在本地功能分支上操作，不会影响远程公共分支；即使 rebase 过程中发现问题，也可以用git rebase --abort撤销，恢复原状。

3.3 保护分支与 force 推送限制

流程再清晰，也挡不住手滑和误操作。所以还要在托管平台上配置分支保护，把“规则”变成“强制”。大多数 Git 托管平台都支持这类设置，在仓库设置里可以这样配：

• 将main和develop设为保护分支，禁止直接 push；
• 要求合并请求（MR/PR）通过后才允许合入；
• 禁止使用git push --force往保护分支推送，或者至少限制为--force-with-lease。

这里解释一下--force-with-lease和--force的区别。--force是无条件覆盖远程分支；--force-with-lease则会在覆盖前检查远程分支在你上次 fetch 之后是否被其他人动过，如果动过就拒绝推送。我甚至建议把团队里的全局 Git 配置都加上这个更安全的选项：

git config --global push.default current git config --global alias.pushf "push --force-with-lease"

分支保护的意义，是让“能不能推”的决策不再依赖个人自觉，而在制度层面直接堵住误操作。权限配置完成后，上库流程才算真正闭环。

4. 一次干净的上库路径：从工作区到远程分支的完整拆解

4.1 暂存与清理：add、rm、status 的组合拳

下面进入实际操作。假设我在本地功能分支feature/login-validation上完成了新功能，准备推送到远程。第一步不是直接 commit，而是先把要提交的内容精确放进暂存区。

git status --short git add src/controller/login.ts src/service/auth.ts git rm --cached dist/bundle.js # 如果之前误跟踪了编译产物

我建议尽量用明确的文件路径，而不是一上来就git add .。后者太容易把无关文件、本地产物、未完成的新文件全部卷进来。第一次不习惯没关系，可以先git add .，然后git status --short看一下暂存区列表，如果发现多余文件，再用git restore --staged <文件>逐个摘出去。

在提交之前，再看一眼暂存区具体差异。这时已经不是扫文件列表，而是逐行确认改动内容：

git diff --cached

如果改动量很大，可以只抽查关键文件的差异。重点检查有没有误改的配置项、注释掉的旧代码、以及和自己需求无关的格式变动。这一步很花时间，但也是上库流程中最能避免返工的一步。

4.2 push 之前先同步：我习惯用 fetch + rebase

本地提交完成，不代表可以立刻 push。因为在你开发的过程中，远程develop或者其他同事的分支可能已经更新了。如果直接 push，很可能产生分叉，甚至引发合并冲突。我的固定做法是：

git fetch origin git rebase origin/develop

git fetch只更新远程追踪分支，不改变工作区，安全便宜。git rebase把自己的提交依次放到远程最新提交之后。如果 rebase 过程中某一步出现冲突，Git 会停下来，告诉你哪些文件冲突；解决完一个冲突后，执行：

git add <冲突文件> git rebase --continue

如果冲突系得太乱，觉得自己处理不了，也可以：

git rebase --abort

这会回到 rebase 开始之前的状态，自己的工作区不受影响。需要注意的是，rebase 会把分支历史改写了，所以不能用在已经被多人使用的公共分支上；它只适合自己的功能分支同步开发分支这种场景。

有时候，团队习惯用git pull --rebase，这一条命令相当于fetch + rebase。我自己在功能分支上会用这个简写，但培训时还是先教拆分写法，因为报错信息更容易理解。

4.3 推送与合并请求衔接：push 只是半程

同步和提交都完成后，就可以推送了：

git push -u origin feature/login-validation

-u参数让本地分支和远程分支建立跟踪关系，之后直接敲git push就能推送到正确目标。推送成功后，我会顺手做两件事：

• 用git log origin/develop..feature/login-validation --oneline确认将要合入的提交列表，确保没有夹带不相关的改动；
• 在托管平台创建合并请求，在描述里写清楚改动目的、测试步骤、涉及模块，并关联需求单号。

这一步很多人会跳过，只丢一个光秃秃的分支名。但当你日后需要从几百个 MR 里翻某个问题时，描述完整与否，直接决定别人能否高效定位。我一般要求在 MR 描述里包含三块内容：背景、改动清单、自测结果。没有自测结果的 MR 基本会被打回。

5. 上库翻车现场：push 被拒、冲突白热化与误提交挽救

5.1 从报错信息读出真实拒绝原因

培训文档不能只讲顺利路径，还得让成员读懂失败的信号。最常见的是 push 时弹出类似：

! [rejected] feature/login-validation -> feature/login-validation (non-fast-forward) error: failed to push some refs

non-fast-forward意思是远程分支上有本地没有的提交，本地分支落后于远程。这时候不要直接加--force硬推——大概率会覆盖别人的提交。正确操作是回到 4.2 节，先fetch + rebase，把远程新提交合进来，再重新 push。

另一种情况是权限拒绝：

remote: GitLab: You are not allowed to push code to protected branches

这说明你企图往受保护分支直接推送，被托管平台拦下了。解决方案不是绕过保护，而是按规范走合并请求流程。我在团队里反复强调：这种报错是保护机制在正常工作，不是系统故障。

还有一种相对隐蔽的报错，是推送时因为文件名大小写变化、或者本地目录结构调整，出现一些奇怪的“旧文件残留”。这类问题靠报错信息不一定能直接看出来，我会让成员先git status看看是否有未跟踪的重复文件，如果有，用git rm --cached清理后再推。

5.2 rebase 冲突的完整处理链路

冲突是最容易让人崩溃的场景。我在培训时会专门带一次完整的冲突演练，步骤包括：

1. 制造冲突：两个分支同时修改同一个文件的同一段逻辑；
2. 触发git rebase origin/develop，观察提示；
3. 用git status找出冲突文件；
4. 打开文件，搜索冲突标记<<<<<<<、=======、>>>>>>>，逐段决定取舍；
5. 修改完成后，git add该文件，执行git rebase --continue；
6. 重复步骤直到 rebase 完成。

关键经验是：冲突标记出现时，不要试图“消灭标记”，而是要理解双方代码的意图。大多数冲突不是真正技术对立，而是双方在同一区域改了不同内容。此时最好和对方作者同步一下，确认保留哪段，而不是擅自决定。

我在文档里额外加了一条提醒：rebase 过程中不要提交新功能。这是一个常见的错误操作方式，很多人解决完冲突后，会顺手把还没写完的代码 commit 进去，结果 rebase 链被打断，后面的提交序列全乱掉。正确做法是解决一个、继续一个，全程只保留原有的提交序列。

如果实在不想用 rebase 解决冲突，退回方案是git merge origin/develop。合并会产生一次额外的合并提交，解决冲突的步骤类似，区别是它会保留完整分叉历史。对于不熟悉 rebase 的新人，先用 merge 兜底也可以，等熟练后再切换到 rebase。

5.3 推错了怎么办：reset 与 revert 的选择

人都会犯错，关键是犯完之后怎么安全地收场。这里要区分两种情况：本地犯错还是远程犯错。

如果代码还没 push，只是本地提交顺序乱了，可以用 reset 回退：

git reset --soft HEAD~2 # 回退两个提交，保留改动在暂存区 git reset --hard HEAD~1 # 彻底丢弃最近一个提交，谨慎使用

--soft适合想重新整理提交的情况，--hard适合确定不要当前改动了。还有一个常用操作是git stash，适合你还没提交但想临时放下当前工作的情况。

如果代码已经 push 到远程，并且别人可能已经拉取了，第一选择不是 reset，而是 revert：

git revert <commit-id>

revert 会生成一个“反向提交”，把某次提交的改动回滚掉，但保留原提交历史。这样做的好处是不会改写远程历史，别人 pull 时也不会出现强制推送的混乱。

需要回滚一批已发布的改动时，可以用：

git revert --no-commit <commit1>..<commit2> git commit -m "revert: 回滚某功能相关改动"

而 reset 只建议在无人拉取的私有分支上使用。如果是自己 push 到远程功能分支后想完全重写提交历史，可以用git push --force-with-lease，但前提是你确认远程分支没有别人动过。这个操作我会让团队成员在使用前至少确认两遍分支名。

6. 上库的收尾不是结束：CI 联动、评审与二次修改

6.1 CI 检查通过后才算“入沟”

很多团队的流程止步于 MR 创建成功，剩下的靠人肉评审，结果漏掉很多低级问题。我在培训文档里强调一个理念：上库只是一个动作，代码合入公共分支才是结果。如果一个改动没有通过自动化检查和评审，它此刻还不算真正“上库”。

我建议在托管平台配置 CI 流水线，至少包含三件事：

• 编译或构建检查；
• 单元测试和必要的接口测试；
• 静态检查（lint、格式校验、安全扫描）。

本地跑过不代表 CI 能过，因为环境可能不一致。所以培训时会明确一条规则：CI 未通过前，合并按钮是灰的，不允许手动绕过。如果在 MR 里看到 CI 失败，先回本地修复，再 push 新的提交，CI 会自动重新触发。

6.2 评审意见落地后的二次上库

代码评审基本都会提几条修改意见。这时候的“二次上库”操作也很关键。拿到意见后，在本地同一个功能分支继续修改、提交：

git add <修改文件> git commit -m "fix(review): 根据评审意见调整登录校验逻辑" git fetch origin git rebase origin/develop git push

只要分支没被合并，这些新增提交会自动追加到 MR 里。评审人看到后可以再次审查。这里有个习惯问题：有些人为了保持提交历史整洁，会用git commit --amend修改上一次提交来回应评审意见。这个做法在小范围内可以，但如果改动比较大，或者评审已经产生过多轮反馈，我建议还是新开提交，方便评审人只看增量变化。

另一种常见情况是，评审期间远程develop又前进了，MR 出现冲突。这时还是用老办法fetch + rebase解决，解决完 push 后 MR 会自动刷新。

6.3 线上紧急问题：热修分支的出入库路径

最后补充一种特殊的上库场景：线上出了紧急问题，需要在短时间内修复并发布。这种情况下，仍然不建议在主分支直接补丁。我会让团队走一条快速但规范的路径：

git checkout main git pull origin main git checkout -b hotfix/1.2.1-login-failure # 修改并提交 git push -u origin hotfix/1.2.1-login-failure

在 MR 里标注“热修”，让评审人优先处理。合入main后，再切到develop，把main的改动合并回来：

git checkout develop git pull origin develop git merge main

这么做是为了避免 develop 和 main 之间的差异越来越大。热修越着急，越要走流程，因为乱中更容易出错；哪怕少睡一小时，也不要给线上留下第二个故障源。

如果线上问题需要立即回滚某个已发布提交，操作顺序是：确认影响面、用git revert生成回滚提交、推送到 main 发版，然后再用同样的逻辑同步回 develop。先回滚止血，再定位根因，比边查边改更快也更安全。

最后分享一个我培训时的收尾动作：每次讲完这套流程，我不会让大家背命令，而是要求每个人用自己的话，把一次完整上库的步骤写出来。写出来的顺序但凡有一点偏差，比如漏掉同步远程、没核对分支、提交信息不规范，我都知道这人还没真正吸收。制定流程从来不是为了让文档更厚，而是让团队在最不想动脑的时候，也能靠习惯做正确的事。你如果也在头疼团队的上库乱象，不用一口气铺开全部规则，先把分支、提交信息、push 前同步这三件事立住，就已经能避掉大多数坑。