你是不是也遇到过这种情况：在 GitHub 仓库页面上点开 Clone 按钮，看到 HTTPS 和 SSH 两个选项，习惯性复制了 HTTPS 链接，结果每次 push 都要输用户名密码，一不小心还提示认证失败；或者明明照着网上的教程生成 SSH key、配置好了 GitHub，却始终报Permission denied (publickey)，心态直接崩掉。
这篇内容就是帮你把 Git 和 GitHub 入门阶段最常踩的坑一次性理清楚，核心围绕从 SSH 配置到克隆仓库这条主线：先搞明白 Git 和 GitHub 各自做什么，为什么日常开发我更推荐 SSH 方式；再从零开始生成密钥、配置身份、把公钥交给 GitHub；最后实操克隆仓库，并附上我在实际使用中遇到的高频问题排查记录。适合刚接触版本控制的学生、转行做开发的初学者，以及一直用 HTTPS 但想切换成 SSH 的老手。
1. 先明白 Git 和 GitHub 在解决什么问题
很多人把 Git 和 GitHub 当成同一个东西，安装完之后直接开干，出了问题一脸懵。其实这两个东西分工完全不同，理解清楚它们的关系，后面遇到报错时定位方向会快很多。
Git 是一个分布式的版本控制工具，它运行在本地，负责记录你项目文件每一次改动。你可以理解为给代码写日志：每次提交都是一次快照，里面有谁在什么时间改了哪些文件、改了什么内容，并且可以从任意一个历史点恢复回来。最关键的一点是，Git 的几乎所有操作（提交、回滚、建分支、合并）都不需要联网，它本身是一个完整的版本管理引擎。
GitHub 则是基于 Git 的代码托管平台，它把本地的 Git 仓库同步到云端，成为多人协作的枢纽。换句话说，Git 是你的本地记事本，GitHub 是公共书架的共享文档。没有 GitHub，你依然可以用 Git 做个人版本管理；但没有 Git，GitHub 上那些仓库推拉操作也根本无法落地。
那 SSH 为什么在这里面这么重要？因为 Git 自己的协议不带远程身份认证，你用git push把代码推到 GitHub 时，Git 只负责打包跟传输，它并不管你是谁。真正证明你身份的是传输隧道那一层——HTTPS 用的是账号密码或 Token，SSH 用的是密钥对。所以 SSH 配置本质上就是解决“我怎么证明我是我”的问题。搞懂这一层，你才会理解为什么ssh -T git@github.com能用来测试认证，也才知道认证失败根本不是 Git 的错，而是密钥没配对。
好，概念理清了，接下来就从最基础的安装和身份配置说起。
2. Git 安装与身份配置：90% 的新手容易忽略的一步
2.1 不同系统的安装方式
Git 的安装本身不难，但“装哪个版本、从哪里装”其实有讲究。Windows 用户一般去 Git 官网下载安装包，安装时一路默认即可。这里有一个容易被忽略的选项：在安装过程里，记得把 Git Bash 的支持选上，后续你会发现在 Windows 上敲 Linux 风格的命令非常方便，很多教程里的命令在 Git Bash 里都能直接跑。
macOS 用户最稳妥的方式不是单独下载安装包，而是装 Xcode Command Line Tools，因为很多开发工具链都会依赖它，执行下面命令后会弹出安装窗口，确认就行：
xcode-select --install如果已经装了 Homebrew，也可以用brew install git。Linux 用户则根据发行版选择包管理器，Ubuntu/Debian 用sudo apt install git，CentOS/RHEL 用sudo yum install git。
这里我要多说一句：尽量别用不知名第三方打包的“绿色版”，也不要在系统提示缺少依赖时顺手装一个看似相关的旧版本。Git 的版本影响的是底层协议兼容性和 bug 修复，新版对 SSH key 类型支持更全，处理大仓库的性能也更好。我自己见过有人在旧版 Git 上用ed25519密钥死活连不上，升级版本后问题直接消失。所以宁可花三分钟去官方渠道下载，也别省这个时间。
2.2 配置 user.name 和 user.email 的细节
安装完后第一件事不是克隆仓库，而是配置你的身份。打开终端或 Git Bash，执行下面两条命令：
git config --global user.name "你的昵称" git config --global user.email "你注册GitHub用的邮箱"很多人会问：这个配置是干嘛的？它是用来标记提交作者信息的。你每次用git commit生成一个提交，提交记录里都会带上这个名字和邮箱，别人通过 GitHub 能看到这次提交是谁干的。如果你不配置，Git 会报一个“请告诉我你是谁”的提示，并拒绝提交。
有几个细节值得注意。第一，配置分三个级别：--system（整台机器）、--global（当前用户）、--local（当前仓库）。默认建议只用--global和--local。如果某台电脑同时做个人项目和工作项目，想要不同仓库显示不同作者，可以在进入某个具体仓库目录后用不带--global的命令覆盖配置。第二，邮箱最好和你 GitHub 注册邮箱一致，因为在 GitHub 上提交记录会根据邮箱关联账号，邮箱不一致会使头像和账号归属对不上。第三，虽然 Git 允许你填一个假的邮箱，但既然要用 GitHub 做协作，那就老老实实填真实邮箱，省得后续统计贡献度时空欢喜一场。
身份配置好之后，用git config --list能查看当前所有生效配置。这一步做扎实，后面的 SSH 配置才有意义。
3. SSH 密钥配置：从生成到验证的全流程
3.1 为什么日常开发我推荐 SSH 方式
GitHub 对 HTTPS 和 SSH 都支持。HTTPS 的克隆链接长这样：https://github.com/用户名/仓库名.git，SSH 的链接长这样：git@github.com:用户名/仓库名.git。两者都能把仓库拉下来，但区别非常明显。
HTTPS 在克隆公共仓库时不需要认证，可一旦你要 push 代码，GitHub 已经不再支持用账号密码直接验证，而是要求你生成一个 Personal Access Token，把它当成密码来用。Token 有有效期，过期了又得再搞一次。SSH 则是一次配置，长久使用。密钥对里，私钥留在你本地，公钥上传到 GitHub，之后所有 push/pull 操作都靠密钥自动证明身份，不用再输任何密码。
从实际操作体验来说，SSH 的“免密”特性在日常高频推拉时极其舒服。你每天可能 push 十几次，如果每次都要找 Token 再粘贴，迟早会烦躁。另外，SSH 传输的稳定性和速度在某些网络环境下也比 HTTPS 更令人满意，我自己的体验是：只要网络本身没问题，SSH 通道很少出现半路卡死的情况。
当然也不是说 HTTPS 一无是处。在一些公司内网环境里，SSH 端口（默认 22）可能被防火墙限制，这时候 HTTPS + Token 就成了备选方案。所以我建议初学者先把 SSH 配好，把它作为日常主力，同时知道 HTTPS 怎么用，遇到特殊情况能切换。
3.2 生成密钥与 ssh-agent 管理
接下来进入核心操作。打开终端，执行：
ssh-keygen -t ed25519 -C "你的邮箱"这条命令的意思是用ed25519算法生成一对密钥，-C后面的内容只是一个注释标记，建议填你的邮箱，方便以后在 GitHub 上识别这把钥匙是谁的。为什么我默认推荐ed25519？因为它生成的密钥更短、性能更好，安全性也达到现代标准，而且 GitHub 已经完全支持这个算法。老的教程会让你用rsa -b 4096，这是为了兼容非常老的服务器，现在新环境直接选ed25519就对了。假如你的 Git 版本特别老，或必须用 RSA 的场景，再用回rsa -b 4096也不迟。
执行后，系统会问你保存密钥的位置，默认是~/.ssh/id_ed25519，直接回车默认路径即可。接着它让你设置 passphrase（口令），这个是一个额外的本地保护层：就算别人拿到了你的私钥文件，没有 passphrase 也用不了。
生成完成后，~/.ssh目录下会多出两个文件：id_ed25519（私钥）和id_ed25519.pub（公钥）。私钥绝对不要给任何人，公钥则是可以公开的。
如果你给私钥设置了 passphrase，会发现每次用 SSH 连接时都要输一遍口令，这又回到了“每次都要输入”的麻烦。解决办法是把密钥交给ssh-agent托管：
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519ssh-add第一次会让你输入 passphrase，之后 agent 会在后台帮你记住，这台电脑上再连接就不用反复输口令了。这个组合是日常开发最顺手的配置。
3.3 把公钥交给 GitHub 并验证连通性
密钥生成好了，接下来把公钥内容复制下来。Windows 上可以直接用记事本打开.pub文件，macOS/Linux 可以用cat ~/.ssh/id_ed25519.pub查看。复制整行内容，然后进入 GitHub 网站，点击右上角头像 → Settings → SSH and GPG keys → New SSH key。Title 随便填一个能识别设备的名字（比如“我的 MacBook”），把公钥粘贴到 Key 输入框，保存即可。
这一步特别容易出错的是粘贴时机：很多人复制过程中多复制了一个换行符，或者用 Windows 记事本打开时编码问题导致内容变了。最好在终端里直接输出，然后用鼠标选中复制，别手动敲，因为手动输入几乎不可能保证一字不差。
配置完成后，执行验证命令：
ssh -T git@github.com第一次连接时，GitHub 会提示你确认主机指纹，输入yes回车即可。如果看到类似Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.的输出，恭喜，SSH 认证已经通了。请注意，哪怕 GitHub 说 “does not provide shell access”，这是正常的，GitHub 不允许通过 SSH 进入 shell，只允许 Git 操作，看到这句话反而说明成功了。
我在这个环节踩过一次很无语的坑：一直报Permission denied (publickey)，检查了很多遍公钥都没问题，最后发现是配置私钥时没有用默认文件名。因为之前测试别的项目，~/.ssh下放了其他名字的密钥对，Git 默认只去找id_ed25519或id_rsa这类标准名字。如果你生成的密钥不是默认名，需要创建~/.ssh/config文件指定它，或者在ssh-add时明确添加。这个问题在下面常见问题部分会专门展开。
4. 克隆仓库：第一次把项目拉到本地
4.1 HTTPS 和 SSH 克隆链接的区别
Git 配置好、SSH 又验证通了，现在终于到了本篇的收尾主角——克隆仓库。打开任何一个 GitHub 项目首页，点击绿色的 Code 按钮，会弹出三个切换标签：HTTPS、SSH、GitHub CLI。默认显示的是 HTTPS，很多人习惯性地复制了它，但你要做的是在这一步主动点一下 SSH，再复制链接。
两种链接核心区别在于协议头和地址格式。HTTPS 以https://开头，SSH 以git@github.com:开头。如果你复制的是 SSH 链接，但本地 SSH 密钥又没配好，克隆时依然会输密码或报错；如果复制的是 HTTPS 链接，虽然克隆成功，但后面推送代码时极大概率会折腾 Token。所以，想要愉快的免密体验，从克隆这一刻就选 SSH。这也是我对所有初学者的统一建议：只要没有特殊网络限制，一律用 SSH 链接。
4.2 实操：克隆仓库并查看状态
假设我已经复制好了 SSH 克隆链接，例如git@github.com:octocat/Hello-World.git，在终端里执行：
git clone git@github.com:octocat/Hello-World.gitGit 会开始拉取远程仓库的全部历史记录，并在当前目录下创建一个名为Hello-World的文件夹。这个过程能看到进度条，如果你是在 Git Bash 里拉取，显示的是彩色的进度信息。克隆完成后，进入项目目录：
cd Hello-World接着用git remote -v查看远程仓库的地址，确认一下它是 SSH 格式而不是 HTTPS；再用git status看当前工作区的状态。克隆下来后，工作区默认是干净的，分支通常在main或master。
有一个很多人容易混淆的点：git clone默认只帮你在本地建立对主分支的跟踪，远程仓库里其他分支不会全部下载到本地。想查看远程全部分支，可以运行：
git branch -a远程分支会以remotes/origin/分支名的形式列出来。如果你想切到某个远程分支工作并创建对应的本地分支，直接用git checkout 分支名，Git 会自动完成跟踪关系。
如果你拉的是一个大仓库，或者只想看最新代码、不关心历史版本，可以使用浅克隆：
git clone --depth 1 git@github.com:octocat/Hello-World.git--depth 1表示只拉取最近一次提交，下载体积会小很多。但注意，浅克隆会限制一些依赖完整历史的操作，比如git log看不到以前的提交记录，后续想完整拉历史时要git fetch --unshallow补充。所以我的建议是：个人小项目无所谓，大型仓库只想快速跑起来时用浅克隆。
克隆到指定目录也很有用。默认目录名是仓库名，如果你想自定义，可以在命令末尾加上目录名：
git clone git@github.com:octocat/Hello-World.git my-project这样项目会下载到my-project文件夹里，文件夹名不会影响 Git 仓库的任何逻辑，纯粹是你本地的命名习惯。
4.3 克隆之后：日常推拉工作流示例
克隆只是开始，不是终点。我见过太多初学者克隆完一个项目后一头雾水，不知道接下来怎么跟远程互动。这里简单演示一个日常开发循环。
假设你修改了项目里的README.md，想把这个改动同步回 GitHub，先运行：
git add README.md git commit -m "更新README内容" git pushgit add是把改动放进暂存区，git commit是生成一次提交，git push是把提交推到远程。这只是单人协作最简单的流程，更复杂的分支合并、冲突解决场景，等基础熟练后再慢慢接触也不迟。
5. 常见问题排查与避坑指南
5.1 Permission denied (publickey) 排查思路
这是 SSH 配置过程中出现频率最高的问题。遇到时按顺序排查，绝大多数都能解决：
| 排查步骤 | 操作与原因 |
|---|---|
| 查看本地是否有对应私钥 | 执行ls ~/.ssh，确认存在id_ed25519或id_rsa文件。如果不存在，说明密钥根本没生成成功 |
| 确认私钥已被 ssh-agent 加载 | 执行ssh-add -l，如果输出The agent has no identities.，就需要先用ssh-add添加密钥 |
| 确认 GitHub 上公钥与本地公钥一致 | 重新复制id_ed25519.pub的内容，和 GitHub Settings 里的 SSH keys 对比，注意有没有多余空格或换行 |
| 验证认证是否通过 | 再跑一次ssh -T git@github.com，看报错是否还停留在 publickey 阶段 |
还有一个隐藏问题：如果你在~/.ssh目录下自定义了config文件来管理多台主机，会因为 Host 段的配置写错而走到错误的密钥去认证。你自己电脑上只面对一个 GitHub 时，可以先不用 config 文件，保持默认文件名反而是最简单可靠的方案。
5.2 Host key verification failed 处理
这个问题出现在你首次连接某台 SSH 主机时，或者远程主机公钥发生变化时。Git 会在~/.ssh/known_hosts里记录已见过的远程主机指纹，如果 GitHub 侧的指纹变了，而你本地还保留着旧记录，连接就会被拒绝。
解决方法是先移除旧的记录，再重新连接确认新的指纹：
ssh-keygen -R github.com ssh -T git@github.com每次新环境第一连时提示Are you sure you want to continue connecting (yes/no)?，输入 yes 前先确认域名是你真正要连的 GitHub。这个安全性提示本身是保护机制，别为了省事设置成跳过指纹验证，很容易被中间人攻击盯上。
5.3 多账号多密钥如何配置
很多开发者会同时有个人 GitHub 和公司 GitLab（或企业 GitHub），如果同一台电脑上只有一对密钥，就会出现“公司仓库提交时身份显示成个人账号”的尴尬，或者两个平台抢默认密钥导致认证失败。
我的做法是为不同平台生成独立的密钥对，并在~/.ssh/config中列出它们对应的主机。比如：
Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work这样连接github.com时会自动使用个人密钥，连接公司 GitLab 时使用工作密钥，互不干扰。需要注意的是，config 文件的缩进不是必须的，但每条配置项要写清楚；改完文件后最好执行ssh -T git@github.com和ssh -T git@gitlab.company.com分别验证一次。
5.4 其他高频问题速查
| 现象 | 原因与处理建议 |
|---|---|
| 克隆很慢或卡住 | 先确认网络本身是否正常，判断是网络因素还是仓库太大。大仓库用浅克隆可以缓解首次下载耗时。如果网络环境不稳定，可以换一个时段再试，或用git clone --depth 1拉取最新代码 |
| 每次 push 都要求输入用户名或 Token | 大概率你用的是 HTTPS 克隆链接。可以修改当前仓库远程地址切换为 SSH：git remote set-url origin git@github.com:用户名/仓库名.git |
| 本地提交的邮箱在 GitHub 上没有记录 | 检查git config --global user.email，确认和你 GitHub 账号的邮箱一致 |
| 公司内网限制 SSH 端口 | 尝试切换为 HTTPS + Token 方式，GitHub 支持通过 https 的 443 端口进行 SSH 连接（ssh.github.com），但这个相对进阶，建议直接使用 HTTPS 协议 |
| push 时提示远端领先本地 | 说明远程仓库有新提交，先执行git pull拉取远程改动，解决冲突后再 push |
这里还要特别提醒一个安全习惯：永远不要把私钥文件（如id_ed25519）上传到任何仓库，包括私有仓库。公钥可以公开，私钥泄密等于把你的代码提交权限交了出去。另外，如果你管理的项目部署在公网服务器上，要避免把整个.git目录暴露在 Web 静态目录下，那样别人可以直接通过网址访问.git/config或下载完整源码。曾经流行过一个叫 git 目录泄露的攻击点，原理就是 Web 服务器把.git文件夹当普通静态资源输出。好在正规托管平台不会这么配，但自己用 Nginx 部署静态站点时，记得在配置中屏蔽掉点号开头目录的访问。
实际工作中这种小坑真的满天飞。我有个同事第一次在公司配 SSH，因为 IT 部门把 22 端口墙掉了，他折腾了一个下午，最后切到 HTTPS + Token 半小时完事。所以想清楚自己的环境限制，比盲目“照着教程做”更重要。工具是死的，排查思路是活的。
6. 我的实际使用体会
这套流程我前前后后给不少人讲了很多遍，最大的感触是：SSH 配置这件事，看起来只是几个命令，但背后隐藏的是“版本控制工具、托管平台、传输协议、密钥体系”四层概念。很多初学者栽跟头，通常不是命令执行错误，而是完全不清楚自己正在跟哪一层打交道。
我也经历过一个印象很深的坑：在公司电脑上配置好所有东西，回家在自己的笔记本上继续写同一个项目，结果发现 push 不了，因为新电脑上压根没有生成过密钥。后来我养成了一个习惯，换电脑或重装系统后的第一件事就是检查~/.ssh目录是否存在，如果没有就立刻重新生成密钥并把公钥加到 GitHub。这件事熟练到形成肌肉记忆后，就再也没被认证问题卡过了。
另外想补充一个提升效率的小技巧：把git clone、git status、git log这些高频命令玩熟之后，可以试试配合终端别名使用，比如在 bash 或 zsh 里加一个alias gs='git status'，日常操作能省不少按键。但这都属于锦上添花了，前提还是把 SSH 和克隆这些基本功练扎实。希望这份从配置到克隆的完整记录，能帮你少走我当年走过的弯路。
