简介GitHub 是广受欢迎的代码托管与协作平台很多初学开发者对仓库概念、分支管理、合并请求等操作感到陌生这份教程以 PDF 文档为载体由浅入深地梳理了一套完整的 GitHub 使用流程。内容从注册账户开始依次讲解创建仓库、克隆项目到本地、添加文件并提交更改、创建分支、完成合并以及发起和审核 Pull Request还补充了 Issue 追踪、团队讨论和参与开源贡献的方法无论用于个人学习还是团队协作都能快速上手。资源包非常轻量仅含一个 PDF 文件大小约 91KB内容精炼方便在电脑或手机上随时查阅。目前已有 3458 人学习下载实用性得到不少用户认可。学完这份教程你将能独立完成从零搭建 GitHub 工作环境、管理代码版本、协作开发乃至向开源社区提交贡献的完整闭环节省大量盲目搜索的时间。1. 一份能离线回看的 GitHub 教程才是真的能救场的那份打开 GitHub 官网卡半天、clone 一个几 MB 的仓库能断三次、push 代码时提示认证失败——这些场景几乎每天都在技术群里出现也正因为如此“github使用教程”才始终是高频检索词。这篇笔记按一份可打印成 PDF 的手册来写概念只讲够用的命令直接给可复制的参数标明为什么这么设最后补一组避坑记录。目标是让新手照着敲完能跑通第一轮 clone-push-PR 流程让已经用了一段时间的人把模糊概念和反复踩的坑对齐。适合所有打算认真用 GitHub 做开源协作、项目存档或自动化部署的开发者哪怕你之前只会在网页上点 Download ZIP。2. 先立框架仓库、分支、提交不过关后面全是玄学2.1 Git 与 GitHub 的关系很多教程把这两件事混着讲反而把人绕晕Git 是分布式版本控制工具它在本地记录每一次文件变更GitHub 则是基于 Git 的远程托管与协作平台。两者不是同一个东西哪怕完全不联网Git 也可以正常 commit而 GitHub 解决的更偏向“怎么把本地提交同步给别人、怎么审阅、怎么发布”它天然依赖网络。很多新手把 GitHub 当网盘用只下载不提交等于完全没过本地提交这一关后面看协作教程会越看越懵。先建立这个区分后面的命令才有归属感。在 GitHub 上找学习资料和开源项目时正确姿势是先 fork 到自己账号下再 clone而不是直接在网页里下载 zip。fork 像是复制一份到你的名下复制品与原仓库保持连接方便你后续提交改动并发起 Pull Request。这套流程理解了GitHub 的核心协作模型就通了。2.2 最小可用的 GitHub 协作模型fork → clone → push → pull requestFork 是在别人仓库名下复制一份到你的账号clone 把远程仓库拉到本地push 把本地提交推回自己账号下的仓库pull request 则是“请求原仓库维护者把你的改动合并进去”。这个流程适合所有你在 GitHub 上找到的开源项目不要试图直接往别人仓库 push你大概率没有写权限常见做法是先 fork。# 假设你已经 fork 了某项目后端地址换成你自己的账号路径 git clone gitgithub.com:你的用户名/learning-git.git cd learning-git git checkout -b docs/update-readme # 改完 README 后执行下面三行提交并推送 git add README.md git commit -m docs: 补充快速开始段落 git push origin docs/update-readme说明git checkout -b是新建并切换分支这条新分支只存在于本地push 之后 GitHub 上才会出现对应远程分支git commit -m后面跟的是提交信息最好写清楚“这段改动做了什么”而不是随手写个 update。至于为什么不直接在默认分支上改PR 需要让维护者看到一个干净、可审阅的差异一堆和主题无关的中间提交会让合入变得困难。2.3 提交、标签、发布三者的边界不要混淆场景用哪个一句话说明本地改完代码要留个记录git commit每次提交是一次独立的快照给某个里程碑定个名git tag v1.0.0tag 指向某一次 commit把代码打包给别人下载GitHub Release网页操作附带 zip 和变更说明很多新手把这三件事混在一起以为打了 tag 就等于发布了或者以为 commit 到本地之后别人就能看到。实际上 release 是项目交付的门面用户只认 Releases 页面tag 是 Git 层面的标记release 一定基于 tag但 tag 本身不要求有 release。日常开发中commit 的频率可以很高而 tag 和 release 要克制只在真正可交付的节点才打。3. 本地环境与 SSH 认证照着敲就能跑通的 20 分钟3.1 装 Git 与第一级配置三个平台各自一条命令Windows 上用包管理器装 Git 最省事macOS 建议走 HomebrewLinux 发行版仓库里的版本通常足够新。装完别急着 clone先把三组全局配置写上。# Windows winget install --id Git.Git -e --source winget # macOS brew install git # Debian / Ubuntu sudo apt update sudo apt install git -y # 三组通用配置新机器必做 git config --global user.name 你的名字 git config --global user.email 你的邮箱 git config --global init.defaultBranch main说明user.name 和 user.email 会固化进每一次 commit 记录里不配的话 Git 会拿机器名拼一个随机字符串后续在 GitHub 上关联头像和主页会非常麻烦。init.defaultBranch main是为了让本地初始化的仓库默认分支名和 GitHub 保持一致避免“本地 master、远程 main”的分支错位问题。3.2 生成 SSH 密钥并添加到 GitHub免密认证的关键一步HTTPS 方式每次 push 都要输入账号口令token 过期后又得重新生成SSH 的体验好得多。首先生成密钥对公钥放到 GitHub私钥留在本地之后所有 git 操作都不需要再输密码。# 生成 ed25519 密钥-C 只是备注写邮箱或昵称均可 ssh-keygen -t ed25519 -C 你的邮箱或者昵称 # 把密钥加载进当前 shell 的 ssh-agent eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 # 打印公钥内容复制这一整段粘贴到 GitHub 网页 cat ~/.ssh/id_ed25519.pub说明ed25519 比 RSA 密钥短、生成快新机器上安全强度足够如果你的操作系统或内部工具链比较老再退回rsa -b 4096。公钥是公开信息复制粘贴到网页不会泄露敏感内容私钥留在本地~/.ssh/id_ed25519不要发给任何人。此时在 GitHub 网页打开 Settings → SSH and GPG keys → New SSH key把cat出来的内容粘贴进去保存。验证是否通ssh -T gitgithub.com看到 “Hi 你的用户名! Youve successfully authenticated” 就说明通了。这一步失败最常见的原因是公钥没粘贴完整或粘贴时带了换行。3.3 远程地址该用 HTTPS 还是 SSH按网络环境选连接方式默认端口适合场景主要麻烦HTTPS443办公网络限制少每次需要凭据管理或 tokenSSH22长期开发环境首次要生成密钥并部署公钥SSH over 44344322 端口被限制时需要额外配置 ssh configGitHub 官方为 22 端口被限制的场景提供了 443 端口连接方式配置在~/.ssh/config里对日常使用没有感知差异。我一般会先试标准 SSH如果公司网络连 22 端口不通再切到 443。HTTPS 不是不能选只是要配好凭据管理器否则每次 push 都弹一次账号密码很快会烦。4. clone 慢、下载老断给 GitHub 访问提速的几种落地手段搜索词里“github打不开”“github官网进不去”常年排在前列。经验是遇到这类问题先别急着换镜像第一步永远是定位是域名解析慢还是连接建立后传输慢。这两个环节的补救方式完全不同。4.1 先定位瓶颈DNS 解析卡住还是传输过程慢# 测量域名解析耗时 time nslookup github.com # 测量建立 HTTPS 连接耗时 time curl -I https://github.com如果nslookup结果返回要好几秒说明本地 DNS 解析环节耗时常见做法是改用公共 DNS或者清掉 hosts 里过时的旧条目。如果nslookup很快、curl却迟迟没有响应说明是网络链路到 GitHub 的传输慢这种慢大多集中在跨境链路上继续看下面的传输层补救办法。curl -I只拿响应头、不下载 body适合快速连通性验证time输出里的 real 是总耗时一眼能看出卡在哪。4.2 镜像站与加速前缀clone 与 release 下载的常用做法“github镜像站”“github国内加速网站”“github下载加速”这些词背后是同一个诉求让 GitHub 上公开仓库的内容能被更快拿到。这类服务本质是只读加速中转把 GitHub 的文件通过带宽较好的节点转发用法是给原始地址加一个前缀。# 小仓库直接 clone整体 URL 作为路径拼在加速前缀后面 git clone https://加速前缀/https://github.com/owner/repo.git # 大仓库建议加 --depth 1只取最新一次提交 git clone --depth 1 https://加速前缀/https://github.com/owner/repo.git # release 附件同样能套用 wget https://加速前缀/https://github.com/owner/repo/releases/download/v1.0.0/app.zip说明加速前缀只对公开仓库的读取有效不能拿来做 push也不建议长期依赖——这类服务的可用域名经常变化适合“临时下载某个仓库或 release 包”的场景。用完记得检查一下远程地址确认 remote 仍然指向官方 GitHub 而不是中转站避免后续 push 到不该去的地方。4.3 不 clone 的方案直接下 zip 或 tarball如果只想要源码看看思路不需要提交历史完全不必git clone。GitHub 每个仓库页面都有 Download ZIP 按钮这种下载方式比 clone 少传整个.git目录速度快很多。命令行方式# 假设默认分支是 main wget https://github.com/owner/repo/archive/refs/heads/main.zip unzip main.zip说明URL 中refs/heads/main对应默认分支名如果仓库默认分支是 master就改成refs/heads/master。zip 里没有.git目录自然无法 push这是它和 clone 的本质区别适合“只用不改”的场景。很多人在 GitHub 上找学习资料时就是下 zip 快速看等确定要参与贡献了再 fork clone。4.4 调 Git 传输参数与浅克隆不依赖外部服务时怎么减少失败某些场景下中转服务不可用只能直连。此时可以调整 Git 自身的传输行为降低“克隆到一半断掉”的概率。# 大仓库浅克隆只取最新一次提交 git clone --depth 1 https://github.com/owner/repo.git # clone 过程中经常断把单次传输缓冲调大单位字节 git config --global http.postBuffer 524288000 # 关闭低速限速开关避免传输一慢就被判定失败 git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999说明http.postBuffer默认值较小克隆或推送大文件时容易在长连接中途断开调整到524288000约 500MB是社区里的高频做法http.lowSpeedLimit和http.lowSpeedTime这对参数是“传输速度低于阈值就终止”的保护机制设成 0 和 999999 等于让它别因为轻微网络抖动就误杀连接。浅克隆拿不到提交历史后续想补完整历史就执行git fetch --unshallow。5. 避坑手册GitHub 日常使用最常见的五个翻车现场下面这些坑属于真正的“血泪经验”每条按“现象 → 原因 → 解决”写打印出来对表排查会很顺手。5.1 push 报错 fatal: unable to access现象git push到任意仓库都报fatal: unable to access https://github.com/...。原因最常见是当前网络链路到 GitHub 不通或者本机 Git 配置里残留了指向失效端口的网络访问配置。后一种情况在“曾经配过某些网络配置后来又关掉”的机器上特别常见。解决先执行git config --list看全局有没有不认识的 http 相关项用git config --global --unset 配置项名清掉再用curl -I https://github.com确认直连是否恢复。如果直连仍然失败回到第 4 章的加速手段临时处理。5.2 每次 pull 都要输一次账号密码现象HTTPS 方式操作仓库时每次 pull 或 push 都弹窗要账号、密码。原因没有配置凭据管理器Git 每次都要重新认证。很多新手以为这是“正常的”其实可以一次配好。解决Windows 执行git config --global credential.helper manager-coremacOS 用osxkeychainLinux 可以用store但它是明文存储更推荐libsecret。如果不想折腾直接转到 SSH 认证一劳永逸。5.3 clone 大仓库老是 early EOF / index-pack failed现象克隆到一半中断报error: RPC failed; curl 56 OpenSSL SSL_read: Connection was reset或fatal: early EOF。原因网络链路不稳定加上 Git 默认缓冲区偏小单个请求在传输大对象时被掐断。这在 clone 带大量二进制资源的仓库时特别常见。解决先用第 4.4 节的--depth 1浅克隆减量再加http.postBuffer调大缓冲如果还失败换镜像或加速前缀重新拉。记住不要反复重试同样的直连命令那基本是浪费时间。5.4 本地 master 推不到远程 main现象git push -u origin master报error: src refspec master does not match any。原因本地仓库初始化时的默认分支是 master而 GitHub 远端默认分支是 main两边分支名不一致push 无对应引用。解决本地执行git branch -M main把当前分支改名再git push -u origin main。-M是大写强制改名如果已经推过 master 到远程还需要在网页上把默认分支切回 main 再删掉旧分支。5.5 本地 commit 了网页仓库里却什么都没有现象git commit成功git log也有记录但 GitHub 网页上看不到任何新提交。原因commit 只写在本地没有执行 push或者当前分支没有关联远程分支push 无从谈起。解决先git remote -v确认远程地址存在再git push origin HEAD把当前分支推上去。HEAD表示当前所在分支不需要手打分支名能少敲几个字。6. 把常用操作做成自己的速查表命令、参数与一句验证教程看到这里真正有用的是把它沉淀成自己的速查表。我的建议是浏览器里按 CtrlP 把这页存成 PDF放到项目文件夹里下次卡住时直接搜命令不用重新翻网页。想做的事命令或操作关键参数新机器初始化git config --global user.name/user.email再ssh-keygeninit.defaultBranch main日常提交git addgit commitgit pushcommit 信息写清做了什么同步远端更新git pull --rebase避免多余合并节点临时拿代码git clone --depth 1或 Download ZIP大仓库优先浅克隆下载 release 附件wget加加速前缀看 releases/download 路径判断项目是否活跃看 stars、最近 commit 时间、issue 响应网页操作即可新机器配好之后我习惯按顺序过三件事git config --list确认身份ssh -T gitgithub.com确认认证再git clone一个小仓库跑通全链路。三件事全过才开始干正事。这套习惯帮我省了很多“黑匣子”式排查时间比出问题再找后悔药靠谱得多。希望帮到你。本文还有配套的精品资源点击获取
