打住先别急着点 New repository。我见过太多队伍的 GitHub 协作现场一个仓库放 main 分支四五个人直接把代码推上去过两天发现同事的README.md把自己的改动覆盖了或者两个人都改了config.py最后合并时看到一片红色的 CONFLICT 就懵了。这根本不是 GitHub 难用是你们还没把多人协作的流程搭建起来。这篇教程就是给所有准备用 GitHub 组队干活的人看的不论你是做课程设计、打比赛、做毕业论文还是带几个人的小团队做内部项目。我会从最基础的 Git 环境配置讲起把仓库怎么初始化、任务怎么拆、分支怎么命名、PR 怎么提、冲突怎么解决、分支保护怎么配全部过一遍。全程用真实项目里会发生的情况来举例你照着一步步做基本就能把团队协作理顺。1. 多人协作先想清楚你们该走 Fork 流程还是共享仓库流程很多教程一上来就教命令我觉得这是错误的。Git 命令只是工具真正决定你们项目能不能顺利推进的是协作模型选得对不对。这一步没想明白后面全是坑。1.1 两种协作模型的核心差异GitHub 上最常见的多人协作方式有两种Fork 流程Fork Pull Request和共享仓库流程Shared Repository。Fork 流程每个成员先把项目仓库复制到自己的 GitHub 账号下Fork改完代码后提交到自己那边然后向原仓库发起 Pull Request由维护者审核合并。共享仓库流程所有人直接在一个仓库里工作但是通过分支Branch隔离功能每个人在自己的分支上开发最后通过 PR 合并回主分支。两者在操作流程上有本质区别我整理了一个对比表对比项Fork 流程共享仓库流程仓库归属每个人账号下都有一个副本只有一个中心仓库写权限多数人无原仓库写权限成员都有指定分支的写权限典型场景开源项目、不熟的人协作小团队、课程设计、公司内部分支使用每个 Fork 里的独立分支中心仓库内的功能分支合并方式PR 从 Fork 指向原仓库PR 从功能分支指向 main维护成本需要多次同步上游仓库相对简单直接1.2 怎么选别拿开源项目的方式折磨小团队我建议你们按这三个条件判断人数少于 10 人的队伍共享仓库流程足够。信任度全员都能遵守规范、代码水平差不多的共享仓库流程效率更高。目标如果你们只是内部协作不需要培养外部贡献者共享仓库流程更省事。Fork 流程有个很烦的点每次开工前你都要先同步自己 Fork 的仓库和原仓库否则很容易基于过期代码开发多一步git remote add upstream操作对新手很不友好。所以基础为 10 人以下、关系紧密的队伍我建议直接走共享仓库流程。现在 GitHub 对免费私有仓库不限制协作者人数完全够用。这也是本篇文章后面所有操作的主线。1.3 一个仓库玩明白再做其他花样很多团队一上来就搞 git flowdevelop、release、hotfix 一堆长期分支结果小组成员根本分不清该从哪里开分支。我的经验是先用最简单的 main或 master 功能分支模型跑顺了再考虑扩展。具体就是main稳定可用版本任何人都不能直接推代码。feature/xxx开发新功能的分支。bugfix/xxx修 bug 的分支。就这两个够了。等你把这套玩熟了再去看 GitFlow 或者其他模型那时候你是真的理解了需求而不是在模仿操作。2. 环境准备与仓库初始化从 Git 安装到第一批代码入库方向定了就该动手了。这里说的环境准备不只是装个 Git 那么简单还有身份配置、SSH 免密、仓库创建和项目文件的初始化。每一步都是我见过无数新手翻车的地方。2.1 Git 安装与全局身份配置安装 Git 这一步Windows 用户直接去官网下载安装包一路 Next 就行记得勾选Git Bash Here选项macOS 用户推荐用 Homebrew 安装Linux 用户用自带包管理器安装。装完之后第一件事配置身份信息。这一步不是可选的每个人的 user.name 和 user.email 会直接记录在 commit 历史里如果你们不对齐GitHub 上会出现一堆无法关联到人的陌生提交。git config --global user.name Your Name git config --global user.email your_emailexample.com这里有个细节GitHub 的提交贡献图是根据邮箱关联的。建议所有人使用自己 GitHub 绑定的邮箱或者启用 GitHub 的 noreply 邮箱在 GitHub 设置页面可以看到否则你的提交不会被算进贡献图。2.2 SSH 免密连接一次配置长期省心HTTPS 方式每次 push 都要输密码很影响效率。我推荐全部换成 SSH。生成密钥的命令是ssh-keygen -t ed25519 -C your_emailexample.com一路回车生成在默认位置。然后执行cat ~/.ssh/id_ed25519.pub复制输出的内容打开 GitHub 的 Settings - SSH and GPG keys - New SSH key粘贴保存。测试是否配置成功ssh -T gitgithub.com看到Hi xxx! Youve successfully authenticated就说明通了。这一步配置好后后续所有 clone、push、pull 都不用输密码。2.3 创建组织与仓库把权限分清楚个人账号下建仓库不是不行但队伍协作我更建议建一个 Organization组织。组织的好处是有独立的成员管理和权限体系比如有成员离职你直接在组织里移除就行不用动仓库本身的代码。在 GitHub 首页点右上角头像选择 Settings - Organizations - New organization创建一个组织免费版够用。然后在组织里创建仓库记得勾选 Private私有还是 Public公开课程设计一般是 Private开源性质的项目才用 Public。创建完仓库后把队友加进组织并分配角色角色权限范围适合人群Owner完全控制包含删除仓库队长/负责人Member可以读写按仓库设置权限核心开发外部协作者只对指定仓库有访问权偶尔贡献的人组织创建完以后在组织页面创建仓库初始化时不要勾选Add a README file因为后面我要教你自己写更规范的初始化文件避免初次 push 产生冲突。2.4 初始化项目README、.gitignore、LICENSE 一步到位在本地创建一个项目文件夹然后执行mkdir team-project cd team-project git init先创建.gitignore文件。这个文件的作用是告诉 Git 哪些文件不要纳入版本管理比如 Python 的__pycache__、venv、.envNode 的node_modules。很多人没有这个文件结果把几百 MB 的依赖包全推到 GitHub 上仓库卡得不行。.gitignore写好后创建README.md把项目简介、目录结构、运行方式写清楚。建议用模板# 项目名 ## 项目简介 一句话说明项目做什么。 ## 技术栈 - 后端Python / Django - 前端Vue 3 - 数据库MySQL ## 快速开始 bash pip install -r requirements.txt python manage.py runserver目录结构建议用 tree 命令生成再整理如果项目是公开的建议加上 LICENSE 开源协议如果是私有课程设计可加可不加。 初始化完成后把代码推到仓库 bash git add . git commit -m chore: init repository with project skeleton git branch -M main git remote add origin gitgithub.com:your-org/your-repo.git git push -u origin main第一行提交记录建议用chore: init repository...比first submit、初始化有意义得多这个规范后面会详细讲。3. 日常协作流Issue 分工、分支命名与提交规范仓库建好了接下来是整个协作流程里最容易乱的部分。很多队伍失败就失败在没有任务分工、没有分支规范、提交信息乱写。这一部分我给出一个可以直接照抄的流程。3.1 用 Issue 把任务拆成能认领的卡片Issue 就是 GitHub 内置的任务卡片。队长拿到需求后第一件事不是安排人写代码而是把需求拆成一个个可执行的任务写好描述指定负责人。我常用的 Issue 模板## 需求描述 这个任务要做什么 ## 验收标准 - [ ] 用户能通过手机号登录 - [ ] 登录失败返回明确错误提示 ## 相关文件 - src/login/api.py - src/login/login_page.vue ## 关联分支 feature/login-12拆 Issue 有一个原则一个 Issue 尽量能在一天内完成。如果超过两天说明拆得不够细任务边界不清晰到后期统计进度会很痛苦。3.2 分支命名规范看一眼分支就知道在做什么分支命名直接反映了一个团队的工程素养。我推荐这种格式类型/功能描述-关联Issue编号举个例子feature/user-login-12bugfix/fix-timezone-issue-15docs/update-readmerefactor/optimize-query-18类型就用feature、bugfix、docs、refactor这几个不要自创。功能描述用英文短横线连接简单明确。创建分支的正确姿势# 先拉取 main 最新代码 git checkout main git pull origin main # 创建新分支并切换 git checkout -b feature/user-login-12这里有个关键细节一定要从最新的 main 分支开新分支而不是从别人已经落后几天的旧分支上开。否则你开发到一半合并回 main 的时候会撞上大量和功能无关的冲突。3.3 Commit 信息规范让 log 变得像一本书的目录多人协作时commit 信息写得好坏直接决定回溯问题的效率。这是我推荐的格式type(scope): subjecttype提交类型feat、fix、docs、style、refactor、test、chorescope影响范围模块名subject简要描述不要超过 50 个字符实际例子feat(auth): add user login API fix(api): correct error code for expired token docs(readme): update local development guide style(ui): format button spacing with prettier refactor(db): merge duplicate queries in user model test(auth): add unit tests for token validation chore(deps): bump requests to 2.31.0我看到很多队伍成员每次提交只写update你问他更新了什么他也说不出来。一个建议commit 信息应该能回答我做了什么改动为什么做这个改动。3.4 每天的同步动作把代码最新状态留住多人协作里有一个高频错误一开发就是几天不 pull等要提交了才发现别人的代码已经改得面目全非。正确习惯是每天开工前先同步 maingit fetch origin git checkout main git pull origin main git checkout feature/user-login-12 git rebase main这里用了git rebase而不是git merge。两者的区别是rebase 会把你分支上的提交重新放到 main 的最新提交之上让历史保持线性后面看 log 更清晰。刚开始不熟悉的话用git merge main也能解决只是会产生一个多余的 merge commit。开发完成推送时git add . git commit -m feat(auth): implement login page git push origin feature/user-login-12如果提示推送失败说明远端分支已经有别人提交了先 pull 再 pushgit pull origin feature/user-login-12 --rebase git push origin feature/user-login-124. Pull Request 与 Code Review把协作节奏固定下来进行到这一步代码已经写完了。但请不要直接把分支合并到 main我强烈建议所有改动都通过 Pull Request 合入哪怕你只是改了一个错别字。4.1 为什么不让直接推 main三个原因第一保护主干稳定。main 分支代表了当前可用的代码如果每个人都能直接改一个半夜上的错误提交就可能导致全队第二天拉下来的代码跑不起来。第二给代码留一个审查窗口。PR 提供了讨论和 review 的界面队友可以针对某一行代码给出意见这对提升代码质量至关重要。第三便于回溯。合并回 main 的每个 PR 都对应一个清晰的改动范围出问题时可以快速定位到是哪个 PR、哪次 review 引入的。所以在仓库设置里我一定建议把 main 设为保护分支禁止任何人直接 push。4.2 写一个让别人愿意看的高质量 PR 描述PR 描述是有模板的。我团队里用的模板长这样## 对应 Issue #12 ## 改动内容 - 新增用户登录接口 /api/v1/auth/login - 前端新增登录页组件 - 补充 token 过期处理逻辑 ## 测试情况 - 本地启动服务用 Postman 验证登录成功/失败两种情况 - 前端在 Chrome 和 Safari 下分别测试通过 ## 需要注意的点 - 数据库新增 users 表运行前请执行 python manage.py migrate模板的作用是强迫自己思考改动的影响面也让 reviewer 更容易看懂。4.3 Code Review 到底看什么Code Review 不是走形式。作为真正的团队经验我建议重点看四层功能性代码是否真的解决了 Issue 里的问题测试是否覆盖正确性有没有明显的边界错误、死循环、内存泄漏风险异常处理是否合理可维护性变量命名是否清晰函数是否过长有没有复制粘贴的重复代码安全性有没有把密码、密钥写进代码接口有没有做输入校验Review 评论要具体给出理由。比如你看到一段代码很绕不要说这个不太行而是说这里的循环嵌套太深建议抽成一个函数并且在数据量超过 N 时提前退出避免性能问题。4.4 合并策略Merge、Squash、Rebase 怎么选在 PR 合并页面GitHub 提供三个选项合并方式历史效果适用场景Create a merge commit保留所有提交产生一个 merge commit想完整保留开发痕迹Squash and merge把多个提交压缩成一个功能分支提交混乱时最推荐Rebase and merge线性历史不留 merge commit追求干净直白的 log我的默认推荐是Squash and merge因为大多数团队的分支上有feat: xxx、fix typo、update这种零散提交压缩成一个提交后再合入 main历史会非常干净。只有需要完整还原开发过程的时候才考虑 merge commit。5. 冲突处理实战从merge 红色告警到干净历史冲突是每个用 Git 的人绕不开的坎。不要怕冲突它本质上不是 Git 出了问题而是两个人改了同一个地方Git 不知道该听谁的。学会解决冲突你的协作才算真正入门。5.1 冲突是怎么发生的举例你和队友同时基于 main 分支开发。你在app.py第 10 行旁边加了一段登录逻辑队友基于同一个旧版本也在app.py第 10 行附近加了缓存逻辑。你们俩合并时Git 发现这一块代码既可以是你的版本也可以是队友的版本无法自动判断于是产生冲突。一句话理解冲突 两处修改在时间轴上重合了。5.2 一次标准冲突现场我模拟一个典型场景。假设你在分支feature/user-login-12上改了一行# app.py 第 10 行 def handle_request(request): user auth.login(request.user) # 你加的 return do_something(request)队友在分支fix/cache-15上也改了同一行附近# app.py 第 10 行 def handle_request(request): cache.set(key, request.data) # 队友加的 return do_something(request)当你的分支合并 mainmain 已经合并了队友的分支时Git 会报错Auto-merging app.py CONFLICT (content): Merge conflict in app.py Automatic merge failed; fix conflicts and then commit the result.5.3 解决冲突的完整步骤看到冲突提示后按顺序执行# 1. 查看冲突文件 git status # 2. 修改冲突文件用编辑器打开打开app.py你会看到类似这样的内容 HEAD cache.set(key, request.data) user auth.login(request.user) feature/user-login-12 HEAD到之间是当前分支main的版本到 feature/user-login-12之间是你分支的版本。解决冲突的目标不是选一边删掉另一边而是理解两边意图把它们都保留下来# 手动整合 def handle_request(request): user auth.login(request.user) cache.set(key, request.data) return do_something(request)保存文件后继续# 3. 标记为已解决 git add app.py # 4. 完成合并 git merge --continue # 也可以用 git commit但 --continue 更规范git merge --continue会自动打开编辑器让你填写 merge commit 信息默认的可以直接保存。5.4 想少踩冲突靠的是日常习惯解决冲突是基本功但减少冲突才是高手要思考的问题。我自己总结了几条切实有效的方式任务拆细同一个模块尽量只让一个人负责避免两个人在同一段代码上同时开工。小步提交宁愿一天提交 5 次也不要憋一周提交一次。提交间隔越长冲突面越大。及时 rebase开发前先 rebase main而不是把 main 合并进自己的分支后放任不管。多沟通你准备改一个公共函数签名前先在群里说一声。你是不是觉得这不是技术问题其实软件工程的大部分问题都不是纯技术问题。6. 团队维护者必做的保护策略与看不见的坑最后这部分是队长或者项目负责人需要看的。等你把前面流程都跑通会发现真正的坑往往不在命令上而在一些容易被忽略的细节里。6.1 开启分支保护规则在仓库页面的 Settings - Branches - Add rule 里设置 main 分支的规则。我会勾选这些Require a pull request before merging强制 PR 才能合并。Require approvals至少 1 人 review 通过。Dismiss stale pull request approvals when new commits are pushed有新提交时自动取消旧 review防止改了代码后旧review依然有效。Require status checks to pass before merging如果有 CI必须跑过才能合并。Do not allow bypassing the above settings禁止管理员绕过可选依队伍风格。这几个选项一开谁都不能绕过流程直接改 main。6.2 权限矩阵给你团队的每个角色配好权组织创建好后在 Repository Settings - Collaborators 里配置每个人的权限。我建议按这个表分配角色权限应做操作维护者Maintain管理仓库设置可合并 PR负责人写权限Write可推送分支、创建 PR核心开发者读权限Read只能读取和 fork只读成员/客户不要给所有成员 Maintain 权限否则有人误删设置或强行 merge PR你拦不住。团队里有谁需要操作 GitHub Actions 或管理 Release再单独升权限。6.3 几个经常踩的隐形坑我把带队过程中遇到最多的问题拉一个清单每一条都是真实项目里发生过的大文件入库GitHub 单文件超过 100MB 会直接拒绝。即使没超 100MB几十 MB 的文件也会拖慢 clone 速度。大文件该用 Git LFS或者根本别入库放到网盘、云盘单独管理。密钥和密码被提交.env文件、.pem密钥、数据库密码一旦进 git 历史即使删了也会留在 commit 历史里。解决办法是永远把此类文件写进.gitignore并检查历史git log --diff-filterA -- *.env换行符问题CRLF vs LFWindows 和 Linux 协作时文件换行符不同会导致 diff 显示整片文件被修改非常恼人。仓库根目录加一个.gitattributes文件* textauto *.py text eollf *.js text eollf *.json text eollf依赖版本不锁定Python 项目写requirements.txt时不要只写包名要把版本号也锁上如requests2.31.0。不然队友pip install出来的版本和你不一样跑出来的结果对不上。6.4 团队协作常用指令速查表最后给你们一张速查表打印出来贴显示器旁边都行场景命令拉取主分支最新代码git pull origin main创建功能分支git checkout -b feature/user-login-12查看当前状态git status提交所有改动git add . git commit -m feat: xxx推送新分支到远端git push -u origin feature/user-login-12用 main 最新代码更新当前分支git fetch origin git rebase origin/main查看提交历史git log --oneline --graph解决冲突后继续合并git add . git merge --continue我自己带团队从课程设计到正式项目最大的体会是GitHub 本身只是一个载体真正决定协作效率的是你们有没有把分支-提交-PR-Review-合并这套节奏固定下来。很多队伍一开始怕麻烦跳过 PR、跳过 Issue最后面对的就是难回溯的历史、频繁的冲突和这代码到底能不能跑的焦虑。换个角度想花半天时间把流程理顺后面整个项目周期都会轻松很多。如果你们团队连 GitHub 访问本身都经常超时我建议先排查网络环境或者考虑在 Gitee、自建 GitLab 上维护一份镜像仓库都可以核心协作流程完全一致。等网络稳定后再切回 GitHub不会有什么学习成本。如果你正在组建一个多人队伍不妨今天就把组织、仓库、分支保护三条规则建好拉上队友一起跑一遍 Issue 到 PR 的流程。第一周可能觉得多此一举等到项目收尾那天你会感谢当初这个决定。