协作设置

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 协作, 团队协作, 合作, 团队
---

# 项目协作设置指南

本指南帮助您设置远程仓库并邀请同事参与项目开发。

## 选项 1: 使用 GitHub（推荐）

### 1. 创建远程仓库

```bash
# 在 GitHub 创建新仓库后，添加远程仓库
git remote add origin https://github.com/<your-username>/<repo-name>.git

# 或使用 SSH
git remote add origin git@github.com:<your-username>/<repo-name>.git
```

### 2. 推送代码到远程仓库

```bash
# 首次推送 main 分支
git push -u origin main
```

### 3. 邀请同事协作

#### 方式 A: 通过 GitHub 网页端
1. 打开仓库页面
2. 点击 `Settings` → `Collaborators`
3. 点击 `Add people`
4. 输入同事的 GitHub 用户名或邮箱
5. 选择权限级别：
   - **Read**: 只能查看和拉取代码
   - **Write**: 可以提交代码和创建 PR
   - **Admin**: 完全管理权限

#### 方式 B: 通过团队/组织
1. 创建或选择组织
2. 在组织设置中创建团队（如：`developers`）
3. 将团队成员添加到仓库
4. 配置团队权限

### 4. 同事克隆仓库

```bash
# 同事执行以下命令
git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>

# 安装依赖
pnpm install

# 启动开发环境
pnpm dev
```

### 5. 同事提交代码流程

```bash
# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 开发并提交
git add .
git commit -m "feat: 添加新功能"

# 3. 推送到远程
git push origin feature/new-feature

# 4. 在 GitHub 上创建 Pull Request
```

### 6. 审查和合并

1. 在 GitHub Pull Requests 页面查看同事提交的 PR
2. 代码审查（Review Changes）
3. 如果需要，请求修改（Request Changes）
4. 审查通过后，合并 PR（Merge Pull Request）
5. 选择合并策略（建议使用 Squash and merge）

## 选项 2: 使用 GitLab

### 1. 创建远程仓库

```bash
git remote add origin https://gitlab.com/<your-username>/<repo-name>.git
git push -u origin main
```

### 2. 邀请成员

1. 打开仓库 → `Settings` → `Members`
2. 点击 `Invite members`
3. 选择角色：
   - **Guest**: 仅只读访问
   - **Reporter**: 可以创建 Issue
   - **Developer**: 可以提交代码
   - **Maintainer**: 可以管理仓库
   - **Owner**: 完全控制权限

## 选项 3: 使用 Gitee（国内）

### 1. 创建远程仓库

```bash
git remote add origin https://gitee.com/<your-username>/<repo-name>.git
git push -u origin main
```

### 2. 邀请成员

1. 仓库页面 → `设置` → `成员管理`
2. 添加成员
3. 设置权限：
   - **开发者**: 可读写代码
   - **管理员**: 完全控制

## 分支保护设置

### GitHub 设置

1. 仓库 `Settings` → `Branches`
2. 点击 `Add branch protection rule`
3. 配置：
   - Branch name pattern: `main` 或 `main,develop`
   - ✅ Require a pull request before merging
   - ✅ Require approvals: 1
   - ✅ Disallow stale approvals
   - ✅ Require status checks to pass before merging
   - ✅ Require branches to be up to date before merging
   - ✅ Do not allow bypassing the above settings

### GitLab 设置

1. 仓库 `Settings` → `Repository` → `Protected branches`
2. 选择 `main` 分支
3. 配置保护规则

## CI/CD 设置（可选）

### GitHub Actions

创建 `.github/workflows/ci.yml`:

```yaml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build:
    runs-on: ubuntu-latest

steps:
    - uses: actions/checkout@v3

- name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '24'

- name: Install pnpm
      uses: pnpm/action-setup@v2
      with:
        version: 8

- name: Install dependencies
      run: pnpm install

- name: Build
      run: pnpm run build

- name: Test
      run: pnpm test
```

## 常用协作命令

### 同步远程代码

```bash
# 查看远程更新
git fetch origin

# 拉取并合并
git pull origin main

# 或使用 rebase（更清晰的提交历史）
git pull --rebase origin main
```

### 解决冲突

```bash
# 拉取最新代码
git fetch origin

# 尝试合并
git merge origin/main

# 如果有冲突，查看冲突文件
git status

# 编辑冲突文件，解决冲突后
git add <conflicted-file>

# 继续合并
git commit -m "解决冲突"
```

### 同步主分支

```bash
# 切换到功能分支
git checkout feature-branch

# 同步最新 main 分支
git fetch origin
git merge origin/main

# 或使用 rebase
git rebase origin/main

# 推送更新
git push origin feature-branch
```

## 团队协作建议

### 1. 代码审查规范

- 每个 PR 必须经过至少一人审查
- 审查关注点：
  - 代码质量和可维护性
  - 性能影响
  - 安全问题
  - 测试覆盖
- 审查应在 24 小时内响应

### 2. 沟通工具

- 使用 GitHub/GitLab Issues 跟踪任务
- 使用 Pull Request 讨论代码变更
- 使用项目看板管理任务进度

### 3. 发布流程

```bash
# 创建发布分支
git checkout -b release/v2.1.0

# 更新版本号
# 运行测试
pnpm test

# 构建生产版本
pnpm run build

# 创建标签
git tag -a v2.1.0 -m "Release v2.1.0"

# 推送标签
git push origin v2.1.0
```

### 4. 定期同步

建议每周进行一次团队代码同步会议，讨论：
- 进展更新
- 技术难点
- 代码审查反馈
- 下周计划

## 问题排查

### 权限问题

```bash
# 检查当前远程配置
git remote -v

# 如果使用 HTTPS，需要配置 GitHub Token
# 设置 Git 配置
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

### 推送被拒绝

```bash
# 先拉取远程更新
git pull origin main --rebase

# 解决冲突后
git push origin main
```

### 分支追踪丢失

```bash
# 重新设置上游分支
git branch --set-upstream-to=origin/main main
```

## 安全建议

1. **保护主分支**：启用分支保护规则
2. **代码审查**：强制要求 PR 审查
3. **自动化测试**：CI/CD 必须通过才能合并
4. **敏感信息**：不要提交密钥、密码等敏感信息
5. **定期备份**：定期备份远程仓库