我最早带团队的时候代码全靠 QQ 群里传来传去。今天是登录模块最终版明天是登录模块最终版2后天是登录模块打死也不改了。直到某次一个同事把整个项目的代码覆盖了别人改了三天的功能全组折腾了一整天才恢复我们才下定决心把 GitHub 用起来。如果你现在还在用压缩包和网盘管代码或者刚注册了 GitHub 但只会在网页上点来点去这篇内容就是给你写的。我尽量把建仓、提交、协作这三件事压缩到 30 分钟内讲透不讲废话全程以实际操作为主。你跟着敲一遍之后不管是自己写项目还是进团队协作都能直接上手。1. 建仓之前先把 Git 和 GitHub 的关系理清楚1.1 Git 是工具GitHub 是平台很多人刚接触时会把 Git 和 GitHub 当成同一个东西其实完全不是一回事。Git 是一个分布式版本控制系统它跑在你自己的电脑上负责记录你每一次代码改动让你可以随时回退、对比、分支开发。GitHub 则是一个基于 Git 的代码托管平台它把你本地的仓库同步到云端让团队里的每个人都能拉到同一份代码也能在上面做代码评审、提 Issue、管理任务。打个比方Git 是单机游戏里存档的功能GitHub 是让你把存档传到公共服务器上、还能和朋友联机的平台。没有 GitGitHub 就失去了意义没有 GitHubGit 也能在本地用但团队协作会非常麻烦。所以你在本地写代码时用到的所有 git 命令都属于 Git 本身只有 git push、git pull、git clone 这种和远程地址打交道的操作才真正涉及 GitHub。1.2 一次典型的协作流程长什么样在正式开始操作前先在脑子里建立全局概念。一个典型的 GitHub 协作流程是这样项目负责人创建一个仓库把初始代码推上去。成员把仓库克隆到本地开始开发新功能或者修 Bug。开发完一部分先在本地提交commit再推送到远程分支。在 GitHub 网页上发起 Pull Request简称 PR请求把自己的改动合并回主分支。负责人或其他成员在 PR 里评审代码、提意见。通过后合并所有人拉取最新代码继续下一轮。这个过程中最核心的三个动作就是建仓、提交、协作下面我按这个顺序拆开讲。1.3 账号准备与 SSH 配置开始之前你需要注册一个 GitHub 账号。注册完成后我强烈建议你先把 SSH 密钥配好因为后面用 HTTPS 方式推送代码时每次都要输用户名和密码现在还要用 Personal Access Token更麻烦而 SSH 配置一次以后所有仓库都能免密推送。配置 SSH 的步骤# 在本地生成密钥对 ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车即可默认会生成在~/.ssh/id_ed25519和~/.ssh/id_ed25519.pub。公钥.pub后缀的那个文件里的内容是要给 GitHub 的。打开 GitHub 网页进入 Settings → SSH and GPG keys → New SSH key把公钥内容粘贴进去保存。然后在本地测试ssh -T gitgithub.com如果看到Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.说明 SSH 配置成功。这里有个新手容易忽略的点生成密钥时如果用默认文件名Git 会直接读取id_ed25519如果你改了文件名需要自己在~/.ssh/config里指定否则后面推送会报 Permission denied。2. 建仓篇从网页点按钮到本地 git init2.1 网页端创建仓库的每一步建仓库GitHub 里叫 create a repository中文常叫建仓是第一步。打开 GitHub 首页右上角点那个 New repository 的加号按钮进入创建页面。几个关键选项这样填Repository name仓库名建议用小写字母、数字和连字符比如my-first-project。不要用中文不要有大写团队项目更要注意统一命名风格。Description一句话描述这个仓库是干什么的可填可不填但建议填别人一眼能看懂。Public / PrivatePublic 是所有人都能看到Private 只有你和邀请的协作者能看到。个人练习项目建议直接 Public还能装点主页公司项目一律 Private。Add a README file是否同时生成一个 README 说明文件建议勾上。Add .gitignore按项目语言选择对应的忽略规则文件。Choose a license开源协议个人项目可以先不选后面要开源再补。点 Create repository 后仓库就建好了。这时候网页上会显示三种推送方式分别对应从命令行创建新仓库、推送已有本地仓库、从其他仓库导入。新手最常用的是第三种场景也就是本地已经有代码想把它交给 GitHub 管理。2.2 本地初始化并关联远程git init、git remote add假设你本地已经有一个项目文件夹里面已经有代码了。要在本地把它变成 Git 仓库再关联到 GitHub 上刚建的那个空仓库操作如下cd 你的项目目录 git init git add . git commit -m Initial commit git branch -M main git remote add origin gitgithub.com:你的用户名/你的仓库名.git git push -u origin main这几行命令是整篇内容里最核心的我逐个解释一下git init在当前目录初始化一个仓库会生成一个隐藏的.git文件夹你的所有版本记录都存在这里面。如果初始化后发现.git目录都没看到先检查一下文件资源管理器是否开启了显示隐藏文件。git add .把当前目录下所有文件加入暂存区就是把准备提交哪些文件这件事告诉 Git。后面我会细讲暂存区。git commit -m Initial commit把暂存区的内容正式提交为一个版本-m后面是本次提交的说明。git branch -M main把默认分支名从 master 改成 main。GitHub 现在默认主分支就叫 main本地初始化时默认可能是 master这里统一一下。git remote add origin ...给远程仓库起个名字origin并关联地址。以后推送都用origin代替那一长串地址。git push -u origin main把本地的 main 分支推送到远程-u的意思是建立本地分支和远程分支的追踪关系之后你直接敲git push就能推送不用再写参数。执行完最后一行刷新 GitHub 仓库页面就能看到你的代码了。这个时刻对很多新手来说是很有成就感的我第一次推送成功的时候盯着网页看了半天。2.3 README 与 .gitignore仓库的门面与护栏README 和 .gitignore 这两个文件在新建仓库时很容易被忽略但实际项目里它们非常重要。README.md 是仓库的门面任何人点进你的仓库第一眼看到的就是它。内容至少应该包含这个项目是做什么的、怎么安装、怎么运行、目录结构、使用的技术栈。写得好的 README 不仅能帮别人快速上手也能逼你自己梳理项目。用 Markdown 语法写支持标题、列表、代码块、图片GitHub 会自动渲染成漂亮的页面。.gitignore 是护栏用来告诉 Git这些文件不要纳入版本管理。典型的需要忽略的内容包括依赖目录比如 Node.js 项目的node_modules、Python 项目的venv或.venv。编译产物比如dist、build、target。IDE 配置文件比如.idea、.vscode团队如果有统一配置则另说。日志文件、临时文件、环境变量文件比如.env里面通常有密钥绝不能提交。如果一开始忘建 .gitignore已经把依赖目录提交上去了后面要移除会比较麻烦。我的建议是仓库一建立就把 .gitignore 配好哪怕先写个基础的后面再慢慢补。等你经历过一次把密码或密钥提交到公共仓库的事故就明白这个文件有多重要了。3. 提交篇把代码交给 Git 的完整流程3.1 工作区、暂存区、版本库三层模型很多新手把git add和git commit当成一步来记觉得不就是提交代码嘛。但如果搞不懂它们为什么是分开的两个步骤后面遇到怎么撤销提交怎么只提交一部分文件这类问题时就会很懵。Git 的三个核心区域工作区你电脑上看得见的那些文件和文件夹日常编辑代码就是在这里。暂存区一个临时存放区执行git add后文件改动会先进入这里。它相当于购物车你可以往里面放一部分商品也可以放全部最后统一结账。版本库执行git commit后暂存区里的内容会被打包成一个不可变的版本记录存进版本库。每个版本都有一个唯一的 commit hash一串十六进制字符以及提交人、时间和提交说明。为什么要设计暂存区因为实际开发中你可能同时改了三个功能但只想先把其中一个功能的改动提交了。有了暂存区你可以精准地选择哪些改动进入本次提交做到提交粒度与功能边界一致这在团队协作中是很加分的习惯。3.2 git add、git commit、git push 的正确姿势日常最常用的提交流程是这样的git status # 查看当前改动状态 git add 文件或目录 # 把指定文件加入暂存区 git diff --cached # 查看暂存区里的具体改动 git commit -m feat: 新增登录接口 # 提交 git push # 推送到远程其中git status和git diff --cached这两个命令一定要养成习惯。git status能告诉你当前哪些文件改了、哪些已经加入暂存区、哪些还没。git diff --cached能让你在提交前最后检查一遍改动内容避免把自己随手写的调试代码一起交上去。这里有一个非常实用的技巧提交前先看一眼 diff。尤其是console.log、print、debugger这种调试语句以及不小心改错的格式都可能在最后检查时被发现。我见过太多人在代码评审环节被同事问这个 console.log 是干嘛的就是因为提交前没看 diff。另外git add .这种全量添加虽然方便但有时会把不该提交的文件加进来。建议尽量用git add 具体文件或git add 目录明确告诉 Git 你要提交什么。如果你想提交多个文件但又不想一条条敲可以用通配符比如git add src/把src目录下的所有改动加入暂存区。3.3 提交规范commit message 怎么写得让别人看得懂提交信息看起来只是几个字的说明实际是团队的操作日志。三个月后你想查这个配置是哪个版本加的靠的就是 commit message。没有规范的项目提交信息五花八门什么update、修改、fix、aaa都有查起来非常痛苦。业界比较通用的是 Conventional Commits 规范格式是类型(范围): 描述。常见的类型feat新功能fix修复 Bugdocs文档改动style不影响代码逻辑的格式调整空格、分号等refactor重构既不是新功能也不是修 Bugtest测试相关chore构建或辅助工具的变更示例git commit -m feat: 新增用户注册接口 git commit -m fix: 修复登录状态下刷新页面丢失 session 的问题 git commit -m docs: 更新 README 部署说明描述建议用中文或英文都行关键是团队统一。描述本身要能说明为什么做这个改动而不只是改了什么。比如fix: 修改登录 bug就不如fix: 修复 token 过期后跳转登录页死循环的问题信息量足。我还建议提交粒度尽量小一些。一个提交只做一件事这样出问题时可以精确回退到某个版本代码评审时也更好理解。宁可提交十次小的、逻辑清晰的改动也不要攒一周然后一次提交几千行代码。3.4 改错了怎么办commit --amend、reset 与 revert提交之后发现有问题是新手特别容易慌的场景。这里分三种情况第一种刚提交完发现漏了一个文件或者想补充说明但还没推送到远程。这时候用git commit --amend -m 新的提交信息这个命令会把当前暂存区的内容追加到上一次提交里同时允许你修改提交信息最终合并成一个新的提交。但注意--amend会重写提交记录如果已经 push 到了远程并且是多人协作的分支就不要用了会和其他人的历史冲突。第二种提交后发现改动根本不需要想撤回但保留改动内容回到工作区git reset --soft HEAD~1HEAD是当前所在提交的指针HEAD~1表示上一个提交。--soft只是把提交撤销改动内容会保留在暂存区。如果想把暂存区也清空改动全部回到工作区用git reset --mixed HEAD~1这是默认行为如果想彻底丢弃这次提交的所有改动用git reset --hard HEAD~1。最后这个命令非常危险因为改动会彻底消失不可恢复。用之前一定确认自己不需要这些改动了。第三种提交已经推送到远程其他人也拉取了这个提交。这时候不要用 reset 去重写历史而是用 revert 生成一个新的反向提交git revert commit hashrevert 的好处是它不改变历史只是生成一个相反的提交把之前的改动翻回去这样其他成员的本地分支拉取后不会出现历史分叉。4. 协作篇分支、Pull Request 与代码评审4.1 分支就是平行宇宙单人的时候你可能不需要分支但一旦进入团队协作分支就是最基本的组织方式。分支可以理解为从某个提交点分出来的平行开发线各条线上的改动互不干扰最后可以合并到一起。一个典型的分支工作流是 Git Flow 的简化版也叫 GitHub Flowmain分支始终处于可发布状态所有已合并的代码都是经过评审的。功能分支从 main 分支拉出来命名通常和功能相关比如feature/login、fix/issue-123。创建和切换分支git checkout main git pull git checkout -b feature/logingit checkout -b等于创建并切换到新分支。新分支上的所有提交都是独立的不会影响 main 分支。等开发完毕把分支推送远程然后发起 Pull Request 请求合并。为什么要用 Pull Request 而不是直接把代码推到 main 分支因为 PR 提供了一个评审入口。发起 PR 后团队成员可以看到你的完整改动、逐行评论、提出修改意见CI 也可以自动跑测试通过后才允许合并。这个过程极大地降低了垃圾代码直接进主干的风险。4.2 完整 Pull Request 流程假设你在feature/login分支上开发完了登录功能现在想合并到 main。流程是先把分支推送到远程git push -u origin feature/login打开 GitHub 仓库页面会看到一个提示条Compare pull request按钮点它。在 PR 创建页面左边选目标分支main右边选你的功能分支确认改动范围和内容没有误加。填写 PR 标题和描述。标题建议直接用一句完整的话描述里写清楚这个 PR 做了什么、为什么做、测试过什么场景。如果有关联的 Issue在描述里输入#就能关联。指派 Reviewers评审人、Assignees负责人、Labels标签然后点 Create pull request。发起后评审人会在 PR 里逐行看代码。如果他们提出了修改意见你直接在本地对应的分支上修改、提交、推送PR 会自动更新不需要重新发起。这个一个 PR 对应一个分支持续更新的机制是理解协作流程的关键。合并的方式有三种GitHub 会给你选Create a merge commit保留所有提交历史生成一个合并提交。Squash and merge把分支上的所有提交压缩成一个提交再合并历史干净适合功能分支。Rebase and merge把分支上的提交逐个重放在 main 分支上历史是线性的。小型团队我建议用 Squash and merge因为功能分支上那种WIP、fix typo、oops的提交没有保留价值压成一个feat: 完成登录功能提交干净利落。4.3 冲突处理实战合并冲突是协作中躲不开的场景。它发生的根本原因是两条分支修改了同一个文件的同一部分Git 不知道应该保留谁的。举个例子你和同事同时改了config.js的第 10 行你先合并了你的 PR同事的 PR 再合并时就会冲突。GitHub 会在 PR 页面明确提示conflict要求你解决后才能合并。解决冲突的正确流程本地切到目标分支并拉取最新代码git checkout main git pull git checkout feature/login git merge main这时如果有冲突Git 会提示冲突文件文件里会出现类似这样的标记 HEAD 这里是你当前分支的内容 这里是被合并分支的内容 main手动编辑文件保留你想要的最终结果然后删掉、、这些标记。保存文件后git add 冲突文件 git commit -m merge: 解决 config.js 冲突 git push冲突解决的核心原则是一定要理解双方改动的意图再决定保留谁不要图省事全部保留或者全部删除否则可能生产事故。解决完冲突最好再跑一遍相关测试。4.4 从 0 到 1 的团队协作约定工具只是基础真正能让团队顺畅协作的是约定。我在带团队时用过一套很简约的规则分享给你参考main 分支受保护不允许直接推送所有改动必须通过 PR 合并。GitHub 仓库设置里可以在分支保护规则中勾选 Require pull request reviews before merging。每个功能一个分支分支名统一为类型/描述比如feat/login、fix/payment-bug。每次提交只做一件事commit message 遵循 Conventional Commits 规范。每天开始开发前先git pull结束开发前确认代码能跑通再提交推送。关联 Issue比较大的功能先建 Issue 描述需求再在 PR 中关联方便追溯。这套规则不需要一步到位可以先从分支 PR 提交规范三条开始跑顺了再加保护规则和 CI。5. 常见报错与排查实录这部分是我想重点分享的因为我自己踩过太多坑也看过太多新手在群里问同样的问题。我把最常见的报错整理成一个速查表后面再详细说几个典型的。5.1 认证相关报错报错信息Permission denied (publickey)这是 SSH 密钥没配置好或者没生效。排查思路ssh -T gitgithub.com如果也是 Permission denied检查.pub公钥是否真的粘贴到了 GitHub 上检查本地密钥文件是否存在如果你用了多个 SSH key检查~/.ssh/config是否配置了正确的 IdentityFile。报错信息remote: Support for password authentication was removed./could not read Username2021 年之后 GitHub 不再支持用账号密码做 Git 操作必须使用 Personal Access Token。解决办法是到 GitHub Settings → Developer settings → Personal access tokens 生成一个 token然后把它当作密码输入。更一劳永逸的做法是切到 SSH 方式一劳永逸就不用来回填 token 了。查看当前远程地址git remote -v如果显示的是https://github.com/开头说明你在用 HTTPS 方式可以考虑切换为 SSH 地址。5.2 提交与推送相关报错报错信息git push -u origin main一直不成功这个问题的原因很多先看的永远是两条一是网络能否访问 GitHub二是远程分支是否领先。如果远程 main 分支有其他人推了新提交你的 push 会被拒绝提示! [rejected]或failed to push some refs。解决办法是先git pull把远程的改动拉到本地合并再 push。报错信息fatal: not a git repository说明当前目录不是 Git 仓库确认是否在正确的目录下或者忘记执行git init了。报错信息fatal: origin does not appear to be a git repository说明远程地址没有设置。用git remote add origin 仓库地址配置后再试。报错信息Please make sure you have the correct access rights也是认证问题按 5.1 的流程排查。5.3 IDE 提交报错实录VSCode 提交时报There are no staged changesVSCode 的源代码管理面板里改动文件需要先点文件旁边的加号暂存再输入提交信息点提交。如果直接提交会提示没有已暂存的更改。理解了暂存区概念后这个报错就不会再困扰你了。IDEA 提交时报Commit Author is not correct/ 提交信息显示为其他人这种情况一般是本机 Git 全局配置的用户名和邮箱不是你的代码里认的是邮箱不是用户名。修改方法git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com如果只改当前仓库就去掉--global。改完后用git log查看历史如果之前的提交作者不对可以用git commit --amend --reset-author修正上一次提交的作者。另外注意GitHub 识别提交人靠的是邮箱。你必须用注册 GitHub 时绑定的邮箱提交推送后提交记录才会关联到你的 GitHub 账号。如果邮箱不匹配提交会显示成无名小卒头像都挂不上。5.4 日常操作避坑清单最后整理几条我经历过血泪教训后总结的避坑经验提交前坚决看 diff不把调试代码混进正式提交。不要在 main 分支上直接开发哪怕是个人项目也养成开分支的习惯。推送前先 pull合并冲突的代价永远大于先拉取一次代码的代价。.env和其他含密钥的文件绝对不要提交。一旦提交过光删文件不够密钥依然在历史记录里需要更换密钥。不要用git reset --hard去处理已经推送过的提交后果是历史分叉队友会想打你。大文件不要提交到 Git 仓库Git 设计上就不是为了管大文件用的。频繁使用git status和git log --oneline两个命令一个看当下一个看历史非常有用。6. 一些实操心得权当聊天写了这么多其实工具层面的东西就那么点真正难的是习惯的养成。我自己刚用 GitHub 的时候也犯过一天提交一个大版本的毛病直到有一次需要回退某个功能却发现不知道在哪次提交里加的才老老实实开始写规范提交信息、小步提交。后来带新人我总结了一个比较顺的学习路径先用个人项目把建仓、提交、推送跑通然后自己给自己开分支、合并体会分支的隔离感接着找一个开源项目挑一个简单 Issue 去提 PR走一遍完整的评审流程。这三步走完GitHub 协作的基本面你就都见过了。再分享一个小技巧GitHub 的git log --oneline --graph --decorate可以看到整个分支历史的关系图这个命令对理解分支合并非常直观。我刚开始带团队时遇到新人问分支到底怎么分出来又合回去我就让他们输这个命令看看比讲半天概念都管用。如果你还有余力GitHub 上还有很多值得研究的内容比如 Actions 自动化构建、GitHub Pages 部署个人网站、组织Organization管理多团队、Code Review 文化等等。但这些都是在你把基础协作流程跑顺之后的事了。先把建仓、提交、协作这三件事做扎实不管以后换什么平台、进什么团队底层逻辑都是通的。