企业官网建设流程全解析

简介：GitLab 分支管理最佳实践文档，面向研发负责人、开发人员和测试人员，用于解决多团队并行开发与发版节奏难协调的问题。内容以 GitLab 分支模型为核心，系统说明 master、feature、test、release、hotfix、bugfix 六类分支的职责与生命周期，并给出 feature-、test-等命名规范及分支权限矩阵，还通过一次标准迭代发布的情景化案例，展示从功能开发、提测、回归到打 tag 发布、分支清理的完整流程，可直接在项目中参考落地。文档共 1 个 docx 文件，大小 266KB，已有 626 人学习。这份实践指南尤其适合需要支持功能测试与发版测试并行、实现任意功能组合发版控制的研发团队。

1. gitlab 分支管理：一套规则同时扛住功能测试和发版测试

版本发布前一周最怕听到的问题不是 bug 太多，而是测试同学问「今天功能测试环境上跑的是哪个分支的代码」，全场沉默。我见过不止一个团队在这种沉默之后，发现测试环境早就被多个功能分支交叉合并弄成了黑匣子，功能测试和发版测试各自为政，发布前只能靠赌。这背后的共同点，是 gitlab 分支管理只解决了「代码放哪」，没解决「哪个分支该服务于哪个测试环节」。

功能测试和发版测试对分支的需求天然冲突：功能测试要灵活，希望每个功能能快速拉到独立环境验证；发版测试要稳定，希望拿到一个不被后续提交污染的固定快照。一套同时兼顾两者的分支策略，核心就三件事：环境分支职责固化、保护分支权限落地、CI 按分支自动决定部署目标。这套方案不挑团队规模，三五人的小组和二十人的产线都能用，下面从模型选型开始一步步拆。

2. 先想清楚再动手：分支模型怎么选，环境分支为什么是刚需

2.1 两种主流分支模型在发版测试视角下的取舍

常见的分支模型无非两条路：以 Git Flow 为代表的多长分支模型，和以主干开发为代表的单主干模型。一开始就纠结「哪个更先进」没有意义，要看你的发布节奏和测试环境形态。

Git Flow 维护 master、develop、release、hotfix 四条长分支，外加 feature 短分支。它的优势恰恰落在发版测试环节：release 分支从 develop 拉出来后进入冻结状态，后续功能继续进 develop，release 保持原样。测试人员测的就是 release 当前 HEAD 这个固定快照，测出问题修复后重新走一遍合并，快照语义清晰。缺点是分支操作繁琐，每次发版要处理的合并方向多。

主干开发模型只有一条 master，功能通过短分支合入，发版靠打 tag 提供快照。代码量小、自动化程度高的团队跑得很顺，但一旦你有独立的发版测试环境，问题就来了：测试环境部署 master，功能测试的同学刚验证完一个功能，下一个人把代码合进主干，环境立刻变了样。功测和发版测挤在同一条分支上，互相踩踏。

我一般建议走混合路线：主干做集成与记录，环境分支承担测试职责。具体到 GitLab 上，就是 master、test、release 三条长分支各自对应一个环境职责，功能分支短命、随合随删。这样既有 Git Flow 的快照语义，又避免了 develop 和 release 之间来回合并的繁琐。

2.2 环境分支设计：master / test / release 的职责边界

分支规则混乱的根源，是同一个分支承担了太多角色。最简单可靠的拆法是让长分支与测试环境一一对应，每条分支只有一个主子职责。我常用的结构是这样：

这个结构里有几个容易被忽略的约定。首先，test 分支不是「开发主战场」，它的职责是聚合本期要测的功能。功能开发在 feat/xxx 分支上做，完成合入 test 后，功能测试同学才在 test 环境看到它。其次，release 分支平时不与 test 分叉，只有进入发版窗口时才把 test 合并进来，然后冻结。发版测试通过后，从 release 打正式 tag 部署生产，再把 release 合并回 master 留档。

很多人会问：test 和 release 内容不是一样吗，为什么不能只留一条？因为在发版测试期间两者会必然分叉。功能测试的同学继续在 test 环境验证新功能，发版测试的同学在 release 快照上做回归，两条分支各司其职，互不污染。如果只有一条 test，发版测到一半有新功能合进来，整个回归就失去意义了。

2.3 命名规范与合并方向：用一段仓库约定统一全队认知

分支模型落地时最大的阻力不是技术而是习惯，所以命名规范和合并方向要写成仓库里的约定文件，让每个新成员一眼看懂。功能分支统一用 feat/前缀，修复用 fix/，紧急修复用 hotfix/，文档类用 docs/。前缀后面跟简短描述，比如 feat/login-sms-code，而不是 feat/a 或者直接用自己的名字。

合并方向用一段文字加命令注释就能写清楚，放在仓库根目录的 BRANCH.md 里即可。关键约定是这些：

# 合并方向约定（禁止反向合并） # feat/* -> test 功能开发完成后合入功能测试环境 # fix/* -> test 修复功能测试发现的问题 # test -> release 发版窗口期合入,进入发版测试 # release -> master 发版测试通过后留档 # release -> tag v* 生产发布 # hotfix/* -> release 生产问题修复,重新走发版测试 # hotfix/* -> test 同一修复合回功能测试环境

逻辑说明：这里刻意把 hotfix 的合并方向写成两个步骤，而不是直接从 release 部署上线。生产修复也属于「发版」，必须过一遍发版测试快照，合回 test 则是为了让功能测试环境同步修复。实际执行时如果修复非常紧急需要跳过发版测试，至少要保留 hotfix 分支记录并在合并说明里标注风险，这个操作在避坑章节会展开讲。

3. 落地一套可复现的分支管理配置：从建分支到保护分支

3.1 仓库初始化：三条长分支的建立命令

分支管理方案不能只停留在文档里，先把仓库切到目标状态。假设你在 GitLab 上已经建好空仓库并 clone 到本地，初始分支默认是 master，执行下面这段命令建立 test 和 release 长分支。这里以 master 作为两者共同的起点，保证后续合并时提交历史是同源的。

# 从主分支拉出 test 长分支并推送 git checkout -b test origin/master git push -u origin test # 从主分支拉出 release 长分支并推送 git checkout -b release origin/master git push -u origin release # 回到主分支确认三条长分支都已就位 git branch -a

逻辑说明：-u 参数把本地分支与远端分支关联起来，后续直接 git push 和 git pull 就能操作，避免每次输入完整远端分支名。第二步单独从 origin/master 拉 release 而不是从 test 拉，是为了保证两条环境分支初始内容完全一致，之后只有 test 在前、release 在后按方向推进。第三步的 git branch -a 是检查动作，看到 origin/test、origin/release 都存在后再进行保护配置。

参数说明：如果你希望 test 分支初始为空而非继承 master 的代码，可以省略上一节提到的 checkout 步骤，直接创建并强制推送空分支，但我不建议这么做。空分支作为起点会让第一次合并带上大量历史差异，CI 流水线也更容易在首轮构建中暴露环境变量缺失的问题，从 master 同源开始，问题都在可控范围内。

3.2 保护分支一键配置：用 GitLab API 而不是在网页上点

很多团队在网页设置里把 master 保护了就算完事，test 和 release 仍然裸奔。结果是功能分支直接 push 到 test 的现场时有发生。分支保护应该覆盖三条长分支，而且应该写成脚本，而不是人工去每个项目点一遍。GitLab 提供的保护分支 API 可以一次完成权限配置，下面这段脚本对同一批项目执行，结果可重复、可审计。

# 批量保护长分支：禁止直接 push，仅允许 Maintainer 通过 MR 合并 for branch in master test release; do curl --request POST \ --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \ --data-urlencode "name=${branch}" \ --data-urlencode "push_access_level=0" \ --data-urlencode "merge_access_level=40" \ --data-urlencode "allow_force_push=false" \ "https://gitlab.example.com/api/v4/projects/${PROJECT_ID}/protected_branches" done

逻辑说明：push_access_level=0 表示没有任何角色可以直接向该分支推送代码，这是整条策略的核心。开发者要合入 test，唯一路径是创建功能分支、发起合并请求、由 Maintainer 审核合并。merge_access_level=40 对应 Maintainer 角色，允许审核后点击合并，但不能绕过 MR 直接 push。allow_force_push=false 顺带把强推也禁掉，防止有人用 git push --force 覆盖远端历史。

参数说明：PROJECT_ID 是 GitLab 项目数字 ID，在项目设置页面的 General 里可以看到；GITLAB_TOKEN 需要是一个拥有 Maintainer 权限的 Personal Access Token，在 GitLab 用户设置里生成，scope 勾选 api。如果你的 GitLab 实例启用了分组级保护规则，可以在项目所属分组里统一配置，这样新项目创建后自动继承，不需要每个项目都跑一遍脚本。

3.3 合并请求模板：把「可测试」写进 MR 的门禁

保护分支解决的是「谁能合入」，但没解决「合入的东西测试同学能不能接得住」。功能测试团队拿到一个 MR 常常要先猜它改了哪些模块、影响什么范围、重点验哪里。与其让两边来回拉扯，不如把 MR 模板设计成一份测试交接单。在仓库根目录创建 .gitlab/merge_request_templates/default.md，内容如下：

## 功能范围 （这段改动解决什么问题，关联的需求单/缺陷单编号） ## 自测结果 （开发本地跑过哪些用例,覆盖了哪些关键路径） ## 建议测试点 （给功能测试同学的重点验证清单,比如异常输入、边界条件、依赖模块） ## 影响模块 （改动可能波及的页面/接口/数据表,方便评估回归范围） ## 合并目标分支 （默认 test；发版用 release；紧急修复用 hotfix,与分支策略对照）

逻辑说明：这个模板的关键在「建议测试点」和「影响模块」两栏。功能测试同学拿到 MR 后，第一眼看到的就是开发给出的验证路径，而不是从 diff 里自己猜。合并目标分支这一栏用来约束开发者的意识：每次发起 MR 时要想清楚这个改动是进入功能测试流程还是发版测试流程，而不是无脑选择默认分支。

实际执行中我见到的最大阻力是开发觉得「填模板浪费时间」。我的处理办法是：MR 模板作为合并的前置条件，空的直接打回。跑过两个版本之后，团队会发现模板里填的内容能直接复用到发版说明的「本期变更」部分，填起来越来越顺手。这个模板文件本身要提交进仓库并设为默认模板，在 GitLab 项目设置里指定即可。

4. 让分支策略自动执行：GitLab CI 按分支触发环境部署

4.1 流水线设计思路：一条分支对应一个环境

分支规则是静态约定，真正让团队省心的是让 CI 流水线按分支自动决定部署目标，彻底消灭「手动选择部署环境」这一步。我常用的设计是：功能分支只跑构建和单元测试，不部署任何环境；test 分支的 push 自动部署功能测试环境；release 分支的 push 自动部署发版测试环境；前缀符合版本规则的 tag 触发生产发布 job，并且需要人工确认。

这个设计的核心价值在于「环境与分支的绑定关系由流水线规则强制」。测试同学不用问开发要部署按钮权限，也不存在某个人手动把功能分支部署到生产这种低级事故。每条环境在自己关联的分支上跑，分支一推，环境跟着变，谁改的、什么时候改的，GitLab 的环境页面里都留了记录，排查问题时有据可循。

4.2 gitlab-ci.yml 核心规则：按分支路由的完整示例

下面这份 .gitlab-ci.yml 是可以在新仓库里直接改用的骨架，覆盖了上一节表格里的全部触发场景。注意 stages 的顺序和 rules 的匹配逻辑，这是最容易出错的地方。

stages: - build - deploy variables: APP_NAME: demo-web IMAGE_TAG: ${CI_COMMIT_SHORT_SHA} build: stage: build script: - echo "build image ${APP_NAME}:${IMAGE_TAG}" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_COMMIT_BRANCH =~ /^(master|test|release)$/' - if: '$CI_COMMIT_TAG' deploy_test: stage: deploy script: - echo "deploy ${APP_NAME}:${IMAGE_TAG} to TEST" environment: name: test url: https://test.example.com rules: - if: '$CI_COMMIT_BRANCH == "test"' deploy_release: stage: deploy script: - echo "deploy ${APP_NAME}:${IMAGE_TAG} to RELEASE" environment: name: release url: https://release.example.com rules: - if: '$CI_COMMIT_BRANCH == "release"' deploy_prod: stage: deploy script: - echo "deploy ${APP_NAME}:${IMAGE_TAG} to PROD" environment: name: prod url: https://www.example.com rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/' when: manual

逻辑说明：最核心的是 rules 里的三层路由。第一层是 build job：MR 事件、三条长分支、任意 tag 都会触发构建，保证代码在任何入口进入流水线时都有产物可测。第二层是 deploy_test 和 deploy_release：各自的规则精确匹配分支名 test 和 release，其他分支即使触发了流水线也不会走到对应部署 job，因为 rules 不匹配时该 job 会被跳过。第三层是 deploy_prod：只匹配 v 开头的标准版本号 tag，并且 when: manual 让生产发布必须有人工点击确认，杜绝 push 触发直接上生产的可能。

参数说明：IMAGE_TAG 用的是 CI_COMMIT_SHORT_SHA，即提交的短哈希，保证每个提交构建出的镜像标签唯一，不会出现多个提交共用 latest 导致部署到错误版本的情况，这个细节对发版测试的可重复性很关键。environment 配置让每个部署 job 在 GitLab 的 Operations 环境页面里有独立记录，可以随时查看某个环境当前部署的是哪个提交、由哪次流水线触发。

4.3 发版测试最容易被低估的设计：同一 tag 可重复部署

发版测试身边的人应该都经历过这个场景：预发环境测出一个数据脏了，测试同学想「重新部署一份干净的再来一遍」，但代码没有变动，没有新的 push，也就没有新的流水线。最后只能去改动代码里的一个空格再推一次，用新 commit 触发部署。这种做法最大的害处是——发版测试的对象变成了一个「未经过审阅的假提交」，git 历史被污染，后续回滚定位时要多绕一个弯。

正确做法是给 RC（Release Candidate）tag 单独开一个部署入口。发版测试通过后，正式 tag 从 release 分支原位打出，RC 与正式版共享同一个代码快照，只是 tag 名不同。部署 job 按 tag 路由，任何一个既往 tag 都可以随时重新部署。这样「重测」不再需要改代码，直接从 tag 列表里选一个点部署即可。

deploy_release_tag: stage: deploy script: - echo "redeploy ${CI_COMMIT_TAG} to RELEASE" environment: name: release url: https://release.example.com rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$/' when: manual

逻辑说明：这个 job 的 rules 只匹配形如 v1.2.0-rc.1 的候选版本 tag，不匹配正式版本号。发版测试期间测试同学部署的就是这个「候选快照」，发现问题后修复代码、合入 release、打下一个 rc tag，整个流程都是可追溯的。它和 deploy_prod 的差别在于：rc 可以反复执行、没有上线压力；正式版 tag 对应生产部署，权限上天然区分。

参数说明：rc 后缀的数字序号要逐个递增，测试通过的那个 rc 号要记录在发版说明里。正式 tag 从 release 分支拉出后，其内容与最后一个 rc 的代码完全一致时，发版测试的结论才对生产发布有效。如果正式 tag 与测试过的 rc 之间存在差异，意味着发版测试白做了，这个问题在避坑章节单独讲。

5. 分支管理避坑：功能测试和发版测试中的 5 个高频翻车点

5.1 功能测试环境被「交叉合并」污染

现象：功能测试同学上午验证完登录功能一切正常，下午同一个环境里登录突然报错，查下来发现是另一个功能分支合入时带进去的改动覆盖了公共模块。定位了半天，发现功能分支 A 和功能分支 B 之间发生过一次「互相帮忙」的合并，把彼此没验证过的代码掺在了一起。

原因：功能分支不是从最新 test 拉出，而是从另一个功能分支拉出，或者两个功能分支之间直接 merge 过。这类交叉合并会让 test 分支在合并时把两套未经验证的改动一起收进来，环境的问题无法界定是哪个功能的锅。

解决：约定功能分支只能从最新 test 分支拉出，功能与功能之间禁止互相合并，合并目标只允许 test。GitLab 端配合保护分支，让 test 分支仅能通过 MR 合入，从机制上杜绝交叉污染。如果两个功能确实有依赖关系，正确顺序是：合并第一个功能到 test，然后基于更新后的 test 重建第二个功能分支，而不是让两个分支提前绑定。

5.2 发版前两天发现本期功能没有全部进 test

现象：准备从 test 拉 release 分支进入发版测试，核对功能清单时发现某几个预期功能在 test 分支上找不到。开发一脸无辜：「我早合完了啊」。查下来发现这几个功能分支被合并到了 release 分支，或者直接 push 到了 master，唯独绕过了 test。

原因：MR 创建时没有认真选合并目标分支，默认落到其他分支上；或是个别开发为了图方便直推到了 master。功能测试环节对这些改动完全无感，因为功能测试环境只部署 test 分支。

解决：保护分支配置里把 master 的 push_access_level 设为 0，开发者没有权限直推，只能走 MR。拉 release 分支进入发版窗口前，用一个脚本核对 test 分支上是否包含本期的全部功能分支合并记录，确认后再执行合并。具体命令放到第六章的自检清单里，这里记住一个原则：release 分支只能从 test 拉出，任何绕开 test 的合入都是流程事故。

5.3 发版测试「测错了代码」，上线后功能消失

现象：发版测试回归通过，正式发布后用户反馈某个功能不存在。测试记录显示测试环境验证过，生产环境却是旧的代码。两边对质之后发现，测试同学验证的时候部署的是某个旧 commit 构建的产物，而 release 分支本身后来又被修改过，镜像 tag 用的还是 latest，覆盖了验证过的产物。

原因：两个，第一是 release 分支在发版测试期间没有冻结，有人直接 push 了修复；第二是镜像 tag 固定为 latest，部署动作发生时拉的是这个分支最新的提交，而不是测试人员实际摸过的那一份。

解决：release 分支进入发版窗口后立即改保护规则，push_access_level 设 0，任何修复都必须走 hotfix 分支重新合入并重新打 RC tag。镜像 tag 严格使用 CI_COMMIT_SHORT_SHA 这类唯一标识。发版测试的结论必须绑定到「tag + 提交号」这个组合上，而不是绑到分支名。分支是流动的，tag 才是快照。

5.4 hotfix 直接在 release 分支改完上线，下个版本带着隐患走

现象：线上出紧急 bug，开发直接在 release 分支改了一行代码，部署生产后问题解决，大家松了口气。但下一次发版测试时，修复代码连同没有验证过的其他改动一起被带进新版本，测试同学对这次携带完全不知情，回归计划被打乱。

原因：release 分支既被当作发版快照，又被紧急修复当作工作区使用。正常工作流是靠「test → release → tag」维持版本有序推进的，中途改 release 等于跳过了「功能测试」这个环节，修复本身没有被验证过。

解决：hotfix 也走分支流程。从 release 分支拉 hotfix/xxx，修复后合回 release，打新的 tag 部署生产，再把这个 hotfix 合并回 test，让功能测试环境同步修复。如果这个修复不希望进入下个版本，才考虑用 cherry-pick 精准挑选。注意顺序：合回 test 在前，确认下次发版不含该修复在后，不要反过来。保护分支关掉 release 的直推权限后，这类问题会从机制上消失。

5.5 CI 环境变量串环境，预发环境拿到生产配置

现象：发版测试环境部署完成，页面打开直接连上了生产数据库，业务数据一目了然。排查发现 deploy_release 的脚本里读了一个全局变量 DATABASE_URL，这个变量在 GitLab 项目级变量里配置的是生产地址。

原因：GitLab CI 的全局 variables 在所有 job 里共享，部署脚本如果直接引用全局变量，环境名再清晰也拦不住错误配置。镜像 tag 固定为 latest 的同类问题也会引发相近的后果——构建环境的差异让测试产物变成玄学。

解决：每个环境用途的敏感配置放到该环境的 job 里通过 environment 作用域变量覆盖，而不是在全局 variables 里声明。- 项目级变量按环境名分组，GitLab 在对应 environment 的 job 里自动注入，关掉全局变量对部署 job 的可见性。部署脚本里把环境名作为前置参数传入，杜绝脚本内部写死。配置完以后花十分钟做一次「误触发演练」：把一个功能分支手动部署到预发环境，确认它拿不到预发的数据库配置，这个演练比任何 review 都实在。

6. 进阶：发版前一小时，用一张分支状态表完成自检

6.1 一条命令脚本，把分支状态一次看清

发版测试开始前最怕「我觉得都合了」这种模棱两可的结论。我现在的习惯是发版前跑一遍下面这个脚本，把分支之间的差异全部列出来，对照功能清单逐项核对。脚本本身不复杂，价值在于把「确认分支状态」从口头沟通变成可重复执行的检查动作。

git fetch --all --prune echo "== 1. 本期功能分支是否全部合入 test ==" git branch -r --merged origin/test | grep -E 'feat/' || echo "未发现待合并功能分支" echo "== 2. test 与 release 的差异（应为空） ==" git log --oneline origin/release..origin/test echo "== 3. release 领先 master 的提交（应为本期发版内容） ==" git log --oneline origin/master..origin/release echo "== 4. 最近可回放的版本快照 ==" git tag --sort=-v:refname | head -5

逻辑说明：第一条输出列出所有已合入 test 的功能分支，与发版清单对照，缺哪个一目了然。第二条是关键检查项，release..test 返回空，说明 test 分支没有发版窗口期间的新增提交，release 快照没被污染；如果有输出，说明发版测试环境的代码不等于将要发布的快照，需要决定是重新拉 release 还是把多余提交摘除。第三条显示 release 比 master 多出的提交，这些正是本期要发布的内容，应该与发版说明里的变更列表一致。第四条列出最近版本 tag，确认可回滚目标不是空的。

6.2 把自检当成发版流程的一部分

这套分支策略运行一段时间后，你会发现最大的收益不是流程变得好看，而是「测试环境是谁的、验证的是哪个提交、发布的内容和测过的一致」这三个问题都有了确定答案。功能测试和发版测试的分工不再依赖某个人的记忆力，而是靠分支规则和 CI 配置各管一段。

我吃过最大的亏就是早期把分支管理当作文档工作，写了一堆规范没人遵守；后来想明白，分支管理是机制问题，机制要靠保护分支和流水线来强制，而不是靠自觉。现在我的习惯是：日常开发随时合，发版前一个小时跑一次上面的自检脚本，把输出截图附在发版说明里再进发版测试。如果你也正在被「测试环境一团乱、发版测完不敢上线」困扰，照着这套结构先把环境分支和保护规则落实，跑两个版本之后，你就知道它的价值在哪里了。希望帮到你。

本文还有配套的精品资源，点击获取