我这两年陆陆续续带过不少新人入门 GitHub发现一个很有趣的现象大部分人是被第一次的全英文报错吓退的而不是被概念难倒。什么 “Permission denied (publickey)”“non-fast-forward”“Failed to connect to github.com port 443”任何一个冒出来都足以让新手当场石化。所以这篇我不想写成一堆命令的堆砌而是按我实际带人的路径来先花 30 分钟把建仓、提交、协作这条主干跑通再回头把每次操作背后的逻辑、每个常见报错的排查思路讲清楚。你不需要背命令只需要理解“我为什么要敲这一行”等理解了命令自然就记住了。文章不区分平台Windows 和 macOS 都能跟着操作。1. 开工前的准备装好 Git配好“身份”和“钥匙”1.1 为什么我坚持让你用命令行而不是图形工具市面上有大量 Git 图形客户端什么 SourceTree、GitKraken、VS Code 自带的图形操作甚至网页端直接上传文件都能完成“提交”这件事。那为什么我还要让你先学命令行核心原因有两个。第一命令行是所有工具的共同底层不管以后你换什么 IDE、换什么客户端底层跑的其实都是那些命令你先理解了命令图形界面只是壳。第二Git 的报错信息本身就是最好的老师而图形客户端往往会把报错吞掉只弹一个“出错了”你反而不知道发生了什么。命令行原样把错误打出来配合搜索引擎基本没有解决不了的问题。1.2 三步完成 Git 安装不同系统的安装路径不太一样但都不复杂Windows去 Git 官网git-scm.com下载安装包一路 Next 基本没问题。只有一步需要留意在 “Select Components” 那一步默认会勾选 “Git Bash Here” 和 “Git GUI Here”建议都保留。装完在开始菜单里打开Git Bash这就是你以后在 Windows 上敲 Git 命令的终端。macOS最简单的是先敲git --version如果没装系统会弹窗提示你安装 Command Line Tools也可以先装 Homebrew然后brew install git。LinuxUbuntu/Debian 系sudo apt update sudo apt install git。装完不要急着下一步先验证一下git --version只要能输出类似git version 2.39.2这样的信息就说明装好了。如果提示 command not found多半是安装没成功或者装完没重开终端。1.3 配置身份信息越早越好Git 的每条提交记录上都会记录“谁在什么时候干了什么”这个“谁”就是靠下面两个配置来识别的git config --global user.name 你的名字 git config --global user.email 你的邮箱这里有一个新人特别容易踩的坑邮箱不一定非得用注册 GitHub 的邮箱但建议用同一个。因为 GitHub 会通过邮箱把提交记录关联到你的账号上。你在本地提交得再勤快如果邮箱和 GitHub 账号对不上账号主页的 Contribution Graph就是那个绿格子图就不会亮我看着都替你心疼。验证一下配置是否生效git config --global --list1.4 生成 SSH Key给 GitHub 一把“钥匙”配置好身份之后还要解决“怎么证明你是你”的问题。Git 和 GitHub 之间传输数据有两种验证方式HTTPS每次 push 都要输用户名和密码现在密码已经改成 Personal Access Token后面会讲麻烦。SSH生成一对密钥把公钥放到 GitHub 上之后传输就走加密通道免密操作。我建议直接用 SSH一次配置长期受用。生成方式ssh-keygen -t ed25519 -C 你的邮箱它会问你要把钥匙保存在哪里直接回车用默认路径就行。接下来会问你要不要设 passphrase口令新手建议直接回车跳过否则以后每次操作都可能要求输入口令很影响体验。然后查看公钥内容cat ~/.ssh/id_ed25519.pub把输出的那一段ssh-ed25519 AAAA...完整复制下来登录 GitHub点右上角头像 → Settings → SSH and GPG keys → New SSH key粘贴保存。验证是否配对成功ssh -T gitgithub.com如果看到Hi 你的用户名! Youve successfully authenticated之类的提示就大功告成了。第一次会问你是否确认连接输入 yes 回车即可。提示Windows 用户如果在家目录下找不到.ssh文件夹在 Git Bash 里执行ls -a ~/.ssh试试带-a才会显示隐藏文件。2. 建仓从零到第一次 push20 分钟拿捏先说个题外话我见过有人搜索“建仓”搜到股票技术分析去的。这里得澄清一下GitHub 里的“建仓”就是创建一个仓库repository跟股票的建仓完全两码事。2.1 网页端建仓库时为什么建议什么都不勾登录 GitHub 后点右上角那个 “” → New repository会看到一堆选项。很多人纠结要不要勾选 “Add a README file”“Add .gitignore”“Choose a license”。我的建议是第一次练手全部不勾。原因是在 GitHub 上勾选这些选项相当于在远程仓库里自动生成了文件。如果你本地也准备了一个文件夹要作为仓库本地和远程就会各自有“第一次提交”一个叫 initial commit一个叫 Initial commit历史分叉第一次 push 就会撞上 non-fast-forward 错误给新手平添烦恼。等以后熟练了再勾也不迟。仓库名字随便起比如hello-github然后保持默认的 Public公开就行。如果不想让别人看到就选 Private私有这个不影响操作。2.2 本地初始化并完成第一次提交在本地准备一个文件夹比如~/dev/hello-github然后在这个目录里打开终端Windows 用户在文件夹里右键 → Git Bash Here执行git init这条命令会在当前目录下创建一个隐藏的.git文件夹仓库的“灵魂”就在这里。然后创建一个文件比如README.md往里面随便写点内容echo # Hello GitHub README.md接下来是三个高频命令以后每天都会用到git status git add README.md git commit -m chore: init projectgit status查看当前仓库状态git add把文件放进暂存区git commit把暂存区的内容固化成一条提交记录。一开始不理解的“暂存区”是什么没关系你就记着add 是选中要提交的文件commit 是最终落锤存档。-m后面跟的是提交信息这行字会跟着这条提交记录永远留在历史里所以别乱写后面专门讲怎么写。2.3 关联远程仓库并推送网页端的仓库创建好之后GitHub 会给我们几条命令先关联远程仓库git remote add origin gitgithub.com:你的用户名/hello-github.git这里的origin是一个别名代表“远程仓库的位置”。之所以叫 origin是沿用 Git 早期版本的习惯叫法约定俗成你也可以改成别的名字但没必要。然后推送git push -u origin main-u是--set-upstream的简写意思是“把本地 main 分支和远程 main 分支关联起来”。加上它以后在这个目录里直接敲git push就能推送不用再带参数。到这里刷新一下 GitHub 仓库页面看到README.md出现了恭喜你的第一条提交已经上线。2.4 push 失败的第一次心理建设如果你在 push 这一步遇到了红色报错不要立刻怀疑人生这是每个 Git 用户都会经历的事。常见原因无非三种SSH 钥匙没配对、远程有本地没有的提交、或者网络抖动。详细的排查链路我放在本文第 5 章单独讲这里只想说一句报错是 Git 在尝试和你对话把它当成线索别当成判决书。我给新人的标准建议是第一次操作如果 push 没成功先别急着反复重试把报错原文复制到笔记里对照后面第 5 章的表格一条条查比自己瞎试有成就感得多。3. 提交的学问commit 的粒度、规范与“后悔药”建仓跑通之后很多人就开始了“疯狂提交”阶段一天下来提交了五十次信息全是 “Update”“修正”“111”。这种习惯在个人项目里问题不大一旦进入团队协作code review 和问题回溯时就会非常痛苦。3.1 一次提交只做一件事提交的最佳粒度是原子化。一次提交对应一个逻辑改动比如“修复了登录页的密码校验 bug”“新增了导出功能的单元测试”“更新了 README 里的安装说明”这三件事应该拆成三次提交而不是混在一起。为什么三个理由回滚精准如果一次提交里混了三件事哪一件出问题了你没法只回滚那一部分。审查清晰同事做 code review 时看到的 diff 应该是和提交信息匹配的否则他要在一个提交里猜两三个意图。追责高效用git bisect这类二分查找工具定位 bug 时提交粒度越细定位越快。3.2 提交信息这样写同事看一眼就懂业界比较流行的格式是Conventional Commits约定式提交格式大概是type(scope): subject其中type表示类型最常用的几个feat新功能fix修复 bugdocs文档变更style格式调整不影响代码逻辑refactor重构不改变外部行为test补测试chore构建工具、依赖变动等杂项例如feat(auth): 新增手机号登录 fix(login): 修复密码输入框无法粘贴的问题 docs(readme): 补充本地开发环境搭建说明第二行的 subject 不要用 “update”、”修改”这种口水话要写清楚“做了什么改变”。提交信息实际上是给未来的自己留的便签你不可能记得三个月前那次 “Update” 到底更新了什么但 “fix(login): 修复密码输入框无法粘贴的问题” 一眼就能捡起来。3.3 改错了怎么办amend、reset、revert 的取舍提交完之后发现写错了是新人高频需求。我按场景给三个命令场景一刚提交完发现提交信息写错了或者漏了一个文件。git commit --amend这个命令会修改最近一次提交把暂存区里新增的内容并进去同时可以改提交信息。注意--amend适合还没 push 到远程或者改了之后确认不会影响别人的分支的场景。如果已经 push 到共享分支就不要 amend 了后面讲 revert 更安全。场景二提交了不该提交的内容想撤销提交但保留代码改动。git reset --soft HEAD~1HEAD~1表示“最近一次提交之前”。--soft意味着这次撤销只动 HEAD 指针你工作区和暂存区里还保留着改动可以重新整理后再提交。场景三提交已经推送到远程共享分支想撤销某次提交带来的改动。git revert commit-hashrevert不会删除历史而是新增一条反向提交把之前的改动“逆转”回来。这条命令在团队项目里最安全因为它不修改历史不会让同事的本地分支和远程分支产生诡异的分叉。3.4 三个查询命令让你随时知道仓库发生了什么日常开发中我使用频率最高的查询命令就是这三个git log --oneline git diff git statusgit log --oneline每行显示一条提交的简写 hash 和提交信息快速浏览历史。git diff查看工作区尚未暂存的改动想看已经暂存的改动用git diff --cached。git status查看当前所有文件的状态已跟踪、已修改、已暂存、未跟踪。还有一个超级后悔药值得记住git reflog。它记录的是HEAD 指针每一次移动的痕迹相当于 Git 的操作日志。就算你reset错了误删了提交在 reflog 里也能找回之前的 hash 并恢复回来。我救过不少同事的命强烈建议新人先把这五个命令刻进肌肉记忆。4. 协作从 clone 到 Pull Request 的完整链路这里的“协作”指的是人和人在代码仓库里分工配合不是工业机器人那类协作哈。Git 能走到今天靠的不是单机版本管理而是它那套分布式协作模型。4.1 选好协作模型比学会命令更重要团队协作前得先定一个工作流模型。模型虽然有好几个但对绝大多数中小团队和开源项目GitHub Flow是性价比最高的选择主分支叫main任何时候都应该保持可部署状态新功能一律从main切出feature/xxx分支开发完成后 push 到远程同名分支发起 Pull Request经过代码审查和 CI 检查后合并回main。它简单在哪核心只有一个长期分支main所有临时分支的生命周期都很短避免了 Git Flow 里 develop、release、hotfix 一堆分支带来的心智负担。个人项目和小团队从 GitHub Flow 起步基本不会错。4.2 一次标准的功能开发长什么样假设你要给上文那个hello-github仓库加一个新功能“显示当前时间”一次标准流程是git clone gitgithub.com:你的用户名/hello-github.git cd hello-github git checkout -b feature/show-timegit checkout -b是 “新建分支并切换过去” 的快捷写法等价于先git branch feature/show-time再git checkout feature/show-time。然后写代码写完提交git add . git commit -m feat: 显示当前时间 git push -u origin feature/show-time注意这里推的是feature 分支不是直接推 main。这一步非常关键直接推 main 意味着你和团队之间少了一个 review 关卡出问题的概率会指数级上升。4.3 Pull Request 的正确打开方式push 完成之后GitHub 上会出现一个醒目的 “Compare pull request” 按钮点进去之后要填的内容才是重点标题和提交信息一样写清楚“做了什么”别写“更新”。描述说清楚这个 PR 的背景、改动内容和测试方式。可以勾选关联 issue比如Closes #12合并后对应 issue 会自动关闭。测试说明告诉 reviewer 你验证过哪些场景。哪怕只是“本地跑通覆盖了正常和异常输入”也很有帮助。PR 是异步协作的载体不是聊天工具。好的 PR 描述能帮 reviewer 快速进入状态也能在几个月后让查阅历史的人不迷路。4.4 Code Review 的几种反馈与处理建议收到 PR 被 review 的意见新人心理上很容易出现两种极端要么觉得“被批评了”心里不舒服要么觉得“无所谓”全盘忽略。我的建议是摆正心态review 是冲着代码去的不是冲着你的人。常见的 review 意见类型和处理方式意见类型示例处理方式建议型“这个变量名是不是可以改成 xxx 更直观”认同就改不认同就在评论区友好讨论问题型“这里如果入参为 null会不会 NPE”认真评估确实有问题就补逻辑规范型“代码风格和项目规范不一致”直接改这类问题没有讨论价值阻塞型“这里有个并发安全漏洞需要修复后合入”必须处理处理完回复“已修复请复查”处理完 review 意见后重新 commit 并 push 到同一个分支PR 会自动更新不用重新发起。4.5 合并策略怎么选历史才好看Pull Request 合入 main 时GitHub 会提供几种合并策略常见的是Create a merge commit保留分支的所有提交历史会多一个 merge commit图上看得出来分叉。Squash and merge把分支上的所有提交压缩成一个 commit合入后历史是一条直线。Rebase and merge把分支上的提交逐个重放到 main 上也是直线历史但保留多次提交。我个人的偏好功能分支默认用 Squash and merge。理由很实在feature 分支上的提交往往比较随意“wip”“fix typo”“again”全部压成一个语义清晰的提交再进主分支git log看起来干净得多。只有当你明确想保留分支上每一步中间状态时才选 merge commit。4.6 AI 协同下的协作新变化说到协作最近 GitHub 上“vibe coding”这个词很火也就是开发者用 AI 工具生成大半代码自己更多承担评审、纠偏和设计的工作。多 agent 协作开发也成了一个热门讨论话题。我的观察是AI 工具改变了写代码的速度但没有改变协作的节奏。代码仍是提交到仓库的PR 还是要 review 的测试还是要过的。甚至因为 AI 生成的代码量大PR 的 diff 会比以前更臃肿团队反而更需要定好提交规范和 Review 流程否则历史会变成一片混沌。如果你在用 Copilot 或 ChatGPT 辅助开发我有一条很实际的建议让 AI 帮你生成代码没问题但提交信息和 PR 描述一定要人工过一遍别直接复制 AI 生成的 “feat: add new feature” 这种垃圾描述那等于把责任甩给了未来的阅读者。5. 新人最容易踩的坑push 失败与网络异常排查这一章是全文最实用的部分建议先收藏。我按报错信息来分类讲每个都给排查链路而不是直接丢答案。5.1 “non-fast-forward”不是灾难是保护报错示例! [rejected] main - main (non-fast-forward) error: failed to push some refs to github.com:xxx/hello-github.git hint: Updates were rejected because the tip of your current branch is behind这句话翻译成人话远程分支上有你本地没有的提交Git 拒绝覆盖别人的工作。这是保护机制不是错误。排查和处理链路先执行git fetch把远程分支的最新状态拉下来再执行git log --oneline main origin/main看看双方的差异如果你本地有独有提交远程也有独有提交就需要合并。推荐用git pull --rebase把你的提交“重放”到远程最新提交之后保持历史线性如果有冲突Git 会提示你手动解决解决完git add后再git rebase --continue最后重新git push。有一种情况特别常见你在网页端创建仓库时勾了 README本地又自己创建了一个历史天然分叉就是这个报错。5.2 “Permission denied (publickey)”基本是钥匙没配对报错示例gitgithub.com: Permission denied (publickey). fatal: Could not read from remote repository.这个问题基本都和 SSH Key 有关排查链路先验证ssh -T gitgithub.com看是不是同样的提示检查本地是否有公钥ls -a ~/.ssh看有没有id_ed25519.pub或id_rsa.pub有公钥的话用cat ~/.ssh/id_ed25519.pub复制完整内容确认 GitHub 的 SSH keys 设置里粘贴的是一模一样的内容不要多空格、不要少行如果本机用了多个账户确认当前仓库用的是哪个 keygit remote -v查看远端地址ssh-add -l查看当前已加载的 key。另一个常见原因仓库的远程地址写的是 HTTPS但你配了 SSH 的 key那 key 当然用不上。解决办法是改远程地址或者干脆用 SSH 地址。5.3 连接超时和网页打不开的排查思路在做 GitHub 开发的过程中国内开发者偶尔会遇到两类问题网页打不开、加载极慢或者命令行执行到一半报超时错误例如Failed to connect to github.com port 443: Timed out这通常和本地网络、DNS 解析或 GitHub 服务端的访问波动有关不是你的操作问题。我的排查顺序是先明确范围是只有 GitHub 超时还是所有网站都慢如果所有网站都慢先解决网络本身测试 DNS 解析在命令行执行nslookup github.com看返回的 IP 是否正常。解析异常可以尝试更换 DNS例如114.114.114.114然后刷新本地 DNS 缓存ipconfig /flushdns或sudo dscacheutil -flushcache换一种传输协议把远端地址从 SSH 切到 HTTPS或者反过来。因为不同协议走的链路不一样有时候换个协议就通了换网络环境手机热点、公司网络来回切换是最朴素也最有效的试探镜像站的正确用法网上社区常见一些 GitHub 镜像站点用来浏览代码、下载源码包是可行的。但请注意绝大多数镜像站是只读的不适合也不建议用于日常 push 操作而且第三方镜像存在安全风险涉及账号密码、密钥的操作一律不要在镜像站上做等待重试GitHub 本身偶发波动是客观存在的隔几分钟再试往往就好了。一些“打死都连不上”的极端情况大概率是网络环境的问题换个环境就恢复正常。注意无论遇到什么网络问题都建议通过正规渠道和官方文档解决不建议使用任何非官方代理工具或插件既不稳定也有安全风险。5.4 一张表收好现象、原因、对策报错/现象最容易的原因最直接的排查/解决动作Permission denied (publickey)SSH key 没配对重配公钥到 GitHub验证ssh -T gitgithub.comnon-fast-forward本地和远程历史分叉git pull --rebase后重推443 Timed out网络对 GitHub 访问波动换网络、换协议、换 DNS、等待重试fatal: could not read Username使用 HTTPS 且没带 token改用 SSH或改用 Personal Access Token网页能开图片/raw 加载不出CDN 访问异常刷新缓存、换 DNS过段时间再看git push每次都要输密码使用了 HTTPS 密码改用 SSH key一劳永逸6. 进阶让 GitHub 真正成为你的生产力工具如果你已经能流畅地建仓、提交、协作那 GitHub 这座冰山还有相当大的一部分水面下区域值得探索。6.1 用 GitHub Pages 免费托管一个个人主页GitHub 自带免费静态站点托管服务叫做 GitHub Pages。你不需要买服务器、不需要备案、不需要配置数据库只要新建一个名为你的用户名.github.io的仓库在里面放一个index.html在仓库 Settings → Pages 里把 Source 选为 main 分支。几分钟后你的个人主页就能通过https://你的用户名.github.io访问。很多开源作者的博客就是流量大而火的这也是不折腾博客框架的前提下最快把个人名片做上线的方式。更进阶一点可以配合静态站点生成器比如 Jekyll、Hugo写 Markdown 自动生成站点再配合 GitHub Actions 实现 push 后自动部署。6.2 GitHub Actions把重复劳动交给自动化GitHub Actions 是 GitHub 内置的 CI/CD持续集成/持续交付平台。它的核心能力是当仓库里发生某个事件时比如 push、PR、issue 创建自动执行你定义好的任务列表。一个非常典型的入门场景是每次 push 到 main 分支自动跑一遍测试并部署到服务器。仓库里创建一个.github/workflows/test.yml文件写一段 workflow 定义之后每次 push 测试都会自动执行如果挂了 GitHub 会在 PR 页面上直接红叉提醒。它最大的意义不是“自动化跑测试”本身而是把团队的规范从“靠自觉”变成“靠强制”。比如要求每次 PR 必须过了测试才能合并这个硬约束一旦落地主分支的质量就有了底线。6.3 值得花时间研究的功能Releases、Codespaces、模板仓库Releases给某个版本打 tag附上发布说明和二进制附件。开源项目对外发版、内部团队做版本交付都离不开它。Codespaces云上开发环境浏览器里就能打开一个带完整终端和编辑器的 VS Code 环境。对电脑配置不高的同学非常友好也方便团队统一开发环境。模板仓库把一个仓库标记为 Template之后新建仓库时可以把它作为起点一个项目的基础脚手架可以在团队内反复复用。Projects / Issues把它们当成轻量版的项目管理工具维护一个 TODO 列表、关联 issue比什么都记在脑子里强。这些功能不需要一下子全学完但值得你在日常使用中慢慢探索每一块都能省下不少重复劳动。6.4 学习 GitHub 的一个笨办法最后分享一个我自己的“笨办法”不要只阅读文档要去模仿完整的仓库。找几个你常用的开源项目去 GitHub 上看看它们的主分支结构、PR 模板、issue 模板、workflows 目录然后把它们的协作方式复制到自己的项目里。比如学到一个好的 PR 模板直接抄过来改成自己的看到一个项目的.gitignore写得好也顺手复制一份。Git 和 GitHub 的经验很大程度上是靠“抄”和“踩坑”积累的。我踩过的那些坑大多都长成了文章里的一张张表格你踩过的坑也会成为你未来带人的素材。真要说有什么心得那就是不要急着精通先把流程跑顺。30 分钟足够你学会建仓和提交但真正的熟练是在后面一次又一次的报错、解决、浏览历史里慢慢长出来的。