国内 Git 工作流规范

Domestic Git Workflow Specifications

概述

Overview

国内团队用 Git 经常踩的坑：GitHub 访问不稳定、CI/CD 方案照搬国外水土不服、commit message 中英混杂没有规范。本技能提供一套完整适配国内平台和团队习惯的 Git 工作流。

核心原则： 工作流服务于团队效率，不是为了流程而流程。选适合团队规模的，别硬套大厂方案。

Common pitfalls for domestic teams using Git: Unstable GitHub access, CI/CD solutions copied from abroad that don't fit local contexts, and inconsistent commit messages mixing Chinese and English. This skill provides a complete Git workflow adapted to domestic platforms and team habits.

Core Principle: Workflows serve team efficiency, not process for process's sake. Choose the one that fits your team size, don't force big factory solutions.

国内 Git 平台适配

Domestic Git Platform Adaptation

平台对比

Platform Comparison

特性	Gitee	Coding.net	极狐 GitLab	GitHub
国内访问	快	快	快	不稳定
免费私有仓库	有	有	有	有
CI/CD	Gitee Go	Coding CI	内置 GitLab CI	GitHub Actions
代码审查	PR	MR	MR	PR
制品库	有限	完整	完整	Packages
适合场景	开源/小团队	中大型团队	企业私有化	国际项目

Feature	Gitee	Coding.net	Jihu GitLab	GitHub
Domestic Access Speed	Fast	Fast	Fast	Unstable
Free Private Repositories	Yes	Yes	Yes	Yes
CI/CD	Gitee Go	Coding CI	Built-in GitLab CI	GitHub Actions
Code Review	PR	MR	MR	PR
Artifact Repository	Limited	Complete	Complete	Packages
Suitable Scenarios	Open Source/Small Teams	Medium to Large Teams	Enterprise Privatization	International Projects

Gitee 特有配置

Gitee-Specific Configurations

bash

undefined

bash

undefined

设置 Gitee 远程仓库

git remote add origin https://gitee.com/<org>/<repo>.git

Gitee 的 SSH 配置

~/.ssh/config

Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/gitee_rsa PreferredAuthentications publickey

同时推送到 Gitee 和 GitHub（镜像同步）

git remote set-url --add --push origin https://gitee.com/<org>/<repo>.git git remote set-url --add --push origin https://github.com/<org>/<repo>.git

undefined

git remote set-url --add --push origin https://gitee.com/<org>/<repo>.git git remote set-url --add --push origin https://github.com/<org>/<repo>.git

undefined

Coding.net 特有配置

Coding.net-Specific Configurations

bash

undefined

bash

undefined

Coding 的仓库地址格式

git remote add origin https://e.coding.net/<team>/<project>/<repo>.git

Coding 支持的 SSH 地址

git remote add origin git@e.coding.net:<team>/<project>/<repo>.git

undefined

git remote add origin git@e.coding.net:<team>/<project>/<repo>.git

undefined

极狐 GitLab 特有配置

Jihu GitLab-Specific Configurations

bash

undefined

bash

undefined

极狐 GitLab 私有化部署常见地址格式

git remote add origin https://jihulab.com/<group>/<repo>.git

或者企业内部部署

git remote add origin https://gitlab.yourcompany.com/<group>/<repo>.git

undefined

git remote add origin https://gitlab.yourcompany.com/<group>/<repo>.git

undefined

工作流选择

Workflow Selection

方案一：主干开发（Trunk-Based Development）

Option 1: Trunk-Based Development

适合： 小团队（2-8 人）、迭代速度快、有完善的自动化测试。

main ──●──●──●──●──●──●──●──●──●──
        \   /  \   /       \   /
feat/x  ●─●   ●─●    fix/y ●─●
（短命分支，1-2 天内合回）

规则：

主干（main）始终保持可发布状态
功能分支生命周期不超过 2 天
每天至少合并一次到主干
用 Feature Flag 控制未完成功能的可见性

bash

undefined

Suitable for: Small teams (2-8 people), fast iteration speed, and complete automated testing.

main ──●──●──●──●──●──●──●──●──●──
        \   /  \   /       \   /
feat/x  ●─●   ●─●    fix/y ●─●
（短命分支，1-2 天内合回）

Rules:

The main branch is always in a deployable state
Feature branch lifecycle does not exceed 2 days
Merge into the main branch at least once a day
Use Feature Flag to control visibility of unfinished features

bash

undefined

从 main 拉分支

git checkout -b feat/user-login main

开发完成后，rebase 到最新 main

git fetch origin git rebase origin/main

提交 PR/MR，合并后删除分支

undefined

undefined

方案二：Git Flow（经典分支模型）

Option 2: Git Flow (Classic Branch Model)

适合： 中大团队、版本发布节奏固定（如双周迭代）、需要维护多个版本。

main     ──●────────────────●────────────── 生产环境
            \              / \
release     ●──●──●──●──●    ●──●──●──●── 发布分支
            \              /
develop  ──●──●──●──●──●──●──●──●──●──●── 开发主线
             \   /  \       /
feat/x       ●─●    ●─────●               功能分支
                      \   /
                  fix/y ●─●                修复分支

分支说明：

```
main
```
— 生产环境代码，只接受 release 和 hotfix 的合并
```
develop
```
— 开发主线，功能分支从这里拉出，合回这里
```
release/*
```
— 发布分支，从 develop 拉出，只修 bug 不加功能
```
feat/*
```
— 功能分支
```
hotfix/*
```
— 紧急修复，从 main 拉出，同时合回 main 和 develop

Suitable for: Medium to large teams, fixed release cycles (e.g., bi-weekly iterations), and need to maintain multiple versions.

main     ──●────────────────●────────────── 生产环境
            \              / \
release     ●──●──●──●──●    ●──●──●──●── 发布分支
            \              /
develop  ──●──●──●──●──●──●──●──●──●──●── 开发主线
             \   /  \       /
feat/x       ●─●    ●─────●               功能分支
                      \   /
                  fix/y ●─●                修复分支

Branch Explanations:

```
main
```
— Production environment code, only accepts merges from release and hotfix branches
```
develop
```
— Main development branch, feature branches are created from and merged back to this branch
```
release/*
```
— Release branches, created from develop, only fix bugs without adding new features
```
feat/*
```
— Feature branches
```
hotfix/*
```
— Emergency fixes, created from main, merged back to both main and develop

方案三：国内团队常用简化流程

Option 3: Simplified Workflow Commonly Used by Domestic Teams

适合： 大多数国内中小团队的实际情况。

main     ──●──────●──────●──── 生产环境（受保护）
            \    / \    /
dev      ──●──●─●──●──●─●──── 开发/测试环境
             \  /    \  /
feat/x       ●●      ●●       功能分支

规则：

```
main
```
分支受保护，只能通过 PR/MR 合并
```
dev
```
分支对应测试环境，自动部署
功能分支从
```
dev
```
拉出，合回
```
dev
```
```
dev
```
测试通过后，合并到
```
main
```
进行发布

Suitable for: The actual situation of most domestic small and medium-sized teams.

main     ──●──────●──────●──── 生产环境（受保护）
            \    / \    /
dev      ──●──●─●──●──●─●──── 开发/测试环境
             \  /    \  /
feat/x       ●●      ●●       功能分支

Rules:

The
```
main
```
branch is protected and can only be merged via PR/MR
The
```
dev
```
branch corresponds to the test environment with automatic deployment
Feature branches are created from and merged back to
```
dev
```
After
```
dev
```
passes testing, merge into
```
main
```
for release

分支命名规范

Branch Naming Conventions

国内团队常用命名

Common Naming for Domestic Teams

bash

undefined

bash

undefined

功能分支

feat/user-login # 新功能 feat/JIRA-1234-order-refund # 关联任务编号

修复分支

fix/payment-callback # Bug 修复 fix/JIRA-5678-null-pointer # 关联 Bug 编号

发布分支

release/v2.1.0 # 版本发布 release/2024-03-sprint # 按迭代命名

紧急修复

hotfix/v2.0.1 # 线上紧急修复 hotfix/fix-login-crash # 描述性命名

个人分支（部分团队使用）

dev/zhangsan/feat-login # 个人开发分支

undefined

dev/zhangsan/feat-login # 个人开发分支

undefined

命名规则

Naming Rules

全部小写，用
```
-
```
连接单词（不用下划线或驼峰）
前缀明确分支类型：
```
feat/
```
、
```
fix/
```
、
```
hotfix/
```
、
```
release/
```
关联任务管理平台的编号（如有）：
```
feat/TAPD-12345-description
```
长度适中，能看出分支目的即可

All lowercase, words connected with
```
-
```
(no underscores or camelCase)
Clear prefix indicating branch type:
```
feat/
```
,
```
fix/
```
,
```
hotfix/
```
,
```
release/
```
Associate with task management platform IDs (if available):
```
feat/TAPD-12345-description
```
Moderate length, just enough to indicate the branch's purpose

中文 Commit Message 规范

Chinese Commit Message Specifications

约定式提交（Conventional Commits）中文版

Chinese Version of Conventional Commits

<类型>(<范围>): <简要描述>
                                    ← 空行
<正文（可选）>
                                    ← 空行
<脚注（可选）>

<类型>(<范围>): <简要描述>
                                    ← 空行
<正文（可选）>
                                    ← 空行
<脚注（可选）>

类型清单

Type List

类型	说明	emoji（可选）
feat	新增功能	✨
fix	修复 Bug	🐛
docs	文档更新	📝
style	代码格式（不影响逻辑）	💄
refactor	重构（不是新功能也不是修 Bug）	♻️
perf	性能优化	⚡
test	测试相关	✅
build	构建系统或外部依赖	📦
ci	CI/CD 配置	👷
chore	其他杂项	🔧
revert	回滚	⏪

Type	Description	Emoji (Optional)
feat	New Feature	✨
fix	Bug Fix	🐛
docs	Documentation Update	📝
style	Code Formatting (no impact on logic)	💄
refactor	Refactoring (neither new feature nor bug fix)	♻️
perf	Performance Optimization	⚡
test	Testing Related	✅
build	Build System or External Dependencies	📦
ci	CI/CD Configuration	👷
chore	Other Miscellaneous Tasks	🔧
revert	Rollback	⏪

好的 commit message

Good Commit Messages

feat(购物车): 支持批量删除商品

- 新增全选/反选功能
- 删除操作增加二次确认弹窗
- 批量删除接口使用 POST /cart/batch-delete

关联需求：TAPD-12345

fix(支付): 修复微信支付在 iOS 16 上无法唤起的问题

原因：微信 SDK 8.0.33 版本在 iOS 16 上 Universal Links 校验逻辑变更，
导致 openURL 回调失败。

方案：升级 SDK 至 8.0.38，并更新 Associated Domains 配置。

Closes #567

feat(购物车): 支持批量删除商品

- 新增全选/反选功能
- 删除操作增加二次确认弹窗
- 批量删除接口使用 POST /cart/batch-delete

关联需求：TAPD-12345

fix(支付): 修复微信支付在 iOS 16 上无法唤起的问题

原因：微信 SDK 8.0.33 版本在 iOS 16 上 Universal Links 校验逻辑变更，
导致 openURL 回调失败。

方案：升级 SDK 至 8.0.38，并更新 Associated Domains 配置。

Closes #567

不好的 commit message

Bad Commit Messages

undefined

undefined

太笼统

update code fix bug 修改了一些东西

没有上下文

fix: 修复问题 feat: 新增功能

中英混杂无规范

fix：修复了一个bug，因为user login的时候会crash

undefined

fix：修复了一个bug，因为user login的时候会crash

undefined

CI/CD 平台适配

CI/CD Platform Adaptation

Gitee Go

yaml

undefined

yaml

undefined

.gitee/pipelines/pipeline.yml

name: 构建与测试 displayName: '构建与测试流水线'

triggers: push: branches: include: - main - dev

stages:

name: 测试 jobs:
- name: 单元测试 steps:
  - step: npmbuild@1 name: install_and_test displayName: '安装依赖并执行测试' inputs: nodeVersion: 20 commands: - npm ci - npm test

undefined

name: 构建与测试 displayName: '构建与测试流水线'

triggers: push: branches: include: - main - dev

stages:

name: 测试 jobs:
- name: 单元测试 steps:
  - step: npmbuild@1 name: install_and_test displayName: '安装依赖并执行测试' inputs: nodeVersion: 20 commands: - npm ci - npm test

undefined

Coding CI

groovy

// Jenkinsfile（Coding CI 支持 Jenkinsfile 语法）
pipeline {
    agent any

    stages {
        stage('安装依赖') {
            steps {
                sh 'npm ci'
            }
        }

        stage('单元测试') {
            steps {
                sh 'npm test'
            }
        }

        stage('构建') {
            steps {
                sh 'npm run build'
            }
        }

        stage('部署到测试环境') {
            when {
                branch 'dev'
            }
            steps {
                sh './scripts/deploy-staging.sh'
            }
        }

        stage('部署到生产环境') {
            when {
                branch 'main'
            }
            steps {
                sh './scripts/deploy-production.sh'
            }
        }
    }

    post {
        failure {
            // 企业微信/钉钉通知
            sh './scripts/notify-failure.sh'
        }
    }
}

groovy

// Jenkinsfile（Coding CI 支持 Jenkinsfile 语法）
pipeline {
    agent any

    stages {
        stage('安装依赖') {
            steps {
                sh 'npm ci'
            }
        }

        stage('单元测试') {
            steps {
                sh 'npm test'
            }
        }

        stage('构建') {
            steps {
                sh 'npm run build'
            }
        }

        stage('部署到测试环境') {
            when {
                branch 'dev'
            }
            steps {
                sh './scripts/deploy-staging.sh'
            }
        }

        stage('部署到生产环境') {
            when {
                branch 'main'
            }
            steps {
                sh './scripts/deploy-production.sh'
            }
        }
    }

    post {
        failure {
            // 企业微信/钉钉通知
            sh './scripts/notify-failure.sh'
        }
    }
}

极狐 GitLab CI

Jihu GitLab CI

yaml

undefined

yaml

undefined

.gitlab-ci.yml

stages:

test
build
deploy

variables: NODE_IMAGE: node:20-alpine

使用国内镜像加速

NPM_REGISTRY: https://registry.npmmirror.com

单元测试: stage: test image: $NODE_IMAGE script: - npm config set registry $NPM_REGISTRY - npm ci - npm test coverage: '/Lines\s*:\s*(\d+.?\d*)%/'

构建: stage: build image: $NODE_IMAGE script: - npm config set registry $NPM_REGISTRY - npm ci - npm run build artifacts: paths: - dist/

部署测试环境: stage: deploy script: - ./scripts/deploy-staging.sh only: - dev environment: name: staging

部署生产环境: stage: deploy script: - ./scripts/deploy-production.sh only: - main environment: name: production when: manual # 生产环境手动触发

undefined

stages:

test
build
deploy

variables: NODE_IMAGE: node:20-alpine

使用国内镜像加速

NPM_REGISTRY: https://registry.npmmirror.com

单元测试: stage: test image: $NODE_IMAGE script: - npm config set registry $NPM_REGISTRY - npm ci - npm test coverage: '/Lines\s*:\s*(\d+.?\d*)%/'

构建: stage: build image: $NODE_IMAGE script: - npm config set registry $NPM_REGISTRY - npm ci - npm run build artifacts: paths: - dist/

部署测试环境: stage: deploy script: - ./scripts/deploy-staging.sh only: - dev environment: name: staging

部署生产环境: stage: deploy script: - ./scripts/deploy-production.sh only: - main environment: name: production when: manual # 生产环境手动触发

undefined

GitHub Actions 国内替代方案对照

Comparison of Domestic Alternatives to GitHub Actions

GitHub Actions 功能	Gitee Go	Coding CI	极狐 GitLab CI
触发条件	triggers	Jenkinsfile triggers	only/rules
缓存依赖	cache step	stash/unstash	cache
制品存储	artifacts	制品库	artifacts
环境变量	env	environment	variables
密钥管理	环境变量配置	凭据管理	CI/CD Variables
手动触发	手动运行	手动触发	when: manual

GitHub Actions Feature	Gitee Go	Coding CI	Jihu GitLab CI
Trigger Conditions	triggers	Jenkinsfile triggers	only/rules
Dependency Caching	cache step	stash/unstash	cache
Artifact Storage	artifacts	Artifact Repository	artifacts
Environment Variables	env	environment	variables
Secret Management	Environment Variable Configuration	Credential Management	CI/CD Variables
Manual Trigger	Manual Run	Manual Trigger	when: manual

PR/MR 描述模板

PR/MR Description Template

中文模板

Chinese Template

在仓库中创建 PR/MR 模板文件：

Gitee：

.gitee/PULL_REQUEST_TEMPLATE.md

Coding / GitLab：

.gitlab/merge_request_templates/default.md

markdown

undefined

Create a PR/MR template file in the repository:

Gitee:

.gitee/PULL_REQUEST_TEMPLATE.md

Coding / GitLab:

.gitlab/merge_request_templates/default.md

markdown

undefined

变更说明

变更类型

关联信息

需求/Bug 链接：
设计文档：

需求/Bug 链接：
设计文档：

改动范围

测试情况

单元测试通过
手动测试通过
相关模块回归测试通过

单元测试通过
手动测试通过
相关模块回归测试通过

测试方法

影响范围

部署注意事项

需要执行数据库迁移
需要更新配置文件
需要更新环境变量
无特殊注意事项

需要执行数据库迁移
需要更新配置文件
需要更新环境变量
无特殊注意事项

截图/录屏

undefined

undefined

常用 Git 配置

Common Git Configurations

国内环境优化

Domestic Environment Optimization

bash

undefined

bash

undefined

设置用户信息

git config --global user.name "张三" git config --global user.email "zhangsan@company.com"

commit message 编辑器设置为 VS Code

git config --global core.editor "code --wait"

解决中文文件名显示为转义字符的问题

git config --global core.quotepath false

设置默认分支名

git config --global init.defaultBranch main

代理设置（如果需要同时使用 GitHub）

git config --global http.https://github.com.proxy socks5://127.0.0.1:7890

NPM 使用国内镜像

npm config set registry https://registry.npmmirror.com

undefined

npm config set registry https://registry.npmmirror.com

undefined

.gitignore 国内项目常见配置

Common .gitignore Configurations for Domestic Projects

gitignore

undefined

gitignore

undefined

IDE

.idea/ .vscode/ *.swp

依赖

node_modules/ vendor/

构建产物

dist/ build/ *.exe

环境配置

.env .env.local .env.*.local

系统文件

.DS_Store Thumbs.db desktop.ini

国内平台特有

.coding/

undefined

.coding/

undefined

检查清单

Checklist

在推送代码前，确认：

分支命名符合团队规范
commit message 格式正确，类型和范围准确
关联了对应的需求/Bug 编号
PR/MR 描述填写完整
CI 流水线通过
已请求相关同事 Review

Before pushing code, confirm:

Branch naming complies with team specifications
Commit message format is correct, with accurate type and scope
Corresponding requirement/Bug ID is associated
PR/MR description is fully filled out
CI pipeline passes
Requested relevant colleagues for review

chinese-git-workflow

Original

Translation

国内 Git 工作流规范

Domestic Git Workflow Specifications

概述

Overview

国内 Git 平台适配

Domestic Git Platform Adaptation

平台对比

Platform Comparison

Gitee 特有配置

Gitee-Specific Configurations

设置 Gitee 远程仓库

设置 Gitee 远程仓库

Gitee 的 SSH 配置

Gitee 的 SSH 配置

~/.ssh/config

~/.ssh/config

同时推送到 Gitee 和 GitHub（镜像同步）

同时推送到 Gitee 和 GitHub（镜像同步）

Coding.net 特有配置

Coding.net-Specific Configurations

Coding 的仓库地址格式

Coding 的仓库地址格式

Coding 支持的 SSH 地址

Coding 支持的 SSH 地址

极狐 GitLab 特有配置

Jihu GitLab-Specific Configurations

极狐 GitLab 私有化部署常见地址格式

极狐 GitLab 私有化部署常见地址格式

或者企业内部部署

或者企业内部部署

工作流选择

Workflow Selection

方案一：主干开发（Trunk-Based Development）

Option 1: Trunk-Based Development

从 main 拉分支

从 main 拉分支

开发完成后，rebase 到最新 main

开发完成后，rebase 到最新 main

提交 PR/MR，合并后删除分支

提交 PR/MR，合并后删除分支

方案二：Git Flow（经典分支模型）

Option 2: Git Flow (Classic Branch Model)

方案三：国内团队常用简化流程

Option 3: Simplified Workflow Commonly Used by Domestic Teams

分支命名规范

Branch Naming Conventions

国内团队常用命名

Common Naming for Domestic Teams

功能分支

功能分支

修复分支

修复分支

发布分支

发布分支

紧急修复

紧急修复

个人分支（部分团队使用）

个人分支（部分团队使用）

命名规则

Naming Rules

中文 Commit Message 规范

Chinese Commit Message Specifications

约定式提交（Conventional Commits）中文版

Chinese Version of Conventional Commits

类型清单

Type List

好的 commit message

Good Commit Messages

不好的 commit message

Bad Commit Messages

太笼统

太笼统

没有上下文

没有上下文

中英混杂无规范

中英混杂无规范

CI/CD 平台适配