蔡振原我带过好几届实习生，几乎每个人第一次打开GitHub的时候都会露出相似的表情：页面密密麻麻，英文为主，又是什么Repository又是Star，完全不知道从哪儿下手。问得最多的一个问题就是：“GitHub到底怎么学？我跟个教程，感觉跟在学外语一样。”其实GitHub没你想的那么神秘，它核心就干两件事：帮你把代码存到云端做版本管理，以及让一群人能协作写同一个项目。这篇教程我就按我自己带新人的路子来，不整虚的，从概念、安装、配置，到第一次真正把一个项目跑起来，再到给开源项目提交代码，一步一来，你跟着做一遍基本就入门了。适合完全没接触过Git和GitHub的小白，也适合用过GitHub但一直没搞明白原理、只会点网页按钮的人。
1. 先把概念掰扯清楚：Git和GitHub不是一回事
1.1 Git是本地帮你记历史的“时光机”
很多人把Git和GitHub当成一个东西，其实这俩是两码事。Git是一个版本控制工具，装在你自己的电脑上，完全离线就能用。它的作用是记录你文件夹里每次修改的“快照”：你改了哪些文件、加了哪些行、删了哪些行、在什么时间改的，全部记下来。就像打游戏时的存档点，玩崩了可以回退到任意一个存档位置，不至于从头再来。
我用一个写论文的类比你就懂了。你写毕业论文，最原始的操作是建一堆文件：论文终版、论文最终版、论文最终修改版、论文打死不改版……Git解决的就是这种痛苦。它只维护一份文件，每次你写完一小段就提交一次（commit），提交时写一句话说明“这次改了什么”。以后想找回三天前那个被你删掉的段落，一条命令就能看历史记录，还能随时把文件恢复到那个时间点。
Git的另一个核心能力是分支（branch）。你可以理解成在看一部剧时，用一个分支正常追剧，另开一个分支去研究“如果男主当初不这么做会怎样”。两个分支互不干扰，研究完了觉得好，就合并回主剧情；觉得不好，直接扔掉，不影响主剧。这个机制在多人协作时特别关键，后面我会细说。
1.2 GitHub是云端仓库和协作广场
Git是工具，GitHub则是基于Git构建的一个在线托管平台。你把本地Git记录的这些“存档”推送到GitHub的服务器上，就多了一份云端备份，电脑硬盘坏了也不怕。更重要的是，别人也能看到你的仓库，可以下载你的代码、给你提建议、改你的代码再发回来。
打个比方：Git是你自己书房里的档案管理系统，GitHub是把你的档案公开展览在图书馆里，同时允许其他人来借阅、写批注，甚至帮你修订几页再还回来。全世界无数开源项目都放在GitHub上，像Linux的很多核心组件、React、Vue、Python的各类库，你都能找到源码。
1.3 初学者最容易踩的三个认知误区
第一个误区是以为GitHub只是个“存代码的网盘”。它确实能存代码，但不止于此。很多人在GitHub上写个人博客、整理学习笔记、放简历、管理自己的电子书库，甚至单纯用来做文件备份。仓库（Repository）里不一定非得是工程代码，你往里面传Markdown文档也没问题。
第二个误区是以为自己必须把命令背得滚瓜烂熟才能用GitHub。实际上初学者只需要掌握六七个命令就能顺畅操作，剩下的全是在遇到具体问题时再现学现用。我到现在写文章时用Git，也无非就是add、commit、push、pull这几板斧。
第三个误区是把GitHub当成QQ空间怕发错东西被人笑。GitHub上确实大佬云集，但绝大多数项目都是普通人维护的，你建个仓库放自己的练习代码没人笑话你，自己的学习过程被记录下来反而容易吸引同路人。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 开始之前：把Git环境和账号准备齐
2.1 Git安装的完整流程
在Windows上装Git，直接去官网下载Git for Windows，下载完以后双击安装。有几个安装界面要提醒你：安装路径可以默认；组件选择页，默认选项已经够用；“Adjusting your PATH environment”这一页一定要选第二项“Git from the command line and also from 3rd-party software”，因为后面在PowerShell或cmd里敲git命令全靠这个选项；行结束符处理选默认的“Checkout Windows-style, commit Unix-style line endings”即可，避免团队协作时因为换行符问题产生一堆无意义的diff。
macOS用户很简单，终端里执行xcode-select --install，Apple会帮你把Git装好。如果装了Homebrew，也可以brew install git，版本还会更新一些。Linux用户根据发行版来，Ubuntu/Debian系执行sudo apt install git，CentOS/RHEL系执行sudo yum install git。
装完以后，在新开的终端里敲git --version，能输出版本号就说明装好了。这一步百试百灵，如果提示找不到命令，九成是终端没重开或者PATH配置出了问题，具体排查我放到第七部分讲。
2.2 第一次配置：用户名、邮箱和SSH密钥
安装好以后，先告诉Git你是谁，这样每次提交你都会有署名。打开终端，执行：
bash复制git config --global user.name "你的GitHub用户名"
git config --global user.email "你注册GitHub用的邮箱"
注意用户名和邮箱要跟你GitHub账号保持一致，这样你提交的代码在GitHub上才会正确显示到你的头像下面。还有一步是换行符和凭证存储的优化，可以顺手做掉：
bash复制git config --global core.autocrlf input
git config --global credential.helper store
然后配置SSH密钥。这一步对新手来说最容易卡壳，但它是实现“免密操作”的关键。原理很简单：你电脑生成一对密钥（公钥和私钥），把公钥填到GitHub的后台，GitHub以后看到这把公钥就认得你，你推送代码时就不用每次输账号密码。
bash复制ssh-keygen -t ed25519 -C "你的邮箱"
终端会问保存路径，直接回车用默认的~/.ssh/id_ed25519；又问你输入密码，你可以设置一个口令也可以留空直接回车。生成完成后，执行cat ~/.ssh/id_ed25519.pub，把输出的一整段以ssh-ed25519开头的文本复制下来。然后登录GitHub，点头像 → Settings → SSH and GPG keys → New SSH key，标题随便写，Key粘贴进去保存。最后验证是否成功：
bash复制ssh -T git@github.com
看到“Hi 你的用户名! You've successfully authenticated”就对了。这段配置一劳永逸，配合HTTPS方式，能省掉后面无数输密码的麻烦。
2.3 理解配置的三个作用域
Git配置分为系统级、全局级和仓库级三层。系统级影响这台电脑上所有用户，全局级影响当前用户的所有仓库，仓库级只影响当前这个仓库。优先级是仓库级 > 全局级 > 系统级。新手不用管系统级，只需要知道全局配置用--global，仓库级配置就是到某个仓库里执行不带--global的git config命令。
举一个常见场景：你的个人电脑用个人邮箱提交代码，公司项目需要用公司邮箱。这时候在个人全局配置里填个人邮箱，然后进到公司项目目录下单独执行git config user.email "公司邮箱"，这个项目就自动用公司邮箱提交了。这是刚入职团队或者自己拿公司电脑搞开源项目时一定会用到的知识点。
3. 第一次上手：克隆一个开源项目到本地
3.1 怎么找到值得“抄”的项目
初学者别一上来就想写什么惊天动地的项目，先学会“抄”。GitHub上有海量的优质项目，先找自己感兴趣的、能跑得起来的、代码量不太大的项目读一读跑一跑，进步最快。
找项目有几个实用路子。第一是搜awesome系列，比如awesome-python、awesome前端，这些仓库把某领域最好的资源全部汇总好了，质量有保证。第二是按语言筛选，GitHub的Explore页面可以按编程语言浏览热门仓库，Python、JavaScript、Go都能单独看。第三是从课程里找，你学某个技术栈时教程一般会配一个示例仓库，跟着学最合适。第四是看Star数，虽然不绝对，但一个仓库如果积累了上万个Star，通常说明它在某方面确实做得好。
以经典的Hello World级别项目为例，你可以在GitHub搜“html-css-js Portfolio Template”，找一个看起来简单、文档里有截图的项目来练手。
3.2 克隆项目的两种地址：HTTPS还是SSH
每个仓库主页都有一个醒目的绿色Code按钮，点开能看到两个关键的地址格式：HTTPS和SSH。HTTPS长这样：
bash复制https://github.com/用户名/仓库名.git
SSH长这样：
bash复制git@github.com:用户名/仓库名.git
对初学者来说，如果已经按2.2配好了SSH key，直接选SSH地址最省心，第一次clone完以后，后续的push、pull都不会再问你要密码。HTTPS方式第一次推送代码时会要求输入GitHub的登录凭证，而且现在GitHub已经不支持用账号密码当密码来推代码了，必须要用Token，新手容易在这里卡住。所以我的建议很明确：配好SSH，用SSH地址。
3.3 克隆下来之后怎么开始看代码
找到项目后，复制地址，然后在你本地想存放代码的目录下执行：
bash复制git clone git@github.com:用户名/仓库名.git
Git会把这个仓库的全部版本历史下载到当前目录下。如果你的网络环境一般，或者项目特别大，建议先做一次“浅克隆”：
bash复制git clone --depth 1 git@github.com:用户名/仓库名.git
浅克隆只拉取最新一次提交的快照，不带历史记录，传输量小很多，对只想看看代码、跑跑项目的初学者完全够用。等到你真正需要翻历史的时候，再用完整克隆拉一遍。
克隆完成以后，先别急着到处乱点。我的习惯顺序是：先读README，这是项目的说明书，告诉你项目是干什么的、怎么安装、怎么运行；再看目录结构，一般会分为源代码、文档、测试、配置文件等；然后找package.json、requirements.txt这类依赖清单文件，了解这个项目用了哪些东西；最后看入口文件，比如main.py、index.js，从入口开始捋代码执行流程。新手不必要求自己全部看懂，能跑起来就成功了一大半。
4. 参与开源的第一步：Fork + 修改 + Pull Request
4.1 Fork到底在做什么
Fork是GitHub上一个很妙的机制。你想改别人的项目，但没有权限直接往原仓库里推代码，于是你点一下Fork，GitHub会在你的账号下生成这个仓库的完整副本。这个副本归你所有，你想怎么改就怎么改。
用一句话概括Fork：把你喜欢的项目“复印”一份到自己名下，然后在这个副本上自由发挥。你改完以后如果觉得自己的改动对原项目也有价值，就可以发起Pull Request（简称PR），请求原作者把你做的修改合并到他的仓库里。
4.2 动手改点东西：从修文档开始
我强烈建议新手第一次PR从改文档开始，比如修正README里的错别字、补充某一步安装说明、更新一个失效的链接。改文档不需要你写复杂代码，流程却能完整走一遍协作链路，而且还真的能帮到项目维护者，几乎所有项目都欢迎这种贡献。
具体步骤是这样。第一步，打开目标项目，点Fork，等它复制完成。第二步，把你自己账号下的这个仓库克隆到本地：
bash复制git clone git@github.com:你的用户名/仓库名.git
第三步，为了不动坏主线，新建一个分支再改：
bash复制git checkout -b fix-typo
第四步，用编辑器打开README，把错别字改掉，然后把这个文件加入暂存区并提交：
bash复制git add README.md
git commit -m "docs: fix typo in README"
4.3 发Pull Request的正确姿势
提交完成后，把分支推到你的远程仓库：
bash复制git push origin fix-typo
然后去GitHub页面，你的仓库上方会弹出一条黄色横幅，提示你在某个分支上有新提交，旁边有个Compare & pull request按钮，点进去。在PR页面里，你要写清楚这次改了什么、为什么改、有没有测试过。标题就写“docs: fix typo in README”，描述简单一两句话说明修改内容。确认无误，点Create pull request。
发完PR后，原作者会看到你的请求，可能直接合并，也可能提修改意见。如果被要求修改，你就在本地继续改，add、commit、push，PR会自动更新，不需要重新发一个新PR。
这里有几个容易踩的坑。第一，一条PR只做一件事，改文档就只改文档，别顺手把代码也改了，维护者合并时会很头疼。第二，PR之前看一眼项目里有没有CONTRIBUTING.md文件，很多项目会把贡献规范的写在那里。第三，别给大型热门项目胡乱提PR刷存在感，这种维护者每天收到几十条PR，质量不高的通常直接关掉。
5. 建立自己的仓库：从0到1走通完整流程
5.1 在GitHub上新建仓库
参与完别人的项目，你该有自己的一块地了。登录GitHub，右上角点加号，选New repository。仓库名起一个简单能认出来的，Description可以简单写两句这仓库是干嘛的。下面那个Initialize this repository with a README，我建议初学者暂时不要勾选，因为如果你勾了，GitHub上会生成一个带README的仓库，你本地推代码时如果两边历史不一致，还要先处理一次pull合并，对新手不友好。我们先保持空的远程仓库，从本地推内容上去，路径最简单。
可见性这里要注意：Public是所有人都能看到，Private只有你和被你邀请的人能看到。存学习代码、草稿、练习作品，建议先用Private，等你觉得拿得出手了再改成Public也来得及。
5.2 本地工作流：add、commit、push
假定你在本地有个文件夹叫my-first-project，里面已经写了点东西。在终端进到这个目录：
bash复制cd my-first-project
git init
git init会在当前目录创建一个.git隐藏文件夹，把这里变成一个Git仓库。接着把刚才云上建好的远程仓库地址关联过来：
bash复制git remote add origin git@github.com:你的用户名/my-first-project.git
现在你的本地仓库和远程仓库算是认识了。接下来就是Git最核心的三连操作：
bash复制git status
git add .
git commit -m "feat: 初始提交，创建项目基础结构"
git status查看当前哪些文件有变动；git add .把当前目录的所有改动放进暂存区（staging area），这个区域相当于一个待提交清单；git commit把暂存区的内容打包成一个快照，写清楚说明文字。提交之后本地仓库就有了第一条记录，但它还在你的电脑上。最后推送到GitHub：
bash复制git push -u origin main
push可能失败，最常见原因是GitHub新仓库现在默认分支叫main，而你本地git init默认分支是master。如果提示分支名不匹配，先执行git branch -M main再推送。推送成功后你刷新GitHub页面，代码就出现在上面了。
写提交信息有个不成文的公约，我建议新手一上来就养成习惯：用feat表示新功能，用fix表示修bug，用docs表示改文档，用refactor表示重构代码。后面加分号写一句简短描述即可，像feat: 添加登录页面这样的格式。
5.3 几个高频git命令和对应的真实场景
Git命令不用背，但有几个高频的必须烂熟于心。
- git status：随时查看当前仓库的工作状态，看哪些文件还没提交。改代码之前先敲一下，心里有底。
- git diff：看具体改了什么内容，适合在提交前确认自己没有改错地方。
- git log --oneline：查看提交记录，每一行就是一条commit。
- git pull：从远程把最新代码拉下来。团队协作时，动手干活之前先pull一次，能把很多冲突消灭在萌芽里。
- git push：把本地提交推送到远程。
- git branch：查看当前有哪些分支，带*的是当前所在分支。
- git checkout：切换分支，比如git checkout -b new-branch就是从当前分支分叉出一个新分支并切过去。
我见过太多新手遇到问题的原因，就是压根不看git status的提示。Git这个工具非常啰嗦但非常友好，它会告诉你“你有文件没提交”“你有冲突要解决”。执行命令之前先跑一遍git status，你的成功率会高一大截。
6. 版本管理进阶：回到过去和保存现场
6.1 git log和回滚操作
版本管理最强大的地方在于可以反悔。git log --oneline能列出你的提交历史，每一行前面那一串黄颜色的字符就是commit哈希，像fe3a9c1就是这次提交的唯一标识。
假设你不小心删掉了一个重要文件，而且已经提交了，现在想找回。最简单的办法是把整个项目回退到删除之前的那个提交。这里要区分reset和revert。
bash复制git reset --hard 目标提交哈希
reset会直接把当前分支的HEAD指针挪到目标提交上，工作区的代码也跟着变成那个提交的状态。但它会丢弃这期间的所有提交记录，所以如果这些记录已经推到了远程，就会和别人远程的代码冲突，这种场景下慎用。
bash复制git revert 目标提交哈希
revert的操作是“反着再提交一次”，它会生成一个新提交，把目标提交的改动抵消掉，但旧提交记录还在，不会改写历史。协作场景里，已经推到远程的提交要回滚，用revert而不是reset，这是让我踩过好几次坑才长记性的教训。我跟你说，有一次我在公司项目里用reset回滚了一个同事的提交，又强制推送，结果那个同事拉代码时直接懵了，一堆本地改动的分支全对不上，我们几个人花了一下午才把现场收拾干净。从此以后我只要操作远程共享分支，一律用revert，只有没推出去的本地提交才敢用reset。
6.2 .gitignore的正确用法
你有没有遇到过这种场景：本地跑项目生成了一个node_modules文件夹，里面几万个文件；配置里还有.env之类的密钥文件，里面存着数据库密码。如果你一股脑git add .，不仅提交巨慢，还可能把敏感信息传到GitHub上，等于把钥匙挂在门口。
解决方法是建一个.gitignore文件，把不想纳入版本管理的文件或目录写进去。GitHub在创建新仓库时会提供一堆现成的模板，你选对应的语言就能自动生成。手动写也很简单，比如：
text复制node_modules/
.env
dist/
__pycache__/
*.log
每一行是一个忽略规则，/结尾表示目录，表示通配。node_modules/就是忽略整个目录，.log就是忽略所有后缀为.log的文件。遇到一个诡异的问题：为什么同事没提交node_modules还能跑起来？因为他克隆下来以后执行了npm install或pip install，依赖会按package.json或requirements.txt重新安装一遍。配置文件就是干这个用的，所以不用担心别人拉走你的代码跑不起来。
6.3 分支与合并的入门理解
初学者可能觉得分支是高级玩法，其实分支的使用非常日常。GitHub上几乎所有仓库都有一个默认分支，一般是main，代表稳定可用的版本。你想加一个新功能，不直接在main上改，而是从main拉一个新分支比如feature/login，在这个分支里随便折腾。做完、测试通过，再把feature/login合并（merge）回main。
合并的常用写法是：
bash复制git checkout main
git pull
git merge feature/login
如果两个分支改了同一个文件的同一位置，Git就会报冲突。解决冲突不是靠背命令，而是打开冲突文件，找到类似<<<<<<< HEAD、=======、>>>>>>> feature/login的标记，看清楚两边的代码，按自己的意图保留一份，然后重新add和commit。
分支策略对新手要记住的核心就一条：永远别直接在main分支上瞎改。即使你只是自己一个人玩，这句话也能帮你省掉不少麻烦。我在实际的个人项目里也基本遵循“让main永远保持在可运行状态”的原则，开发都在分支上进行，有时候懒了直接在main上改，翻车概率立刻上升，这几乎成了某种玄学。
7. 常见问题与避坑实录
7.1 GitHub页面打不开或加载慢
GitHub是境外服务，偶尔会遇到页面加载不出来或者图片不显示的情况。新手最容易慌，第一反应就是怀疑自己电脑坏了或者不会用。绝大多数时候问题出在网络链路上。
能做的有几步。第一步，先访问GitHub的官方状态页，看看GitHub本身有没有服务异常，如果有故障就是人家的锅，等一等就好。第二步，检查自己本地网络是不是正常的，换个网络试试，比如手机开热点。第三步，清一下DNS缓存，Windows上是ipconfig /flushdns，macOS上是sudo dscacheutil -flushcache。第四步，GitHub的网页端访问不稳不代表Git功能不能用，你依然可以用git clone、git push走SSH协议操作仓库，很多情况下代码推拉是正常的，只是网页加载慢。
关于下载慢这个问题，如果你的项目只是代码查看需求，我刚才说的浅克隆git clone --depth 1非常管用，它不拉历史记录，速度会明显快很多。另外，尽量用SSH地址而不是HTTPS，SSH协议在弱网环境下反而比HTTPS稳定一些。这些都是纯技术层面的优化手段，安全而且有效。
7.2 Windows提示“git无法识别为cmdlet、函数、脚本文件”
这个报错几乎每个Windows新手都会遇到。报错原文是：git : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。出现这个问题的原因很简单：系统找不到git.exe在哪个路径。
排查步骤按顺序来。第一步，你先确认自己到底有没有装Git，安装过的话在开始菜单里找Git Bash，如果能打开，Git就是装了的。第二步，关掉当前的终端窗口，重新开一个新的，再试试git --version。有时候就是终端没刷新环境变量，重开就解决了。第三步，打开系统环境变量设置，在Path里加上Git的安装路径，默认是C:\Program Files\Git\cmd，加完以后重新打开终端。
如果Git Bash打得开但PowerShell里用不了git，绝大多数就是Path配置的问题。把这个配置好了，命令行层面的问题基本就解决了。
7.3 登录失败或Token失效
如果你用HTTPS方式推送代码，GitHub会要求输入用户名和密码，但这里的密码早就不是账号密码了，而是个人访问令牌（Personal Access Token）。现在输入账号密码会直接提示Authentication failed。需要去GitHub的Settings → Developer settings → Personal access tokens生成一个Token，生成时勾选repo权限，然后把Token当密码粘贴进去。
另外，如果你在公司用第三方Git平台（比如GitLab），遇到报错login failed. check api token or gitlab version，这种一般是API Token失效了或者GitLab服务版本不匹配，去平台重新生成Token，再看服务端版本和本地工具是否兼容。这类报错不属于GitHub问题，但很多人会混在一起，我在这里给你一个排查方向。
7.4 IDE里那一长串带参数的命令是什么
很多人在VS Code或者JetBrains系列IDE里提交代码时，会把鼠标悬停在GUI操作上，看到一长串git命令，类似：
bash复制git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks status -z -u
第一次看到这串命令别慌，这是IDE在调用底层的Git命令，附带了一些额外参数，比如让中文文件名不要转义成乱码、让文件比较更准确、关闭Git的可选锁机制提升性能。这些参数对Git本身的操作没有实质影响，你不用手动去输入它们，知道这是IDE帮你在后台执行的就可以。如果哪天你在日志里看到类似的命令，说明你的IDE正在正常工作，而不是出了什么毛病。
7.5 警惕.git目录泄露：部署时别把源码交出去
这个坑在初学者接第一个正经部署任务时特别容易踩。如果你把项目打包传到服务器上的时候，不小心把.git这个隐藏目录也一并传上去了，而这个服务器又开着公网访问，别人就可以通过访问网站的/.git/路径，尝试读取Git对象文件，把整套源码的历史版本都还原出来。这属于源码泄露事故，轻则代码白送，重则配置文件里的密钥全部暴露。
正确的做法有这几条。第一，部署时把关卡设在源头，打包时排除.git目录，比如你用.gitignore或者打包工具配置把.git排除掉。第二，在服务器层面做拦截，Nginx或者Apache里配置规则，把所有以/.git开头的访问请求直接返回403。第三，定期自查，部署后自己先访问一下https://你的域名/.git/config，如果能看输出内容，说明泄露了，立刻处理。
8. 一些老生常谈但真的有用的经验
按我自己的体会，学GitHub最忌讳的就是把教程当电视剧看，看完了感觉都会了，一上手就卡壳。最快的方式永远是带着一个真实目标去用，比如“我要把自己整理的课程笔记传到GitHub上”，或者“我要给某个开源项目修一个文档错别字”。有了目标，安装、配置、克隆、提交这些动作都会变得特别自然，遇到问题也不会慌。
再分享一个小技巧：遇到任何git报错，不要试图用中文翻译硬猜，直接把英文报错原文复制到搜索引擎里搜，十有八九能在Stack Overflow或者GitHub Discussions里找到前人踩过同一个坑的解答。我到现在遇到冷门的git问题也是这么干的，比翻文档快得多。
还有一个小提醒：GitHub账号最好开启二步验证，因为你的仓库会沉淀很多个人代码和记录，安全等级拉高一点，总归没有坏处。希望这篇教程能帮你迈过第一道坎，剩下的路，跑起来自然就顺了。