企业官网建设流程全解析

1. 从一堆看不懂的分支名说起

git 分支命名规范这件事，很多人第一次意识到它的重要性，往往不是在学习阶段，而是在接手一个跑了半年以上的老仓库时。你打开分支列表，看到的是dev、dev2、dev-new、test、test123、zhangsan、fix、fix-bug、fixbug2、tmp、aaa、new这一串东西，然后你就会陷入一种非常具体的困境：不知道哪些能删，不知道哪个对应线上问题，也不知道三个月前那条修好的分支为什么还留着。这不是某一个人的问题，是几乎所有从零开始的团队都会经历的一个阶段。

分支命名规范说白了就是给仓库里的“工作线”起名字的一套约定。它解决的问题非常朴素：让任何一个能进这个仓库的人，光看分支名就知道这条线是谁在做、在做什么、属于哪一类改动、对应哪个需求单。它适合所有正在使用 git 做协作的人——不管是三五人的小团队，还是上百人共用一个仓库的大型项目；也不管你用的是命令行、IDEA 内置的 Git、还是 TortoiseGit 这种图形化工具，规范本身都是通用的。

我在几个不同规模的团队里都参与过分支规范的制定和落地，踩过的坑比想象中多。有些规范写得太理想，发下去三天就没人执行；有些规范太松，等于没写；还有的规范本身没问题，但因为没有自动校验，全靠人自觉，半年后就名存实亡。这篇文章就把我实际用过、改过、最后真正跑起来的那一套东西摊开讲清楚，包括为什么这么定、每一步怎么落地、出问题怎么排查。

2. 分支模型决定了命名该怎么写

2.1 先搞清楚你的团队在用哪套分支模型

分支命名规范不是孤立存在的，它必须挂在某套分支模型上，否则就是一堆没有意义的字符串组合。如果你的团队用的是 Git Flow，那分支天然分成主干、开发、功能、发布、热修这几类；如果你用的是 GitHub Flow，那基本只有主干加功能分支；GitLab Flow 又会在两者之间取一个中间值，加上环境分支的概念。命名规范的作用，就是把这些模型里的角色用命名固定下来。

举个具体的例子。Git Flow 里develop是集成分支，main或master是对外可发布的分支，功能开发从develop切出来，发布前合到release，线上出事从main切hotfix。这套流程本身已经区分了分支的用途，命名规范只需在此基础上把“临时分支”这一层补全，比如功能分支叫什么、修复分支叫什么。反过来，如果你用的是简化到只有主干加功能分支的模型，命名规范承担的区分职责就更重，因为你没有develop、release这些结构性分支帮你分流。

我见过最常见的错误，是团队实际上跑的是简化模型，却照抄了 Git Flow 的五类前缀，结果release/和hotfix/两个月都没出现过一次，规范里一半以上的内容是死条款。规范里每多一条用不上的规则，执行成本就上升一点，最后拖垮整个规范的往往就是这些没人用的部分。

2.2 分支数量与命名粒度的平衡点

命名粒度是另一个需要提前想清楚的问题。粒度太粗，feature/xxx里那个 xxx 写什么都行，等于没约束；粒度太细，要求必须严格按类型/工单号-模块-简述三段式来写，一开始大家还能记住，忙起来就随手写了个feature/tmp。

我的经验是取一个中间值：固定“类型前缀 + 简述”两段，工单号作为可选但强烈推荐的部分。为什么工单号不设为强制？因为不是所有改动都有对应的需求单，比如改一个错别字、补一段注释，硬要编一个单号出来反而是在制造流程负担。但反过来，只要这个改动能被追踪到某个需求或缺陷，工单号就应该带上，因为它解决了“这条分支到底为什么存在”这个问题。

分支存活时间也影响粒度。如果一条分支从创建到合并通常只有一两天，那简述可以写得很粗，feature/user-login就够了；但如果分支会活两三周甚至更久，就需要更具体的信息，feature/1024-user-login-sms-code，避免同一条线上有两条分支都在做登录相关的事而你分不清谁是谁。

2.3 我们团队最后定下来的折中方案

把上面两点合起来，我们最终用的是一套“固定前缀 + 可选工单号 + 短横线小写简述”的结构，形如feature/1024-user-login或者不带单号的docs/update-readme。前缀固定为八类，覆盖了绝大多数场景，剩下的极少数情况允许用chore/兜底。这套结构在三个不同规模的团队里都用过，最长的一个跑了两年多没改，说明它在可执行性和约束力之间找到了平衡点。

3. 分支名到底该怎么拼：前缀、分隔符与长度

3.1 八类前缀的适用场景对照

前缀是整个命名结构里信息密度最高的部分，它决定了别人看到这条分支时的第一判断。定前缀时最忌讳的是语义重叠，比如同时有fix/和bugfix/，那到底用哪个就成了每天都要纠结的问题。下面是我们在实际使用中收敛出来的八类前缀，每一类都有明确的边界。

这张表里最关键的是bugfix/和hotfix/的区分。很多团队只留一个fix/，结果线上紧急修复和开发阶段的普通修复合在同一类里，出问题时没法快速筛出所有线上修复记录。我坚持区分这两者，是因为 hotfix 的整个生命周期都不同：它从 main 切出、要同时合回 main 和 develop、发布流程也更急。把这点体现在命名上，后续追溯线上问题时能省下大量时间。

3.2 分隔符、大小写与长度的那些细节

前缀定完之后，剩下部分怎么写才是真正容易出分歧的地方。我们内部曾经为“用下划线还是短横线”争论过一次，最后的结论是统一用短横线-，理由是它在 URL、命令行和大多数终端里都不需要转义，复制粘贴不会出意外。下划线在某些终端里双击选中时会被截断，斜杠已经被前缀占用了，空格和中文更是绝对不能出现在分支名里——Git 虽然允许部分特殊字符，但一旦碰到 Windows 和某些 CI 系统，就会变成一堆难查的编码问题。

大小写统一用小写，这条没有任何商量余地。原因在下一节的排查部分会详细讲，简单说就是 macOS 和 Windows 的文件系统默认不区分大小写，Feature/Login和feature/login在本地看起来能共存，推到远程却可能互相覆盖，产生让人抓狂的“幽灵分支”。

长度控制在 50 个字符以内，超过之后在终端里经常被截断，git branch列表也会换行显示，反而看不清。简述部分用两到四个单词就够，不要试图把整个需求的背景都写进分支名，那是提交信息和需求单该干的事。分支名是索引，不是文档。

提示：分支名里不要出现#、@、空格、中文、连续的点号。这些字符在 Git 的引用解析、shell 脚本和 CI 配置里都可能被特殊处理，属于典型的高风险字符。

3.3 关联工单号：让分支可以回溯到需求

工单号的位置固定放在前缀之后、简述之前，用短横线连接，比如feature/1024-user-login。这样做的好处是，通过一条简单的git branch --list 'feature/1024*'就能列出某个需求下的所有分支，代码评审时也能直接从分支名跳到需求单。

工单号的位数最好固定。我们用的是六位，早期用过不补零的三位四位数，结果1024和1024这种看起来一样、实际来自不同系统编号的情况出现过一次，之后就统一补零。补零还有一个副作用，就是按字母排序时，同一类前缀下的分支会自然按单号顺序排列，翻起来很舒服。

如果团队用的项目管理系统支持在提交信息里自动关联单号，那就更省事。分支名带单号、提交信息也带单号，服务端可以直接把这两层信息串起来，做发布说明时按分支名分组就能生成一份大致的变更清单。这条链路我们在发版前整理变更记录时用得最多，比人工翻提交历史靠谱得多。

3.4 一份可以直接抄走的规范文档

把上面的规则整理成一段可以贴进仓库 README 或者团队 wiki 的内容，大概是这样：

• 分支名格式：<type>/<ticket>-<short-description>
• type只能取：feature、bugfix、hotfix、release、refactor、docs、test、chore
• ticket为六位数字工单号，可选；无单号时省略连字符前的部分
• short-description全小写，单词之间用短横线，长度不超过 30 个字符
• 完整分支名不超过 50 个字符
• 禁止使用中文、空格、下划线、连续点号及任何 shell 特殊字符
• 临时实验分支必须以tmp/开头，且不得推送到远程超过 24 小时

最后一条是给“我就随手试试”这种情况留的口子。没有这个口子，大家就会用feature/或者直接一个test来应付，反倒破坏了规范。给垃圾留一个专门的垃圾桶，比禁止扔垃圾有效得多。

4. 用工具把规范焊死，而不是靠自觉

4.1 本地钩子：提交和推送时自动拦截

规范写在文档里，靠人记，最多撑一个月。真正让规范活下来的，是自动校验。Git 本身提供了 hooks 机制，可以在提交或推送前执行脚本。最简单的做法是在仓库的.git/hooks/pre-push里加一段校验，推送前检查当前分支名是否符合正则，不符合就拒绝。

#!/bin/sh branch=$(git symbolic-ref --short HEAD) pattern='^(feature|bugfix|hotfix|release|refactor|docs|test|chore)/[0-9]{6}-[a-z0-9]+(-[a-z0-9]+)*$|^(feature|bugfix|hotfix|release|refactor|docs|test|chore)/[a-z0-9]+(-[a-z0-9]+)*$|^tmp/.+$' if ! printf '%s' "$branch" | grep -Eq "$pattern"; then echo "分支名不符合规范: $branch" echo "格式应为: <type>/<六位工单号>-<小写短横线描述>" echo "例如: feature/001024-user-login" exit 1 fi

这段正则分成三支，分别匹配“带单号”、“不带单号”和tmp/开头的临时分支。用pre-push而不是pre-commit是有原因的：pre-commit每次提交都会触发，如果分支名不合规，你连本地提交都做不了，这在紧急改一行代码时非常恼人；而pre-push只在推送到远程时触发，本地怎么折腾都不影响，推送才是真正需要规范的时刻。

注意：.git/hooks/目录不会随仓库提交，脚本需要每个成员手动安装。解决办法是在仓库里放一个hooks/目录存脚本，再写一个install-hooks.sh，或者用git config core.hooksPath hooks把钩子目录指到仓库内的hooks/文件夹，这样克隆下来执行一次配置就能生效。

除了钩子，还可以用commit-msg钩子在提交信息里做同样的校验，把分支名和提交信息的格式统一起来。两者结合，本地这一层就基本堵住了。

4.2 服务端拦截：Push Rules 与 CI 校验

本地钩子能被绕过，--no-verify一加就跳过了。所以关键仓库必须有一层服务端校验。GitLab 的 push rules 支持正则校验分支名，直接在项目设置里填上一条正则即可，不合规的推送会被服务端直接拒绝。这个功能是免费版就有的，配置成本极低，属于性价比最高的一层防护。

GitHub 原生没有分支名正则校验，但可以用 Actions 做。在push事件里取GITHUB_REF判断分支名，不符合就 fail。需要注意的是，Action 是在推送成功之后才跑的，它不能阻止分支被创建，只能发出告警并在分支保护规则里把这个失败的检查设为必需，后续合并请求就会被拦住。

name: branch-name-check on: push: branches-ignore: - main - develop jobs: validate: runs-on: ubuntu-latest steps: - name: Check branch name run: | branch="${GITHUB_REF#refs/heads/}" if [[ ! "$branch" =~ ^(feature|bugfix|hotfix|release|refactor|docs|test|chore)/.* ]]; then echo "分支名不符合规范: $branch" exit 1 fi

三层防护里，服务端这层是最硬的，因为它没法被绕过。但它的反馈最慢，推送之后才知道失败，所以本地钩子还是要装，把问题挡在最早的环节。

4.3 规范落地的灰度节奏

一次性推行全套规则，大概率会激起反弹。我们实际的做法分三步走：第一周只上线校验脚本，但不拦截，只打印提醒；第二周开始对新建分支做硬拦截，已经存在的历史分支不加限制；第三周把服务端规则也打开。

这个节奏的好处是，让大家先看到提醒、形成意识，再遇到实际拦截时不会觉得突然。历史分支不加限制这一条尤其重要，如果一上来就把老分支全部判为违规，那些分支的主人会立刻觉得规范是在针对自己。规范的目标是让未来的分支变好，不是清算过去。

还有一个细节：把规范写进新员工的上手文档里，并且在仓库的模板里预置好钩子安装脚本。新人第一次克隆仓库、执行一次初始化命令，规范就自动生效了，不需要额外的培训成本。最有效的规范，是那种让人“不小心就遵守了”的规范。

5. 那些年踩过的坑与排查实录

5.1 大小写引发的幽灵分支

这是我在两个不同团队都遇到过的问题，值得单独讲。macOS 和 Windows 的文件系统默认不区分大小写，所以在本地用git branch feature/Login创建一个分支后，再用git branch feature/login切换过去，本地看起来什么都没变，但 Git 内部记录的分支名可能已经是后者了。等推到远程，服务器上就出现了两条名字只差大小写的分支。

更麻烦的是删除。你在本地执行git branch -d feature/Login，可能会报“找不到分支”，因为本地实际存的是小写版本。这种情况下需要用git branch -m先重命名再处理，或者直接操作远程。

# 查看远程所有分支，确认是否存在大小写重复 git ls-remote --heads origin # 删除远程的错误分支 git push origin --delete feature/Login # 本地重命名当前分支 git branch -m feature/login

根治办法只有一个：从规范层面禁止大写，并且在校验正则里不写[A-Z]。只要校验规则里没有大写字母，这个问题就永远不会出现。

5.2 分支改名、删除与误操作补救

改分支名是高频需求，尤其是需求单号填错的时候。本地改名用git branch -m 旧名 新名，如果已经推到远程，需要“删除远程旧分支 + 推送新分支”两步：

git branch -m feature/001024-user-login feature/001025-user-login git push origin --delete feature/001024-user-login git push -u origin feature/001025-user-login

这里有个坑：如果这条分支已经有人基于它切了子分支，或者已经开了合并请求，删除远程分支会导致合并请求自动关闭，需要重新开。所以分支名一旦进入代码评审阶段，尽量不要改，把单号问题留到合并时在提交信息里修正。

误删分支的补救，靠的是git reflog。只要分支在你本地存在过、且没有被垃圾回收，reflog里就能找到它的最后提交哈希，用git branch 分支名 <哈希>就能恢复。这条命令我在生产事故里用过一次，救回了一条没合并的功能分支，所以哪怕规范说了分支要及时删，我仍然建议在删除前先确认对应的合并请求已经关闭。

5.3 常见问题速查表

这张表是我自己整理给团队用的，实际排查时按“现象 → 原因 → 处理”一路找下去，比自己回忆命令快得多。

6. 分支之外，顺手能做的事

规范落地之后，还有几个延伸的小习惯值得一起做。第一个是给默认分支改名，现在新建仓库用git config --global init.defaultBranch main就能把默认分支从master改成main，新仓库不用再手动改一次。第二个是把.gitignore和分支规范一起维护，不同分支可能对应不同的环境配置，忽略文件里把本地配置目录统一排除，能避免误提交。

第三个是给分支加上描述。git branch --edit-description可以给分支写一段说明，配合git config --get branch.<name>.description查看，在分支存活时间较长时特别有用。虽然这属于分支管理的边缘功能，但和命名规范是同一套思路：让分支自己携带足够的信息。

我在实际使用中最深的一个体会是，规范的成败不在于写得多漂亮，而在于违反它的时候有没有立刻反馈。一个只能靠人记住的规范，活不过第一个赶工期的迭代；一个推送就被拦下来的规范，一周之内大家就都记住了。所以与其花时间争论前缀该有六个还是八个，不如先把那条校验正则跑起来。