企业官网建设流程全解析

• 示例工程
• 前端
• 移动开发
• 跨平台

本指南围绕 uni-app 仓库中 代码提交说明 这一开发规范文档展开，系统讲解 uni-app 的 dev / alpha / master 三级分支提交策略、Husky Git Hook 的初始化方式，并结合仓库内实际的 check-commit.cjs 钩子脚本逐行剖析其判定逻辑。读完本文，你将理解 uni-app 团队如何防止开发者误提交到受保护分支，并掌握一套可直接迁移到任意 Git 项目的分支提交防护方案。

一、分支模型：dev / alpha / master 与 HBuilder 版本的对应关系

uni-app 的代码提交策略建立在其特有的分支模型之上。根据仓库中的 分支及 tag 与 HBuilder 版本对应关系 文档，仓库分支与 HBuilder（uni-app 官方 IDE）版本存在如下一一对应关系：

tag 的命名同样遵循这一规则：例如v_4.63-alpha对应 HBuilder 4.63-alpha 版本。

从 代码提交说明 与上述分支文档可以完整还原出这套分支治理思路：dev是唯一允许产生新提交的分支，master与alpha只接收从其他分支合入的代码，以此保证正式版与 Alpha 版分支的历史可追溯、内容可控，任何未经合流的直接提交都会被视作违规。

二、提交策略：只有 dev 分支允许创建新提交

原文档对提交策略的表述非常明确：

仅dev分支允许创建新的提交，master分支与alpha分支仅允许从其他分支 cherry-pick 或 merge。

翻译成具体的操作语义：

• 在dev分支上：可以自由创建 commit，正常进行日常开发提交；
• 在master/alpha分支上：不允许直接git commit，只能通过git merge（从其他分支合入）或git cherry-pick（从其他分支挑取指定提交）的方式变更代码。

这种"集中式合流"的分支策略在开源框架仓库中很常见，它的价值在于：发布分支上的每一次代码变更都带有明确的合流来源记录，当出现问题时，可以快速回溯"这个改动是从哪次合流、哪个功能分支引入的"。

三、用 Husky 在提交瞬间自动拦截误操作

规则靠人来记总会失效，因此仓库给出的落地方案是在 Git Hook 层面做强制检查。原文档给出的初始化命令是：

npx husky@9.0.11

这条命令的作用是拉取并执行 Husky 9.0.11 版本的 CLI。Husky 9 初始化后会在项目中创建.husky/目录，并把 git hooks 指向该目录，从而允许我们在提交生命周期的各个节点（pre-commit、commit-msg等）插入自定义脚本。

结合仓库中的实际文件可以还原完整的接线方式：仓库在 package.json 中预置了一个名为check-commit的 npm script：

"scripts": { "check-commit": "node ./git-hooks/check-commit.cjs" }

该脚本指向 git-hooks/check-commit.cjs。由于check-commit.cjs通过process.argv[2]读取提交信息文件路径，可以推断其典型用法是挂载在commit-msg钩子上——即初始化 Husky 后，在.husky/下创建commit-msg钩子文件，内容形如：

#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" node ./git-hooks/check-commit.cjs "$1"

Git 在执行git commit时会自动把提交信息文件路径作为第一个参数传给commit-msg钩子，check-commit脚本据此读取待提交的信息并完成分支合规校验。

四、源码级解读：check-commit.cjs 的判定逻辑

仓库中的 check-commit.cjs 是这套防护机制的核心实现，全文不足 20 行，逻辑非常清晰。完整代码如下：

const fs = require('fs') const { execSync } = require('child_process') const message = fs.readFileSync(process.argv[2]).toString('utf8').toLowerCase() const branch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim() if ( (branch === 'master' || branch === 'alpha') && !message.startsWith('merge') && !message.startsWith('*') ) { console.log('You are not allowed to commit directly to master or alpha branch') process.exit(1) }

逐段拆解其工作流程：

1. 读取提交信息

const message = fs.readFileSync(process.argv[2]).toString('utf8').toLowerCase()

通过process.argv[2]拿到 Git 传入的提交信息文件路径，读取内容后统一转为小写。转为小写的目的是让前缀匹配不区分大小写，即Merge、MERGE、merge都会被识别为合法前缀。

2. 获取当前分支

const branch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim()

调用git rev-parse --abbrev-ref HEAD获取当前所在分支的简写名称（如master、alpha、dev），并去除末尾换行符。这一步是整段检查的事实依据：先确认"我在哪个分支"，再决定"允不允许直接提交"。

3. 分支与提交信息的双重判定

if ( (branch === 'master' || branch === 'alpha') && !message.startsWith('merge') && !message.startsWith('*') ) { console.log('You are not allowed to commit directly to master or alpha branch') process.exit(1) }

判定规则可以形式化为：

禁止提交 ⇔ 当前分支 ∈ {master, alpha} 且 提交信息不以 "merge" 或 "*" 开头

• 只有在master/alpha分支上才触发检查，dev分支（以及仓库中其他功能分支）完全不受限制；
• 提交信息以merge开头（例如Merge branch 'xxx' into master这类由git merge自动生成的默认提交信息）时放行，对应"仅允许 merge"的规则；
• 提交信息以*开头时同样放行，从源码结构看，这是为项目中使用*前缀标注特殊提交场景所预留的白名单通道；
• 命中禁止条件时，打印明确提示You are not allowed to commit directly to master or alpha branch并以退出码 1 终止提交，Git 会因此中止本次 commit 操作。

整套脚本刻意保持"只拦截、不修改"的克制：它不做提交信息改写，也不校验格式风格，唯一职责就是在错误分支上直接提交时亮红灯，把分支保护收敛到最小、最关键的判断上。

五、机制细节与边界：哪些场景会放行，哪些会被拦截

基于对源码的逐行分析，可以总结出这套机制的实际行为边界：

放行场景

• 在dev或其他非保护分支上的任意提交；
• 在master/alpha上以merge开头的提交信息（git merge产生的默认提交即属此类）；
• 在master/alpha上以*开头的提交信息；
• 通过git commit --no-verify绕过钩子（这是 Git 提供的官方逃生通道，仅适合在确认无误时手动使用）。

拦截场景

• 在master/alpha上提交信息不以merge或*开头的直接提交。

需要特别留意的是cherry-pick 场景：文档规则允许master/alpha通过git cherry-pick合入提交，但 cherry-pick 复制的提交信息通常沿用原提交的 message。如果被挑取的提交信息不以merge或*开头，从源码逻辑看该操作同样会被钩子拦截。因此，从源码结构推断，实际执行 cherry-pick 合流时可能需要配合git commit --no-verify或对提交信息做相应调整，这也是团队在真实工作流中需要自行权衡的细节。

六、将这套分支防护迁移到自己的项目

check-commit.cjs不依赖任何 uni-app 特有逻辑，是一个完全通用的分支保护脚本。迁移到任意项目只需三步：

第 1 步：初始化 Husky

npx husky@9.0.11

第 2 步：将钩子脚本放入项目中

把 check-commit.cjs 复制到项目git-hooks/目录（或任何自定目录），并在 package.json 中登记脚本：

"scripts": { "check-commit": "node ./git-hooks/check-commit.cjs" }

第 3 步：在.husky/下创建commit-msg钩子

#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" npm run check-commit "$1"

通用化改造建议

• 修改分支列表：把['master', 'alpha']换成你项目自己的受保护分支名，例如['main', 'release']；
• 调整前缀白名单：若你的团队用docs、fix等 Conventional Commits 前缀，可以扩展startsWith判定；
• 更严格的需求：还可以在钩子中追加git cherry-pick场景识别，或结合 CI 流水线对推送（pre-push）做二次校验。

七、总结

uni-app 通过"分支模型 + 提交策略 + Git Hook 落地"三层设计，把"只有 dev 能新建提交、master 与 alpha 只能合流"的规范固化成了一道自动防线：文档层明确规则，分支及 tag 与 HBuilder 版本对应关系 定义了分支语义，package.json 登记校验脚本，check-commit.cjs 在commit-msg阶段拦截违规提交。这套方案的启发在于：团队规范如果不落到工具层面，就永远只是建议——一个十几行的钩子脚本，就能让"禁止向发布分支直接提交"从口头约定变成无法绕过的硬约束，且这套机制与语言、框架无关，可以直接复用到任何 Git 托管项目。

• 示例工程
• 前端
• 移动开发
• 跨平台