如果你正准备认真学一遍Git和GitHub或者已经被各种报错折腾到怀疑人生那么这篇笔记应该能帮上忙。它不是那种照着文档念一遍的翻译稿而是我把自己从“git push失败就慌”到“日常操作基本不用查命令”这段过程里踩过的坑、验证过的做法、觉得值得记住的点全部整理成了一份可以跟着操作的学习笔记。内容覆盖从安装、配置、常用命令到连接GitHub、解决各类疑难问题适合零基础入门也适合学过但总卡壳的朋友查漏补缺。1. 版本控制到底解决什么问题1.1 从“最终版”说起为什么要用Git在接触Git之前很多人管理文件的方式就是不断复制文件夹起名从“论文初稿”到“论文最终版”再到“论文真的最终版”“论文死也不改了版”。这套办法对付Word文档勉强能忍但放到代码项目里就是灾难十几个文件相互依赖哪里改出了问题你根本不知道是哪次改动引入的更别说多人协作时大家各自改同一份文件最后手工合并能让人崩溃。Git解决的是三个最核心的痛点第一是历史记录每一次提交都是一次快照你可以随时回看项目任意时刻的状态第二是分支能力你可以在一条独立的时间线上开发新功能不影响主线的稳定第三是协作机制多人同时开发时每个人在本地有自己的完整仓库通过推送和拉取来交换变更而不是直接覆盖别人的文件。这些能力说起来简单但真正理解之后你会发现自己写代码的方式都会改变——因为有了随时回退的安全网你更敢于大胆重构、尝试新方案。这也是我建议每个开发者都把Git当作基本功的原因它不是“后端才需要学的工具”而是所有写代码的人都应该掌握的基础设施。1.2 Git和GitHub是什么关系很多初学者会把Git和GitHub当成同一个东西其实它们是两层。Git是一个运行在本地电脑上的版本控制软件完全免费、开源它负责记录文件变更、管理分支、合并代码所有操作都在你的机器上完成不需要联网也能用。GitHub则是一个基于Git的在线代码托管平台你可以把本地仓库推送到GitHub上实现备份、分享、多人协作它解决的是“如何让分散在不同地方的开发者共同维护一个项目”的问题。类比一下Git就像你手机里的相机负责拍照GitHub就像一个云端相册负责把照片存起来并分享给别人。没有相机你拍不了照没有云端相册你也可以自己存着但有了云端相册分享和协作会方便太多。除了GitHub类似的托管平台还有GitLab、Gitee码云等用法大同小异学会GitHub之后再切到其他平台基本无障碍。1.3 学习前的核心概念工作区、暂存区、版本库理解了为什么要用版本控制接下来要建立三个基础概念否则后面看命令都会觉得莫名其妙工作区、暂存区、版本库。工作区Working Directory就是你在电脑里能看到的项目文件夹里面是你正在编辑的实际文件。暂存区Staging Area / Index可以理解成一个临时存放区你通过git add把工作区的改动放进去告诉Git“这些内容我准备记录了”。版本库Repository / .git目录Git真正保存历史记录的地方通过git commit把暂存区的内容固化成一次历史版本。为什么中间要多一个“暂存区”的环节而不是直接提交因为实际开发中你常常会在同一次工作里修改好几个文件但并不是所有改动都应该归入同一条提交记录。比如你修了一个bug又顺手格式化了一下代码这两件事混在一次提交里以后回溯时很难说清楚。有了暂存区你可以先git addbug相关的文件提交一次再git add格式化相关的内容提交第二次让每一条提交记录都保持纯粹、可追溯。2. 从零开始安装与配置Git2.1 不同操作系统的安装方式Windows用户最简单的方式是去Git官网下载安装包下载下来一路Next基本就能装好。安装过程中有几个选项需要留意第一个是“Adjusting your PATH environment”建议选择“Git from the command line and also from 3rd-party software”这样Git命令能直接在CMD和PowerShell里使用不用每次去翻Git Bash。第二个是换行符转换方式默认选项“Checkout Windows-style, commit Unix-style line endings”就行它的作用是防止团队里跨系统协作时出现文件换行符混乱的问题。macOS用户如果装了Homebrew一行命令搞定brew install git。没装Homebrew也可以直接下载安装包或者用Xcode自带的Git不过版本通常偏老建议还是单独装。Linux用户根据发行版不同选择包管理器Ubuntu/Debian用sudo apt install gitCentOS/RHEL用sudo yum install git或sudo dnf install git。安装完成后在终端里输入git --version如果能看到版本号说明安装成功。我见过不少人卡在这一步其实绝大部分都是环境变量没配置好安装时选了推荐选项之后基本不会出问题。2.2 安装后的第一件事配置用户信息Git安装好之后第一件必须要做的事是配置用户名和邮箱因为每一次提交都会记录这两个信息别人在GitHub上看到你的提交会通过邮箱关联到你的账号。配置方法git config --global user.name 你的名字 git config --global user.email 你的邮箱--global表示全局配置对当前用户所有仓库生效。如果某个特定项目要用不同的身份可以在项目目录下去掉--global重新执行一次这样项目级配置会覆盖全局配置。这里有个细节容易被忽视GitHub的提交贡献图那面绿色小格子墙统计依据是提交时用的邮箱是否与GitHub账号绑定。有人提交代码时邮箱没配对代码推上去了但头像和贡献统计都不显示看起来就像“不是本人提交”。所以建议直接把邮箱配置成GitHub绑定的那个邮箱或者干脆在GitHub设置里开启“Keep my email address private”然后把生成的匿名邮箱拿来配置Git。2.3 让命令行更好用别名与常用配置说实话Git的默认命令不算难记但高频操作可以配置成别名能显著提升操作效率。比如我最常用的几个git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.cm commit git config --global alias.lg log --oneline --graph --all --decorate配置之后git st等于git statusgit lg直接以图形化方式展示提交历史非常直观。有人会问这样会不会太花哨我的感受是别名只是输入层面的简化底层执行的还是原生命令完全不影响理解和排障新手也可以放心用。另外还有几个实用配置。一个是默认分支名Git较新版本默认分支是main如果你还在用旧习惯区分主分支可以指定git config --global init.defaultBranch main另一个是大小写敏感问题。Windows和macOS默认文件系统不区分大小写但Linux区分Git在追踪文件时可能会漏掉“文件名大小写改变”这种改动。建议执行git config --global core.ignorecase false让Git把大小写变化纳入监控避免后续部署到Linux服务器时出现诡异问题。2.4 配置SSH密钥连接GitHub的钥匙本地Git配好之后还要解决“怎么让GitHub认识你”的问题。HTTPS方式每次推送都要输入用户名密码现在要求Token后面会细说SSH方式配置一次之后就不需要反复输入了而且更安全。生成SSH密钥的方法ssh-keygen -t ed25519 -C 你的邮箱一路回车会在~/.ssh目录下生成一对密钥文件私钥默认文件名id_ed25519留在本地公钥id_ed25519.pub需要添加到GitHub账号上。查看公钥内容cat ~/.ssh/id_ed25519.pub复制输出内容登录GitHub点头像进入Settings找到“SSH and GPG keys”点击“New SSH key”粘贴保存。之后在本地测试ssh -T gitgithub.com如果看到Hi后面跟着你的GitHub用户名说明密钥配置成功以后所有走SSH协议的Git操作都可以免密进行。这个步骤属于“配一次受益很久”的类型强烈建议别跳过。3. 核心命令与日常操作3.1 本地仓库的初始化与首次提交进入一个项目目录执行git init这个目录就变成了Git仓库。此操作会创建一个隐藏的.git文件夹里面保存着Git需要的全部元数据和历史记录。需要注意的是.git文件夹不要手动去改里面的文件除非你明确知道自己在做什么否则很容易弄坏仓库。初始化之后查看文件状态git status它会告诉你哪些文件是未跟踪的Untracked、哪些文件被修改过、哪些改动已经放进暂存区。新手最容易懵的就是看到一堆??标记和红色文件名这只是表示Git发现了新文件还没开始追踪。接下来执行git add . # 把所有改动加入暂存区 git commit -m feat: 初始化项目git add .会把当前目录里所有改动都放进来但如果你想只提交部分文件就改成git add 文件名或git add src/这样的精确路径。提交信息建议简洁又明确团队协作时可以用一些约定式规范比如feat:表示新功能、fix:表示修bug、docs:表示文档变更这样看历史日志时一目了然。3.2 分支Git最强大的武器分支是Git区别于老式版本控制系统的核心能力。你可以把它理解成平行宇宙主线上的代码稳定运行你在另一条分支上大胆实验新功能搞砸了直接删除分支不影响主线搞成了再合并回来。常用命令git branch feature-login # 创建分支 git checkout feature-login # 切换到该分支 # 或者一条命令完成创建切换 git checkout -b feature-loginGit 2.23版本之后官方推荐用git switch来切换分支git switch -c feature-login等于创建并切换语义更清晰但git checkout在老教程里到处可见两种用法都建议认识。分支合并用git merge。假设你要把 feature-login 合并回主分支先切换到主分支然后执行git merge feature-login。如果两个分支改动的文件互不重叠Git能自动合并如果改了同一个文件的同一段代码就会产生冲突Conflict这时候Git会在文件里用、、标记冲突区域需要手动决定保留哪边再提交一次完成合并。遇到合并冲突不用紧张这属于日常操作。我的经验是冲突越频繁越说明分支切得不够碎功能分支应该尽量短命小步快跑而不是攒一个巨大分支最后一次性合并那样一次冲突能让你改到怀疑人生。3.3 查看历史与回退git log是查看提交历史的命令默认输出一条条提交记录包含提交哈希、作者、日期和提交信息。加上--oneline可以只看一行摘要配合--graph能直观看到分支合并的拓扑图。如果你想回退到某个历史版本有两种常见方式git reset和git revert。两者区别很关键git reset是“移动指针”把当前分支的HEAD指针挪到历史某次提交相当于“抹掉”后面的提交记录。它有--soft、--mixed、--hard三个级别--hard会把工作区文件也恢复到历史状态危险系数最大命令一旦执行未提交的改动直接丢失。git revert则是“反做”它会新建一次提交把某次历史提交的改动反向执行相当于“撤销这个改动但保留历史记录”。团队协作中如果代码已经推送到了远程仓库不要用git reset去“修改历史”因为别人可能已经拉取过这些提交强行改写历史会造成一堆同步问题。正确做法是用git revert生成一个新提交来撤销问题代码这样历史是线性的、可追溯的。3.4 几个容易被忽略但好用的命令这部分是真正的彩蛋都是实战里发现很香但普通教程很少重点强调的命令。第一个是git commit --amend它的作用是修改最近一次提交。场景很常见提交完之后发现少加了一个文件或者提交信息写错了。直接再提交一次显得历史很碎用--amend就能把新的改动合并进上一次提交历史保持干净。常见用法git add 刚才忘了的文件 git commit --amend # 保留原提交信息 git commit --amend -m 新的提交信息 # 顺便改信息注意一点--amend本质上也是在改写历史同样适用于“没推送”的场景。如果已经推送了想更新远程提交就要用git push --force-with-lease强制推送但这个操作会覆盖远端历史务必谨慎别在共享分支上乱用。第二个是git worktree这个命令可以让同一个仓库同时检出多个分支到不同的文件夹。场景很典型你正在 develop 分支上写着功能突然线上bug要马上修但手头代码又不想提交或暂存这时你可以用git worktree add ../hotfix-folder main把主分支检出一个独立目录在那个目录里修bug、提交、推送修完再回到原来的目录继续写功能完全不打断思路。第三个是git rm --cached它做的事情是“停止追踪某个文件但保留本地文件”。比如你误把.env提交到了仓库想让它不再被Git管理但又不删本地文件就可以用git rm --cached .env然后把这个文件加入.gitignore再提交之后Git就不会再追踪它。4. 连接GitHub从本地到远程4.1 创建远程仓库与关联在GitHub上点击New repository创建一个新仓库起好名字之后GitHub会给出几种连接方式的示例命令。以SSH方式为例远程地址长这样gitgithub.com:用户名/仓库名.git本地已有仓库的情况下关联远程仓库git remote add origin gitgithub.com:用户名/仓库名.git git branch -M main git push -u origin main这里解释几个名词origin是远程仓库的默认别名你可以改成别的名字但origin已经是全世界Git用户的通用约定建议遵守。-u origin main中的-u是--set-upstream的简写表示把本地main分支和远程main分支关联起来之后直接执行git push或git pull就不用再带参数了。如果是GitHub上已存在的仓库想把它拉到自己电脑上用克隆命令git clone gitgithub.com:用户名/仓库名.git克隆不需要先git init它会自动把远程仓库完整复制到本地包括历史记录和所有分支。4.2 推送与拉取push、pull、fetch日常开发最常用的两款远程操作是git push和git pull。push是把本地提交推送到远程pull是把远程新提交拉取到本地并自动合并。还有一个git fetch它只把远程的提交记录拉到本地但不自动合并先让你看看改了什么东西再决定怎么处理。一个常见的困惑是“pull和fetch到底用哪个”。我的建议是如果你确定本地没有未提交的改动、也没有还没合并的冲突风险直接用pull省事如果不确定远程改了什么或者你正在一个比较复杂的分支上先fetch再检查一下区别再merge心里更有底。推送时偶尔会遇到“Non-fast-forward”报错意思是本地历史和远程历史出现了分叉远程有本地没有的提交。这通常是因为你在本地做了一些改写历史的操作或者别人已经推送了新提交。解决办法很简单先git pull把远端提交拉下来合并再推送。如果确定要用本地覆盖远端可以用git push --force-with-lease但请先确认这不是共享分支。4.3 认证方式从密码到Token、SSH以前GitHub支持用账号密码进行HTTPS推送但后来出于安全考虑GitHub已经不再接受密码认证而是要求使用Token个人访问令牌或者SSH密钥。当你用HTTPS地址推送时弹出的是账号输入框密码那一栏要填入的是Token而不是你登录GitHub的密码。生成Token的方法GitHub头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token。生成时勾选repo权限即可满足大多数推送拉取需求。Token只显示一次一定要复制保存好丢了就只能重新生成。我个人的习惯是优先用SSH方式因为它配置一次后就再也不需要处理Token过期和重新输入的问题。如果你只偶尔用一下GitHubToken方式更轻量看你的使用频率决定即可。4.4 用GitHub托管网站以Hexo部署为例GitHub Pages是GitHub提供的一项免费静态网站托管服务很多个人博客都用它来部署。以Hexo博客为例部署流程通常是本地写好文章、生成静态页面然后把静态文件推送到一个特殊的分支GitHub Pages自动发布成网站。Hexo部署有专门的插件hexo-deployer-git在站点配置文件_config.yml里设置deploy: type: git repo: gitgithub.com:用户名/用户名.github.io.git branch: main之后执行hexo d插件会帮你自动执行构建和推送。第一次配置时容易踩的坑是仓库名必须叫用户名.github.io才能开启Pages服务另一个是分支名需要和Pages设置里选择的分支一致。4.5 参与开源项目Fork与Pull RequestGitHub作为协作平台的另一个经典场景是参与别人的开源项目。整个流程是Fork把别人的仓库复制一份到你账号下→ Clone到本地 → 新建分支改代码 → Push到你的GitHub仓库 → 在原始仓库页面发起Pull RequestPR请求项目维护者把你的改动合并进去。我第一次提PR时最搞不清的是“怎么让我的提交对应到上游的最新代码”。通用做法是先把上游仓库添加为一个远程源git remote add upstream gitgithub.com:原作者/仓库名.git git fetch upstream git checkout main git merge upstream/main这样能保证你的修改基于上游最新代码减少合并冲突的概率。提交PR前最好再检查一下提交信息是否清晰、是否只包含有意义的改动毕竟维护者是在花自己的时间Review陌生人的代码清晰、小而美的PR更容易被接受。5. 真实场景用Git提交代码的完整工作流5.1 从零搭建一个个人项目仓库把所有知识点串起来用一个完整场景演示一遍现在你要为一个新项目初始化仓库并首次推送到GitHub。第一步创建项目目录并初始化mkdir my-project cd my-project git init第二步创建项目文件比如README.md写上一句项目介绍。然后用git status查看状态再添加并提交git add README.md git commit -m docs: 添加项目说明第三步去GitHub新建仓库把本地推到远程git remote add origin gitgithub.com:用户名/my-project.git git branch -M main git push -u origin main整个过程走下来你会发现常用命令其实就这几个init、add、commit、remote、branch、push。很多教程会把命令铺得很开但实际高频使用的就这六七个把这些练熟再遇到高级命令也能举一反三。5.2 在IDEA中使用Git以IDEA为例命令行虽然通用但有些场景下图形界面效率更高比如肉眼查看文件差异、处理复杂的合并冲突。以IntelliJ IDEA为例它内置了完整的Git客户端。在IDEA里提交代码主流操作是修改文件后文件列表会自动变成蓝色未提交状态右键选择“Commit”在提交面板里勾选要提交的文件填写提交信息点击Commit。推送则点击右上角的绿色箭头Push。IDEA的Git菜单里集成了分支管理、日志查看、Stash暂存改动等能力新版还提供了交互式Rebase的可视化界面。用IDEA的好处是它把所有Git操作都映射成了图形按钮新手不容易敲错命令。但我依然建议你先在命令行里把逻辑学懂这样就算换任何IDE、任何平台都不会觉得陌生。5.3 小乌龟TortoiseGit适合谁TortoiseGit俗称小乌龟是Windows平台上老牌的Git图形客户端它的特点是集成在系统右键菜单里不用打开IDE在文件夹里就能完成提交、更新、切换分支等操作。对于不习惯命令行的Windows用户或者经常需要在资源管理器里快速处理文件的朋友小乌龟确实方便。不过它的界面风格偏老学习资料也不如GitHub官方工具丰富。如果你是刚入门我更推荐先用命令行或者IDEA内置的图形界面把Git的工作原理吃透。等彻底理解了工作区、暂存区、分支这些概念再回头去用小乌龟反而会觉得它很顺手。工具永远是辅助核心还是理解模型。6. 常见问题与排查技巧实录6.1 GitHub访问与下载问题很多人反馈“GitHub打不开”或者打开很慢这主要是因为GitHub的服务器和CDN节点都在境外不同网络环境下访问质量差异很大。首先明确一点你可能不需要任何特殊手段先试试更换网络环境比如从WiFi切到手机热点、更换浏览器或开启无痕模式、刷新DNS缓存Windows执行ipconfig /flushdns很多时候只是临时性的网络波动。也可以试试通过ping github.com或访问GitHub的Status页面了解是否是服务端问题。其次下载仓库时如果很慢常见原因是仓库里包含较大的二进制文件比如图片、打包文件。建议用git clone --depth 1进行浅克隆只拉取最新一次提交体积会小很多git clone --depth 1 gitgithub.com:用户名/仓库名.git如果只是需要下载某个仓库的源码而不是参与开发直接在GitHub网页下载ZIP包也是一种选择。第三市面上的第三方“加速”工具鱼龙混杂很多会要求你安装不明软件、配置代理安全隐患极大。我不建议为了下载代码去安装来路不明的软件更稳妥的做法是通过官方渠道、合理时间段错峰访问或者使用一些有正规背景、公开透明的镜像站点来获取开源软件包注意仅限下载官方发布的公开资源不要登录、不要提交代码。对于需要持续协作的开发项目最快的路径往往是配置好SSH密钥后直接用命令行git操作网页访问慢并不影响git本身的稳定性。6.2 page not found与仓库404GitHub上出现404错误也就是“Page not found”常见原因有几种。第一种是仓库是私有的你没有访问权限这种情况下页面会故意显示成404而不是“无权限”防止泄露仓库是否存在。第二种是仓库地址拼写错误注意GitHub的仓库名和用户名是大小写敏感的路径要完整匹配。第三种是分支名不对比如你访问仓库名/tree/main但默认分支其实是master也会看到404。第四种是你登录了错误的账号或者根本没登录偶尔也会触发权限页面的404。排查顺序建议是先用无痕窗口打开仓库主页面确认登录状态再检查URL是否拼写准确最后确认自己的账号是否有该仓库的访问权限。如果把这些问题都排除了还是404那大概率就是仓库不存在或被删除了没什么好纠结的。6.3 登录失败login failed与Token问题Git客户端连接远程仓库时报类似“login failed. check api token or gitlab version. log in via git if the version...”的错误这类信息里通常会提到api token。它的核心含义就是认证没通过GitHub不接受单纯的密码要求使用Token而Token可能过期、被撤销或者格式不对。解决办法是重新生成一个Token参考4.3节然后重新配置凭据。在Windows上凭据管理器可能缓存了旧密码即使你生成了新Token推送时它依然用缓存的旧凭据结果一直报认证失败。打开“控制面板 → 凭据管理器 → Windows凭据”找到git:https://github.com这一项删掉或编辑下次推送时重新输入新Token即可。另外注意不同平台GitHub、GitLab、Gitee的Token机制不完全一样GitLab报错时还涉及版本兼容问题但排查思路都是确认平台要求的认证类型、确认凭据是否是最新的、检查缓存凭据是否需要清理。6.4 git目录泄露与安全防护“git目录泄露”是指一个本应被保护的Web站点把.git文件夹暴露在了公网访问路径下。攻击者可以通过.git文件夹还原出源码、数据库配置、密钥等信息这是一个非常严重的安全隐患。如果你发现某个目录被意外当作静态站点部署了第一件事就是检查Web服务器的根目录是否包含了.git文件夹同时确认部署过程没有把整个开发目录原样拷贝上去。防御层面最稳妥的方式是部署时明确排除.git目录或者在Web服务器配置里直接禁止以.git开头的路径访问。从GitHub操作的角度还要注意不要把敏感信息提交进仓库。比如.env文件、数据库密码、云服务密钥一旦推到远程仓库即使之后删掉它们仍然留在提交历史里。如果已经发生这种情况最简单有效的方式是吊销泄露的密钥、在GitHub上开启Secret scanning、重写历史或者直接废弃仓库把影响降到最低。预防永远是第一位的在项目根目录创建.gitignore把敏感文件提前排除掉。6.5 其他高频报错速查报错信息含义解决办法fatal: not a git repository当前目录不是Git仓库确认是否执行过git init或处于正确的仓库子目录failed to push some refs推送被拒绝通常是远程有本地没有的提交先git pull再推fatal: remote origin already exists远程别名已存在用git remote remove origin删除旧的再添加Please tell me who you are没配置用户名和邮箱执行git config --global user.name和user.emailwarning: LF will be replaced by CRLF换行符差异警告保持默认换行符配置一般不影响实际使用中文文件名显示为转义字符core.quotepath默认开启执行git config --global core.quotepath false最后再分享一个冷门但很实用的小知识。如果你看到IDE或某些Git客户端生成的命令里带了-c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks它们的意思分别是不把diff输出里的a/、b/前缀替换成更具语义的前缀允许中文路径正常显示以及避免Git在执行命令期间对仓库加不必要的锁。这些都是客户端出于兼容性自动加的参数手动跑Git时不需要特意带上但知道它们存在遇到相关配置就不会一头雾水。学Git的过程和学任何工具都一样别指望一次把所有命令背下来。我的经验是先掌握add、commit、push、pull、branch这五六个最常用的把日常流程跑通然后在真实项目里遇到问题再针对性搜索解决。分支、rebase、worktree这些高级功能等你确实有需要时再去学效率会远高于一开始就啃完整文档。希望这份笔记能帮你少走一些弯路在实际使用中把Git真正变成得心应手的工具。