很多新手在学 Git 和 GitHub 的时候最容易犯的错误是直接背命令。背完add、commit、push之后一旦遇到报错或者分支冲突立刻不知道从哪里查起。Git 是当前最流行的分布式版本控制系统GitHub 是基于 Git 的远程代码托管平台。这两个词组合在一起解决的核心问题其实很简单一是把本地代码的历史记录管好二是把代码安全地同步到远程方便备份和多人协作。这篇文章我会按实际带新人的顺序来讲先把两个概念拆清楚再做安装和配置然后从本地第一次提交开始一路走到分支合并、远程推送和 Pull Request。整个过程是零基础可跟做的命令会给完整写法结果会说明怎么判断对错遇到常见报错也有对应的排查顺序。1. 先搞懂 Git 和 GitHub 各管哪一段1.1 本地代码是怎么慢慢乱起来的很多人第一次意识到“需要版本管理”是因为这样几个场景写代码写到一半改坏了想退回昨天的版本但昨天的代码没存。同一个项目存了一堆文件夹叫项目备份、项目最终版、项目最终版2到最后根本分不清哪个是最新的。和同学或同事改同一个文件你改完覆盖了对方的内容对方原地崩溃。想知道某段代码是什么时候加的、谁加的、为什么要加但本地文件根本没有任何记录。Git 解决的就是这些问题。它会在你本地记录每一次修改像存档一样留下历史节点。每个节点叫什么、谁提交的、改了什么都能查得到。更重要的是你可以随时退回任意一个历史版本而不用手动复制一堆备份文件夹。1.2 GitHub 解决的是“远程”这件事Git 本身是本地工具哪怕电脑不联网也能用 Git 管理代码。但本地版本管理有一个天然限制电脑坏了怎么办换电脑怎么办和别人协作怎么办GitHub 就是架在 Git 之上的远程代码托管平台。你把本地仓库推送到 GitHub代码就多了一份云端备份。别人也可以把代码拉到本地参与修改再把自己的改动推送回去。加上 Pull Request、Issues、代码审查这些功能GitHub 就成了一个完整的协作平台。可以这样理解Git 管“本地版本历史”。GitHub 管“远程代码托管和协作流程”。没有 GitGitHub 会非常难用。没有 GitHubGit 只能解决你一个人的问题。1.3 新手最容易误解的三个点第一Git 不是网盘。网盘同步的是文件内容Git 同步的是“提交历史”。Git 里最小的一次操作是提交也就是commit而不是“保存文件”。第二不是把文件拖到 GitHub 网页上就算会用 Git。网页上传适合单个小文件真正开发中代码要经过本地仓库、暂存区、提交、推送这一整套流程。重点不在网页操作而在本地命令。第三Git 和 GitHub 不是同一个东西。很多报错说“GitHub 推不上去”其实问题出在本地仓库的配置、分支状态或者远程地址而不是 GitHub 网站本身。排查时要先分清是哪一端出了问题。2. 安装 Git 并完成初始化配置2.1 Windows 安装 Git 的完整过程Windows 上安装 Git最简单的方式是去 Git 官网下载 Windows 安装包然后一路点“Next”。安装过程中有几个选项值得留意虽然大部分保持默认就行选择安装路径时不要用带空格的目录避免后续命令解析出问题。“Select Components”页面默认勾选就可以了。如果愿意用命令行可以把 “Git Bash Here”和“Git GUI Here”都勾上右键菜单里会多出快捷入口。“Adjusting your PATH environment”页面推荐选第二项 “Git from the command line and also from 3rd-party software”这样 Git 的命令可以在 CMD 和 PowerShell 里直接用。“Choosing the default editor”页面新手可以保持默认的 Vim。如果你不熟悉 Vim建议改成 Notepad 或 VS Code否则后面写提交信息时会卡在 Vim 里不知道怎么退出。换行符转换那里一般保持默认的 “Checkout Windows-style, commit Unix-style line endings” 即可。Windows 和 Linux 混用项目时会有换行符问题但这个默认选项已经能覆盖大多数场景。安装完成后打开一个新的 CMD 或 PowerShell 窗口输入git --version如果能输出类似git version 2.40.0这样的内容说明安装成功。2.2 macOS 和 Linux 的安装方式macOS 上最简单的方式是先用 Xcode Command Line Tools它会自带 Git。在终端里执行git --version如果提示没有 Git系统会弹出安装提示。也可以用 Homebrew 安装brew install gitHomebrew 装完的 Git 版本通常比较新后续使用更省心。Linux 上用系统包管理器安装即可。Ubuntu、Debian 系执行sudo apt update sudo apt install gitCentOS、Fedora、RHEL 系执行sudo yum install git安装完成后同样用git --version验证。如果版本太老可以先确认一下系统源里的版本再决定是否从源码编译。多数情况下系统源里的版本足够新手使用。2.3 安装完成之后怎么验证git --version只是第一步。建议继续确认三个东西第一当前终端是不是已经识别 Git。如果刚装完就报“不是内部或外部命令”多半是新开终端或者需要重启。Windows 上新开的窗口才会重新加载 PATH。第二Git 的默认配置是否为空。执行git config --global --list如果之前没有配置过可能什么都不输出或者只输出很少几行。第三能不能正常执行git help或者git status。在任意目录执行git status如果提示fatal: not a git repository这反而是正常的说明 Git 已经能运行只是当前目录还没有初始化仓库。2.4 第一次使用前必须配置的用户名和邮箱Git 每次提交都会把提交者的名字和邮箱写进提交记录。这个信息不是登录验证用的而是区分“这段代码是谁提交的”。所以第一次使用前一定要先配置git config --global user.name Your Name git config --global user.email youexample.com这里的--global表示全局配置换一台电脑之后同样要做一次。名字建议用英文或拼音邮箱建议用你 GitHub 注册用的邮箱这样提交记录能和 GitHub 账号关联起来。验证配置git config --global --list输出里应该能看到刚才设置的user.name和user.email。如果提交时看到Please tell me who you are就是这两项没配好或者配错了回到这一步检查。注意配置用户名和邮箱时不要用sudo也不要把配置写在某个仓库内部。全局配置对所有仓库生效局部配置只对当前仓库生效。新手先分清全局和局部后面踩坑会少很多。3. 第一次提交记住这五个命令就够了3.1 初始化仓库和查看状态先建一个测试目录并初始化 Git 仓库mkdir git-demo cd git-demo git initgit init会在当前目录下生成一个隐藏的.git文件夹。这个文件夹里保存着 Git 的全部版本记录不要自己去改里面的文件。创建一个测试文件echo # Git Demo README.md然后查看仓库状态git status在第一次提交之前git status会告诉你当前有哪些文件是“未跟踪”的也就是 Git 还没有纳入版本管理的文件。新手要养成先看git status再操作的习惯它能避免很多误操作。3.2 add、commit、log 的执行顺序Git 提交分两步先把改动放进“暂存区”再把暂存区的内容提交成一条历史记录。git add README.md git commit -m docs: 添加 README 文件git add指定要纳入提交的文件git commit -m提交并附带提交信息。提交信息要写清楚这次改了什么方便以后回看历史时快速定位。如果想一次添加所有改动可以用git add .但我不建议新手一开始就无脑git add .。因为仓库里可能有不该提交的临时文件、日志文件或者大文件。先git status看一遍再git add具体文件更稳妥。提交完成后查看历史git log --oneline输出会显示一串提交哈希值和提交信息比如a1b2c3d docs: 添加 README 文件如果你的默认分支名是master而之后想改成main可以执行git branch -M main这条命令会把当前分支重命名。很多人在这步容易困惑明明提交成功了为什么显示的是master其实分支名只是默认值不影响使用。但为了和 GitHub 默认仓库保持一致建议统一改成main。3.3 提交之后反悔了怎么办提交错了不代表要推倒重来。新手按这三层来处理。第一还没提交但改了文件想放弃改动。用git restore 文件名这会丢弃工作区里未提交的修改恢复到最近一次提交的状态。第二已经git add进了暂存区想撤出暂存区但保留文件改动。用git restore --staged 文件名第三已经提交了但提交信息写错了或者这个提交里漏了一个文件。如果这个提交还没推送到远程可以用git commit --amend--amend会把最新的改动合并到上一次提交里也能修改上一次提交的信息。如果提交已经推送到远程就不要用--amend或reset去改写历史了因为远程历史一旦被改写协作的人会同步出问题。这种情况更安全的处理是用git revert。revert会新增一条反向提交把某个历史提交的改动撤销掉。新手记住一句话本地提交可以改写远程提交尽量只做新增。注意git reset也经常出现在各种教程里但我建议新手在真正理解 HEAD、暂存区、工作区之前少用reset --hard。这个命令会把未提交的改动一起丢掉恢复起来很麻烦。3.4 .gitignore别把不该提交的文件推上去很多人第一次把项目推到 GitHub发现一堆node_modules、.env、__pycache__也进去了。这就是没有.gitignore的结果。在项目根目录创建一个.gitignore文件里面写不需要跟踪的内容node_modules/ __pycache__/ .env .DS_Store dist/.gitignore的规则不难理解每一行写一个需要忽略的目录或文件/结尾表示目录。注意.gitignore只能忽略还没有被 Git 跟踪的文件。如果某个文件已经被git add过再写到.gitignore里也不会自动生效需要先用git rm --cached 文件名取消跟踪。4. 分支是 Git 的核心也是新手的分水岭4.1 没有分支时多人改代码会变成灾难假设你和同事同时改同一个项目主线代码只有一条。你改到一半同事的改动也提交了这时候谁先合并谁就可能覆盖对方的问题。更麻烦的是一个功能还没做完代码已经混进主线别人拉下来直接报错。分支相当于给代码开了个平行空间。你可以在主分支上不动开一个功能分支在功能分支里随便改、随便提交。功能做完、测试通过之后再合并回主分支。主线始终保持稳定所有人都在自己的分支上工作互不干扰。4.2 创建、切换、合并分支的完整过程先看看当前有哪些分支git branch新建一个分支并切换过去git switch -c feature/hello如果用的是旧版 Git可能不支持switch这时可以用git checkout -b feature/hello两种写法作用一样新手用switch更直观因为checkout身兼数职容易搞混。在功能分支里新建文件并提交echo Hello hello.txt git add hello.txt git commit -m feat: 添加 hello 文件然后回到主分支git switch main查看提交历史对比git log --oneline --graph --all如果功能分支已经完成可以合并到主分支git merge feature/hello合并完成后删除功能分支git branch -d feature/hello-d只有在分支已合并的情况下才会删除成功。如果分支还没合并就强制删除用-D。新手尽量不要用-D。4.3 冲突合并看到尖括号不要慌合并时出现冲突是最让新手心慌的一件事。冲突本身不代表着代码被毁掉而是 Git 发现同一个文件的同一个区域两边改动不同无法自动决定保留哪一个。出现冲突时git status会标出both modified对应的文件里会有类似这样的标记 HEAD 当前分支的内容 功能分支的内容 feature/hello处理方式很简单打开冲突文件看三段标记。决定保留哪部分或者把两边内容合并成新代码。删除、、这些标记行。保存文件后执行git add再执行git commit。冲突标记本身不是代码是给人类看的提示。处理完冲突之后如果合并结果不对还能在执行提交之前再做一次确认。新手不要急着删文件先看两边内容再决定最终版本。4.4 给新手的日常分支习惯我建议新手从一开始就养成这几个习惯主分支尽量保持可运行状态不要在主分支上直接开发新功能。每个功能单独开一个分支分支名字用简短清晰的英文比如feature/login、fix/typo。提交频率高一些一次提交只做一件事提交信息写清楚。合并之前先git status和git log确认当前状态不要蒙着眼睛合并。分支玩明白之后Git 的绝大多数场景你就都能应对了。5. 第一次把代码推到 GitHub5.1 注册账号和新建远程仓库登录 GitHub 之后点击右上角“”号选择 “New repository”。这里有两个关键选项Repository name仓库名建议和本地项目名一致不要带空格。Public / Private公开还是私有。学习阶段的代码建议选 Public方便随时分享不想公开的项目选 Private。还有一个容易踩坑的选项如果本地已经初始化过 Git 仓库就不要再勾选 “Add a README file” 或 “Add .gitignore”否则本地仓库和远程仓库会有一次完全不同的首次提交后面推送时容易出现冲突。新建完成后GitHub 会给出页面地址比如https://github.com/你的用户名/仓库名.git接下来要做的是把本地仓库和远程仓库关联起来。5.2 用 SSH 免密连接 GitHub本地往 GitHub 推送代码有两种常见方式HTTPS 和 SSH。HTTPS 方式虽然不需要提前配置密钥但 GitHub 现在不允许用账号密码直接推送代码需要额外生成 Personal Access Token对新手而言更绕。我更建议直接用 SSH配置一次之后免密推送用起来省心。先检查本机是否已经有 SSH 密钥ls -la ~/.ssh如果看到id_ed25519.pub或id_rsa.pub说明已经生成过。没有的话执行ssh-keygen -t ed25519 -C youexample.com一路回车默认保存位置即可。如果有旧系统不支持 ed25519可以改用 RSAssh-keygen -t rsa -b 4096 -C youexample.com生成完成后查看公钥内容cat ~/.ssh/id_ed25519.pub把输出的内容完整复制。然后打开 GitHub 的 Settings - SSH and GPG keys - New SSH key粘贴保存。验证连接ssh -T gitgithub.com看到提示成功关联账号说明 SSH 配置完成。5.3 把本地仓库推送到远程先在 GitHub 仓库页面复制仓库地址。如果你用 SSH地址长这样gitgithub.com:你的用户名/仓库名.git在本地项目目录执行git remote add origin gitgithub.com:你的用户名/仓库名.git git branch -M main git push -u origin main第一条命令把远程仓库地址起名为origin这是 Git 默认的远程名称大家约定俗成。第二条命令把当前分支重命名为main保证和远程分支一致。第三条命令把本地 main 分支推送到远程并用-u建立关联。建立关联之后以后直接执行git push和git pullGit 就会知道对应的是哪个远程分支。推送完成后刷新 GitHub 页面就能看到你的代码了。5.4 换电脑拉取代码clone、fetch、pull 怎么选换了一台新电脑想从 GitHub 拉取项目代码最直接的方式是git clone gitgithub.com:你的用户名/仓库名.gitclone会把远程仓库完整复制到本地包括所有提交历史不需要再手动git init。日常同步更新时有两个命令要分清楚git fetch只把远程的提交记录拉到本地但不会自动合并到当前分支。git pull等于先fetch再merge一步到位把远程改动合进当前分支。新手日常使用直接git pull就够了。但要理解pull本质上是一个组合动作如果远程和本地都改了同一个文件仍然可能产生冲突。fetch的优势是先把远程改动取下来看一眼再决定要不要合并适合想更谨慎控制流程的情况。下面这个表可以直接保存命令作用会不会改动本地工作区适合场景clone复制远程仓库到本地会创建新目录新电脑、第一次拉项目fetch获取远程提交记录不会自动合并想先看再合并pull获取并合并远程提交会返回后直接改动工作区日常同步最新代码6. 多人协作时的 GitHub 流程与常见报错6.1 先拉再推是协作的基本顺序多人协作时最常见的错误就是本地改了代码直接执行git push结果提示提交被拒绝。原因通常是远程仓库已经有了别人推送的新提交而你的本地历史落后了。这个问题的专业说法是non-fast-forward翻译成大白话就是你的本地仓库不是基于远程最新版本改的。正确顺序是git status确认当前改动状态。git pull拉取远程最新代码。如果有冲突在本地解决冲突并提交。再次git push。这个顺序看起来简单但很多人一忙起来会把第 2 步省掉于是错误反复出现。养成“先拉再推”的习惯能少踩很多坑。6.2 Pull Request 和 Fork 到底怎么用Pull Request 通常简写为 PR是 GitHub 上发起代码合并申请的方式。它不是一个 Git 命令而是 GitHub 平台的协作功能。流程是这样的你把本地功能分支推送到 GitHub 仓库。在 GitHub 页面上点击 “Compare pull request”。填写说明说明这次改了什么、为什么要改。仓库维护者审查代码可以留言让你修改。通过后点击 “Merge pull request”功能分支合并进目标分支。如果是给别人仓库贡献代码一般不用直接推送而是先点击 GitHub 仓库页面的 “Fork” 按钮把项目复制到自己的账号下然后修改自己 Fork 出来的仓库最后通过 Pull Request 把改动提交给原作者。Fork 和 Clone 的差别自己体会一下Fork 的最终结果是产生一个属于你的远程仓库副本。Clone 的最终结果是产生一份本地代码副本。实际开发中两者经常配合使用先 Fork再 Clone 到本地改完 Push 到自己的 Fork最后发 PR。6.3 新手最容易踩的四个报错和排查顺序遇到报错时先不要急着百度整条报错按照下面这个顺序排查先看命令在哪个目录执行的再看配置有没有生效再看远程地址对不对最后看分支状态。下面是四个高频报错和对应处理方式。报错信息原因排查与解决Please tell me who you are没有配置 user.name 和 user.email执行git config --global user.name 你的名字和git config --global user.email youexample.comfatal: not a git repository当前目录不是 Git 仓库用cd切换到项目目录或者确认是否执行过git initfailed to push some refs远程有本地没有的提交先git pull解决冲突后再git pushremote origin already exists已经添加过 origin 远程地址用git remote set-url origin 新地址修改或git remote remove origin后重新添加这里特别提醒一点remote origin already exists不代表代码有问题它只是说明远程地址已经设置过了。不要急着删仓库先执行git remote -v看看当前 origin 指向哪里确认地址是否是自己要的。如果git pull之后出现冲突标记回到前面第 4 章讲的处理方法先打开文件再决定保留哪部分最后git add和git commit。冲突处理完之后推送前再看一次git status确认没有遗留的未提交文件。我个人最想强调的一点是把报错当成信息而不是灾难。Git 的报错信息已经写得比较清楚了新手只要养成先看报错、再看路径和分支的习惯大部分问题都能自己定位。真正需要小心的是reset --hard、push -f这类会改写历史或远程状态的命令在还不确定后果之前不要轻易使用。Git 和 GitHub 的学习曲线不在于命令数量而在于你能不能把“工作区、暂存区、本地提交、远程仓库”这四层关系理清楚。先跑通一次单机提交再跑通一次远程推送然后开一个分支做一次合并。等这套流程变成肌肉记忆再去看更复杂的 rebase、stash、子模块和 CI/CD都会顺畅很多。