企业官网建设流程全解析

新手第一次用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 git，Fedora/RHEL系用sudo dnf install git，Arch系用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的认证原理用生活中的场景类比很好懂：公钥是一把挂在你家门外的锁，谁都能看到，私钥是你兜里的钥匙，只有你有。你把这把锁交给GitHub，GitHub每次见到你都让你证明一下自己手里有没有配对的钥匙。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):

直接回车用默认路径就行。除非你已经有一把同名的密钥，否则不建议改路径，改了后续配置容易出幺蛾子。接下来会问你是否设置passphrase：

Enter 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_ed25519

Windows用户不用特意设置，但要知道私钥文件位置在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 git@github.com

第一次连接会看到一句类似这样的提示：

The authenticity of host 'github.com (IP地址)' can't be established. Are you sure you want to continue connecting (yes/no/[fingerprint])?

这是SSH在问你信不信任GitHub这台主机，输入yes回车即可。然后如果密钥配置成功，会看到：

Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.

看到这句话就说明SSH链路彻底通了。注意这里的登录用户固定是git，不是你自己的名字。GitHub把所有SSH连接的用户名统一设成git，它真正区分身份靠的是你拿出的那把私钥对应的公钥。很多人第一次看到git@github.com会困惑：我又不叫git，为什么用这个名字登录？理解了它的认证机制就释然了。

如果配置有问题，通常会提示Permission denied (publickey)。这类错误的排查方法，我会在第4章详细拆。

3. 克隆仓库：从远程把代码拿到本地

3.1 HTTPS和SSH两种地址应该怎么选

GitHub每个仓库页面都有绿色的Code按钮，点开后会看到HTTPS和SSH两个选项卡，分别对应两种克隆地址。拿一个公开仓库举例，两种地址长这样：

两种方式能克隆到的仓库内容完全一样，区别只在认证体验。克隆公开仓库时，HTTPS方式甚至不需要登录，直接就能下载。但如果你需要推送代码，用HTTPS就得每次输token，SSH却一次配置终身免密。我个人日常开发一律用SSH地址，HTTPS只留给临时在别的电脑上快速下载某个开源项目这种情况。

这里也顺带说一句，克隆别人的公开仓库用哪种方式都行；克隆私有仓库则必须保证你的GitHub账号有访问权限，否则SSH会收到repository not found的提示。

3.2 git clone 实操流程与克隆后的第一步

选好SSH地址后，复制它，然后在你希望存放项目的目录下打开终端，执行：

git clone git@github.com:用户名/仓库名.git

命令的核心结构就是git clone后面跟仓库地址。Git会自动创建一个以仓库名命名的文件夹，把远程仓库的所有文件、历史记录、分支信息全部下载下来。这个文件夹里除了你在GitHub网页上看到的文件之外，还多了一个隐藏的.git目录，里面存放着完整的版本历史、远程地址、分支指针等全部元数据。理解这一点很重要：Git的克隆不是简单复制文件，而是把整个仓库的完整历史都拉下来了，你在本地已经拥有了一份完整的仓库副本，断网也能查看历史、创建分支、提交代码。

克隆完成后，第一步先进目录：

cd 仓库名

然后看两样东西。第一，确认远程地址信息：

git remote -v

会输出两行fetch和push对应的地址，说明本地和远程已经被正确关联。第二，看当前所在分支和文件状态：

git status git branch -a

git status会显示On branch main之类的内容和当前工作区是否干净；git branch -a会列出本地分支和远程跟踪分支，远程分支通常是以remotes/origin/开头的。

有一个小细节值得新手注意：克隆下来的仓库默认只创建了远程默认分支（通常是main）的本地跟踪分支。远程仓库还有别的分支时，用git branch -a能看到它们，但本地工作区里没有。想切换到某个远程分支开发，直接执行git checkout 分支名或git switch 分支名，Git会自动基于远程分支创建本地分支并建立跟踪关系。

如果你只想下载一个大型仓库的最新代码，不想把全部历史记录都拉下来，可以用浅克隆：

git clone --depth 1 git@github.com:用户名/仓库名.git

--depth 1表示只克隆最新的一个提交，历史记录不下载，速度会快很多。以后需要完整历史时，在仓库目录里执行git fetch --unshallow就能补全。只想要某个特定分支同样有对应写法：

git clone -b 分支名 --single-branch git@github.com:用户名/仓库名.git

这个命令只拉取指定分支，适合那种分支很多、你只需要其中一条线的场景。

如果你想把仓库克隆到指定名字的目录，而不是默认的仓库名目录，直接在地址后面补一个目录名即可：

git clone git@github.com:用户名/仓库名.git 自定义目录名

克隆完成后，进入项目目录，强烈建议先打开README看一下项目说明，再动手改代码。不少新手克隆完第一件事就是写代码，结果连项目怎么启动、依赖怎么装都没看，白白浪费时间。

4. 这些是我在SSH和克隆路上踩过的坑

4.1 高频报错逐一排查

这里列几个我实际使用中遇到最多、也最容易被新手问到的报错，每条都说清解决思路。

第一个是Permission denied (publickey)。这个错误几乎90%的SSH配置问题都长这样。看到它的第一件事不是怀疑网络，而是检查密钥链路。按顺序排查：确认公钥已经添加到GitHub账户；确认你连的地址是git@github.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 git@github.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 Terminal，SSH_AUTH_SOCK环境变量不一致，导致ssh-agent里的密钥没有被新终端读到。第二是Windows系统里OpenSSH Authentication Agent服务没有启动。按下Win+R输入services.msc，找到OpenSSH Authentication Agent，把启动类型改为自动并启动服务，然后在终端执行ssh-add把私钥重新加载一遍。

还有一个新手容易困惑的点是：我的.ssh文件夹里同时有好几把钥匙，GitHub到底用的是哪一把？默认情况下SSH会尝试id_rsa、id_ecdsa、id_ed25519这些默认文件名的密钥。如果你生成密钥时改了文件名，比如id_github、id_gitlab，Git就不会自动识别，必须通过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多花十分钟，但它换来的是以后一年两年的顺畅体验。希望这篇能帮你一次把密钥配好，顺利克隆出你的第一个仓库。