新手第一次用GitHub最容易卡住的场景往往是这个复制了仓库地址在终端敲下git clone结果等来的不是代码下载进度条而是一句冷冰冰的Permission denied (publickey)。我当年也在这个界面卡了半小时后来才发现问题根本不是命令写错而是SSH密钥压根没配好。这篇入门教程想帮你一条路走通装好Git、配好身份信息、把SSH密钥交给GitHub最后顺利把仓库克隆到本地。内容适合完全零基础、第一次接触Git的人也适合一直用HTTPS方式、每次推送都要输密码、早就想切到SSH省事的人。我会尽量把每条命令为什么这么写、背后在干什么讲清楚而不只是丢给你一段可以复制粘贴的代码。1. 环境准备装好Git顺手把身份信息写对1.1 不同系统下的Git安装方式先解决一个最基础的问题你的电脑上到底有没有Git。Winows、macOS、Linux三套系统的安装方式差别很大但装完之后验证方法是一样的。Windows用户我建议直接去git-scm.com下载安装包全程默认选项就可以用但有一个选项值得留意安装过程中让你选择PATH环境变量时务必选“Git from the command line and also from 3rd-party software”。选了这一项Git才会被写进系统PATH之后你在PowerShell、CMD、VS Code终端里都能直接敲git命令而不只是能在Git Bash里用。如果已经装完才发现终端里找不到git可以重新运行安装包修复一次或者在“系统属性-环境变量-Path”里手动把Git的cmd目录加进去。macOS用户最简单的办法是打开终端执行xcode-select --install系统会装好Command Line Tools里面自带Git。也可以用Homebrew执行brew install git这种方式装到的版本通常更新适合对版本有要求的人。Linux用户就看发行版了。Debian/Ubuntu系用sudo apt install gitFedora/RHEL系用sudo dnf install gitArch系用sudo pacman -S git。安装完统一验证一下git --version能输出版本号比如git version 2.39.2就说明装好了。这步都没过的话后面所有操作都无从谈起。1.2 首次安装后必须做的全局配置很多人装完Git就急着去克隆仓库结果提交代码时发现提交记录里的作者信息是空的或者显示成unknown、一堆乱码。原因就是跳过了身份配置这一步。Git在设计上不允许匿名提交每一次commit都必须有作者和邮箱所以在动手前先把这两项设好git config --global user.name 你的名字 git config --global user.email 你的邮箱注意这里填的邮箱最好是你在GitHub账户里验证过的邮箱不是随便编一个。GitHub判断一次提交是不是你产生的靠的就是邮箱和用户名匹配。如果你用一个没在GitHub里登记过的邮箱提交代码虽然能推上去但你的头像不会亮主页上的贡献绿格子也不会涨提交会显示成一个独立的陌生账号后续想找回归属会很麻烦。配置完之后可以检查一下git config --global --list这里会列出所有全局配置项。另外建议把默认分支名也统一一下。GitHub在2020年后把新建仓库的默认分支从master改成了main但本地Git的初始分支名仍然是master两边不一致容易在操作时造成混淆。执行一次git config --global init.defaultBranch main以后在本地用git init创建仓库时默认分支就是main和GitHub保持一致省掉后面手动改名的功夫。还有一个很容易踩的坑是换行符。Windows和Linux/macOS的换行符不一样Windows是CRLF后两者是LF。如果不管Windows用户克隆下来的代码提交时可能把整个文件的换行符全部改一遍Git会认为你改了每一个文件diff刷屏全是噪音。建议Windows用户执行git config --global core.autocrlf true这会让Git在提交时自动把CRLF转成LF检出时再转回CRLF从源头避免这类问题。macOS/Linux用户则保持默认即可。2. SSH密钥让GitHub认识你这台电脑2.1 为什么偏要配置SSH先回答一个很多人困惑的问题我用HTTPS地址克隆仓库输入用户名和密码也能用为什么还要折腾SSH答案是长期体验差太多。HTTPS方式克隆私有仓库或推送代码时每次都要输用户名和密码。现在GitHub早就取消了密码认证密码位置要求填写Personal Access Token也就是一串很长的随机字符。偶尔用一次还好频繁推送代码时每次都复制粘贴token效率很低。SSH则完全不同只需要在你第一次连接时完成密钥配置之后所有clone、push、pull都免密操作不需要输入任何账号信息。SSH的认证原理用生活中的场景类比很好懂公钥是一把挂在你家门外的锁谁都能看到私钥是你兜里的钥匙只有你有。你把这把锁交给GitHubGitHub每次见到你都让你证明一下自己手里有没有配对的钥匙。GitHub手里只有公钥就算公钥被泄露别人没有私钥也进不去你的账户所以公钥可以随便公开私钥必须保密。所有通过SSH传输的数据都是加密的不存在明文裸奔的问题。2.2 生成密钥的具体操作与参数选择确认电脑上已经有Git之后打开终端执行ssh-keygen -t ed25519 -C 你的邮箱这里逐个解释参数。-t指定密钥类型ed25519是当前推荐的选择密钥短、生成快、安全性高而且是现代OpenSSH的默认偏好。如果你的操作系统比较老或者内网服务器SSH版本过低不认ed25519再退回去用ssh-keygen -t rsa -b 4096生成RSA密钥。等于是说不要再纠结选型先试ed25519被环境拒绝再换RSA 4096。-C是注释一般填你的邮箱作用是方便你日后区分这把密钥是干嘛的。这个注释会出现在公钥文件的末尾不填也不影响功能但填上更规范。命令执行后终端会问你保存密钥的文件路径Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):直接回车用默认路径就行。除非你已经有一把同名的密钥否则不建议改路径改了后续配置容易出幺蛾子。接下来会问你是否设置passphraseEnter passphrase (empty for no passphrase):这里我的建议是设置一个哪怕简单一点。passphrase是私钥的额外保护口令就算有人偷走了你的私钥文件没有这个口令也用不了。不设置的话私钥文件泄露等于账号直接沦陷。设置后的代价是每次使用SSH可能都要输一次口令但这个问题可以用后面提到的ssh-agent解决输入一次就能记住一段时间。生成完成后你的用户目录下的.ssh文件夹里会出现两个文件id_ed25519私钥和id_ed25519.pub公钥。注意私钥永远不要发给任何人公钥可以放心给别人看。Linux和macOS用户建议检查一下.ssh目录权限私钥文件权限不能太开放chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519Windows用户不用特意设置但要知道私钥文件位置在C:\Users\你的用户名.ssh\id_ed25519以后换电脑迁移时是复制这个文件和对应的.pub文件。2.3 把公钥添加到GitHub并验证连通性密钥生成之后把公钥内容复制出来。可以执行cat ~/.ssh/id_ed25519.pub输出是一行以ssh-ed25519开头的字符串从ssh-ed25519开始一直到结尾全部复制包括末尾的邮箱注释。然后在浏览器打开GitHub右上角头像 → Settings → SSH and GPG keys → 绿色按钮New SSH key。Title随便填比如“My Laptop”Key里粘贴刚才复制的内容保存。这时候还没完要验证SSH通道是否真的打通了。执行ssh -T gitgithub.com第一次连接会看到一句类似这样的提示The authenticity of host github.com (IP地址) cant be established. Are you sure you want to continue connecting (yes/no/[fingerprint])?这是SSH在问你信不信任GitHub这台主机输入yes回车即可。然后如果密钥配置成功会看到Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.看到这句话就说明SSH链路彻底通了。注意这里的登录用户固定是git不是你自己的名字。GitHub把所有SSH连接的用户名统一设成git它真正区分身份靠的是你拿出的那把私钥对应的公钥。很多人第一次看到gitgithub.com会困惑我又不叫git为什么用这个名字登录理解了它的认证机制就释然了。如果配置有问题通常会提示Permission denied (publickey)。这类错误的排查方法我会在第4章详细拆。3. 克隆仓库从远程把代码拿到本地3.1 HTTPS和SSH两种地址应该怎么选GitHub每个仓库页面都有绿色的Code按钮点开后会看到HTTPS和SSH两个选项卡分别对应两种克隆地址。拿一个公开仓库举例两种地址长这样类型地址格式示例认证方式适用场景HTTPShttps://github.com/用户名/仓库名.git每次操作输入用户名Token临时下载、CI/CD、不方便配密钥的环境SSHgitgithub.com:用户名/仓库名.git密钥认证免密日常开发、频繁推送代码两种方式能克隆到的仓库内容完全一样区别只在认证体验。克隆公开仓库时HTTPS方式甚至不需要登录直接就能下载。但如果你需要推送代码用HTTPS就得每次输tokenSSH却一次配置终身免密。我个人日常开发一律用SSH地址HTTPS只留给临时在别的电脑上快速下载某个开源项目这种情况。这里也顺带说一句克隆别人的公开仓库用哪种方式都行克隆私有仓库则必须保证你的GitHub账号有访问权限否则SSH会收到repository not found的提示。3.2 git clone 实操流程与克隆后的第一步选好SSH地址后复制它然后在你希望存放项目的目录下打开终端执行git clone gitgithub.com:用户名/仓库名.git命令的核心结构就是git clone后面跟仓库地址。Git会自动创建一个以仓库名命名的文件夹把远程仓库的所有文件、历史记录、分支信息全部下载下来。这个文件夹里除了你在GitHub网页上看到的文件之外还多了一个隐藏的.git目录里面存放着完整的版本历史、远程地址、分支指针等全部元数据。理解这一点很重要Git的克隆不是简单复制文件而是把整个仓库的完整历史都拉下来了你在本地已经拥有了一份完整的仓库副本断网也能查看历史、创建分支、提交代码。克隆完成后第一步先进目录cd 仓库名然后看两样东西。第一确认远程地址信息git remote -v会输出两行fetch和push对应的地址说明本地和远程已经被正确关联。第二看当前所在分支和文件状态git status git branch -agit status会显示On branch main之类的内容和当前工作区是否干净git branch -a会列出本地分支和远程跟踪分支远程分支通常是以remotes/origin/开头的。有一个小细节值得新手注意克隆下来的仓库默认只创建了远程默认分支通常是main的本地跟踪分支。远程仓库还有别的分支时用git branch -a能看到它们但本地工作区里没有。想切换到某个远程分支开发直接执行git checkout 分支名或git switch 分支名Git会自动基于远程分支创建本地分支并建立跟踪关系。如果你只想下载一个大型仓库的最新代码不想把全部历史记录都拉下来可以用浅克隆git clone --depth 1 gitgithub.com:用户名/仓库名.git--depth 1表示只克隆最新的一个提交历史记录不下载速度会快很多。以后需要完整历史时在仓库目录里执行git fetch --unshallow就能补全。只想要某个特定分支同样有对应写法git clone -b 分支名 --single-branch gitgithub.com:用户名/仓库名.git这个命令只拉取指定分支适合那种分支很多、你只需要其中一条线的场景。如果你想把仓库克隆到指定名字的目录而不是默认的仓库名目录直接在地址后面补一个目录名即可git clone gitgithub.com:用户名/仓库名.git 自定义目录名克隆完成后进入项目目录强烈建议先打开README看一下项目说明再动手改代码。不少新手克隆完第一件事就是写代码结果连项目怎么启动、依赖怎么装都没看白白浪费时间。4. 这些是我在SSH和克隆路上踩过的坑4.1 高频报错逐一排查这里列几个我实际使用中遇到最多、也最容易被新手问到的报错每条都说清解决思路。第一个是Permission denied (publickey)。这个错误几乎90%的SSH配置问题都长这样。看到它的第一件事不是怀疑网络而是检查密钥链路。按顺序排查确认公钥已经添加到GitHub账户确认你连的地址是gitgithub.com开头的SSH地址而不是https开头的确认本机SSH用的是你生成的那把密钥而不是系统里其他密钥如果设置了passphrase确认ssh-agent有没有启动并加载私钥。很多情况下是公钥加了但Git Bash和PowerShell读取的密钥路径不一致导致。ssh-add -l这个命令会列出当前ssh-agent加载的密钥指纹。如果输出The agent has no identities说明私钥没加载执行ssh-add ~/.ssh/id_ed25519把私钥加进去再试。第二个是Host key verification failed。这个报错出现在你重装系统、或者曾经清除过known_hosts之后。SSH第一次连接时会询问是否信任主机你的回答会记录在~/.ssh/known_hosts文件里。一旦GitHub服务器的密钥指纹发生变化本机还保留旧记录时就会报这个错。解决办法很简单把旧的github.com条目删掉ssh-keygen -R github.com然后重新执行ssh -T gitgithub.com再次输入yes确认新指纹即可。第三个是repository not found。这个报错最容易误导人因为字面意思是“仓库不存在”但实际可能是三种原因URL里的用户名或仓库名拼错了仓库是私有的而你的账号没有被授权或者你正在用另一个SSH密钥对应的是另一个GitHub账号而那个账号没有这个仓库的权限。多账号用户尤其容易撞上最后一种情况。第四个是克隆大仓库中途失败报错里带着RPC failed、Connection was reset这类的字样。这类原因比较复杂可能是网络波动可能是仓库本身太大导致超时。最直接的解决方法是重新执行一次克隆命令Git会断点续传式的继续。也可以尝试调整Git的HTTP缓冲区大小git config --global http.postBuffer 524288000这个参数把缓冲区调到500MB能解决一部分因为HTTP协议传输慢导致的报错但它不是万能的。如果反复在同一位置失败更值得怀疑的是仓库里有一些体积过大的二进制文件。这种情况建议改用浅克隆拉取最新代码应急。4.2 免密失效、多账号管理与SSH配置文件SSH虽然号称免密但有些时候你会发现明明配置好了突然又要输密码。常见原因有两个。第一是你换了终端工具比如之前用Git Bash现在换到了Windows TerminalSSH_AUTH_SOCK环境变量不一致导致ssh-agent里的密钥没有被新终端读到。第二是Windows系统里OpenSSH Authentication Agent服务没有启动。按下WinR输入services.msc找到OpenSSH Authentication Agent把启动类型改为自动并启动服务然后在终端执行ssh-add把私钥重新加载一遍。还有一个新手容易困惑的点是我的.ssh文件夹里同时有好几把钥匙GitHub到底用的是哪一把默认情况下SSH会尝试id_rsa、id_ecdsa、id_ed25519这些默认文件名的密钥。如果你生成密钥时改了文件名比如id_github、id_gitlabGit就不会自动识别必须通过config文件显式指定。如果你同时使用GitHub个人账号和公司GitLab强烈建议建一个~/.ssh/config文件来区分。文件内容可以参考这样Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_gitlab每个Host对应一个别名SSH会根据你连接的域名自动匹配对应的私钥。这样不同平台用不同密钥互不干扰。这里有个教训不要在config里写一堆IdentityFile让SSH挨个尝试也不要用引号把路径包起来更不要把相同配置堆叠成好几份GitHub对这种情况会直接拒绝认证。每个Host下面只写一个明确的IdentityFile干净利落。4.3 换电脑和密钥迁移换电脑后想把SSH免密配置迁过去只需要复制两个文件私钥id_ed25519和公钥id_ed25519.pub。把它们放到新电脑的~/.ssh目录下然后重新配置权限Linux/macOS上记得chmod 600私钥再ssh-add加载一遍即可。known_hosts文件不需要复制它只是记录了你曾经信任过的主机指纹新电脑重新验证一次就行。公钥文件丢失了问题不大因为GitHub后台还保留着你的公钥但私钥文件是真的无法找回的。私钥丢失时正确做法是重新生成一对新密钥再把新公钥添加到GitHub账户替换掉旧公钥。老密钥没有密码保护又泄露给别人的话就像把你家钥匙掉在街上该换锁就得换锁不要心存侥幸。最后再分享一个我坚持了很久的小习惯每次在GitHub上新建仓库我都会顺手勾选初始化README和.gitignore这样克隆下来第一眼就能看到项目说明也不用担心把本地的临时文件、日志文件误提交上去。第一次配置SSH确实比HTTPS多花十分钟但它换来的是以后一年两年的顺畅体验。希望这篇能帮你一次把密钥配好顺利克隆出你的第一个仓库。