GitCommit团队协作及开源项目规范

标签：git

2026-07-19

清晰、一致的提交记录是团队协作的重要基础，本文主要结合多个方面介绍如何编写符合要求的提交信息以及团队协作的项目规范。

Commit Message规范

约定式提交

约定式提交：https://www.conventionalcommits.org/en/v1.0.0/

约定式提交是由Angular团队提出的一种提交信息规范，它定义了一种统一的提交信息格式，方便团队成员理解和管理代码变更。

知乎上对这种提交方式有许多详细解释：https://zhuanlan.zhihu.com/p/90281637

中文Commit Message

最近几年中文Commit Message被广泛接受，使用中文作为commit message可以很好发挥中文字少事详的优势，方便团队成员理解变更内容。

目前无论是自建git还是gitee, github都支持中文commit message，不会乱码，适合中国团队使用。

仓库规范

分支规范

团队协作时，应该有一个主分支（目前都不用master了，一般用main分支），也可以分为生产和开发分支。

开发者从主分支拉取代码，进行开发，完成后，应提交到自己创建的分支（团队内应有分支命名规范，例如贡献者缩写/feat-fix-chore等变更类型/变更描述词）。

提交之后，再通过Pull request申请将代码合并到主分支。

WIP规范

WIP即work-in-progress，一些开发中的代码，还没有完成，如果提交到仓库，应备好WIP说明。

代码审查规范

自动代码风格检查

人工审查前应通过CI流水线自动执行代码风格检查（如ESLint、Prettier等），确保代码符合团队的代码规范。

人工代码检查

人工代码检查应在检查pull request时进行，审查以下内容：

功能是否符合预期？
是否处理了边界和异常情况？
是否符合团队规范？
命名是否清晰？
是否存在安全问题（如SQL注入、XSS）？
是否有单元测试？
是否遵循架构原则（如monorepo）？

提交内容规范

不要提交以下内容：

dist 等打包后的构建产物
node_modules （或者其他语言的）依赖
.vscode / .idea / .trae / .eclipse 等IDE相关文件
.DS_Store / Thumbs.db 等系统文件

代码规范

变量、函数、常量命名规范

注意对团队的变量、函数、常量命名进行统一，例如：

变量：camelCase
函数：camel_case
常量：UPPER_CASE

CSS规范

建议通过CSS-BEM 命名规范来约定团队的css命名，例如：

<div class="page-btn">
    <button type="button" class="page-btn__prev">上一页</button>
    <!-- ... -->
    <button type="button" class="page-btn__next">下一页</button>
</div>

有关BEM命名规范，可以参考：https://bemcss.com/

公共文件规范

SCSS / SASS 文件：存储有关css的变量命名、混合函数、组件等公共代码；
CSS 文件：存储公共全局的css样式和字体、大小、间距、颜色等主题配置；
config 文件：存储整个项目的配置信息
utils 文件：存储公共的工具函数、帮助函数等

项目结构规范

项目（或是monorepo中的子项目）应由以下几个部分构成：

utils：存储公共的工具函数、帮助函数等
components：存储公共的组件代码
styles：存储公共的css样式代码
config：存储项目的配置信息
index.html：项目的入口文件
...：其他必要的文件，如字体、图片等

React / Vue等项目还可以有：

views(或pages)：存储项目的页面代码
routes：存储项目的路由配置
...：其他必要的文件，如图片、字体等

对于每一个component，需要团队约定是存储在同级目录下（即同时有/view/xxx.css和/view/xxx.tsx文件）、还是将css存储到styles目录下（即有/styles/xxx.css和/view/xxx.tsx文件）、还是存储在单独的文件夹下（即有/view/xxx/xxx.css和/view/xxx/xxx.tsx文件）。注意，css应该和组件的命名相同，如果采用第三种方法，外部文件夹的命名也应该和组件相同。

公用库 / 开发环境规范

一定不要修改通过包管理工具（如npm）引入的代码，这样提交之后别人会报错；
如果所开发的项目和某操作系统有硬性关联，应约定使用该操作系统；
如果所开发的项目已引入某库，但你需要使用该库的其他版本，应当与团队成员协调；
若开发前后端分离项目，应善于使用ApiFox等工具调试接口，后端贡献者应向前端贡献者提供详细的文档。