企业官网建设流程全解析

1. 为什么要在 Mac 上给 GitHub 配置 SSH keys

先说个我经常被问到的问题：明明 HTTPS 方式也能 push 代码，为什么还要折腾 SSH keys？

这得从 GitHub 的两种认证方式说起。HTTPS 方式每次推送都需要输入用户名和密码，虽然在 Mac 上钥匙串（Keychain）能帮你记住密码，但遇到公司电脑、多台设备、频繁切换账号的场景，HTTPS 的体验就很痛苦了——经常出现密码过期、凭据冲突、甚至莫名弹窗。

SSH keys 的本质是一对非对称加密密钥：私钥留在本机，公钥放到 GitHub 账号里。推送代码时，GitHub 用公钥验证你的身份，本机用私钥完成签名，整个过程不需要输入任何密码，纯靠密钥文件完成认证。

这个方案适合谁？如果你需要：

• 日常频繁 clone、push、pull GitHub 仓库
• 在多台 Mac 上管理同一个 GitHub 账号
• 同时管理多个 GitHub 账号（比如个人号 + 公司号）
• 在 CI/CD 环境里做自动化部署，需要免密访问私有仓库

那我强烈建议你花十分钟把 SSH keys 配好，后面能省下大量重复输入密码的时间。

有一点需要提前说明：SSH 配置属于网络层面的安全设置，只涉及本地密钥文件和 GitHub 账号的对应关系。实际操作时，请确保你的网络环境能正常访问 GitHub 网页端（比如能打开 github.com 的仓库页面），这是后续所有步骤的基础前提。如果连网页都打不开，先解决网络连通性问题再说。

顺便把几个基本概念交代清楚，后面实操时你会频繁遇到它们：

先理解了这些名词，后面操作起来就不会一头雾水。

2. 动手前的准备：检查已有密钥与安装环境

2.1 检查是否已经存在 SSH 密钥

很多 Mac 用户其实以前生成过密钥，但时隔太久自己都忘了。直接生成新密钥会覆盖旧密钥，导致原有配置失效，所以第一步一定是检查。

打开终端（Terminal），输入以下命令：

ls -la ~/.ssh

如果显示No such file or directory，说明从来没配置过 SSH 密钥，可以放心地进入下一节生成新密钥。

如果目录存在，里面会有类似下面的文件：

• id_rsa和id_rsa.pub：老式 RSA 算法的密钥对
• id_ed25519和id_ed25519.pub：新版 Ed25519 算法的密钥对
• config：SSH 配置文件，多账号场景下会用到

看到这些文件，先别急着删除。我的建议是确认一下这套密钥之前是否用过：

ssh -T git@github.com

如果返回Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.，说明这套密钥已经绑定过 GitHub 账号，你可以直接用它，不需要重新生成。

如果返回Permission denied (publickey)，说明密钥存在但没在 GitHub 上配置过对应的公钥，可选用现有密钥追加到 GitHub，也可以重新生成一套新的。

2.2 确认 Git 版本与终端环境

Git 是配置 SSH 的前置依赖，先确认它装好了：

git --version

如果提示command not found，有两个安装途径。一是安装 Xcode Command Line Tools：

xcode-select --install

系统会弹出安装窗口，点击确认后等待几分钟即可。装好后再执行git --version验证。二是在官网下载 Git 安装包，或者用 Homebrew 安装，看个人习惯。安装过程本身不复杂，但 Xcode Command Line Tools 这种方式最省事，因为它是 Apple 官方维护的，后续很多开发工具都会依赖它。

2.3 终端工具的选择与准备

Mac 自带终端 Spotlight 搜索 "Terminal" 就能打开，功能完全够用。如果你想要更好的体验，iTerm2 也是个不错的选择，支持分屏、多标签、自定义快捷键，我个人平时用 iTerm2 更多。不过本文所有命令在两个终端中都通用，不影响操作。

有一点要注意：后续所有命令都必须在终端中执行。如果你习惯用 VS Code 的集成终端，也可以，但要确保当前用户是正常的 macOS 登录用户，而不是 root。直接用 root 生成密钥会带来权限问题，后面 git 命令会报错说无法读取密钥文件。

3. SSH 密钥生成：从命令到原理

3.1 ssh-keygen 参数选择详解

生成密钥的标准命令是：

ssh-keygen -t ed25519 -C "你的邮箱@example.com" -f ~/.ssh/id_ed25519

拆开来看每个参数的含义：

• -t ed25519：指定密钥算法。Ed25519 是目前推荐使用的算法，密钥短、安全性高、生成速度快。相比之下，老式 RSA 算法密钥长度动辄 4096 位，文件大且生成慢。除非你要连接的是不支持 Ed25519 的远古服务器，否则优先选 Ed25519。
• -C "你的邮箱"：标注注释信息，方便识别密钥来源。这里填的是 GitHub 账号绑定的邮箱，不是登录密码，可以放心填写。
• -f ~/.ssh/id_ed25519：指定密钥文件保存路径。-f参数会在后面弹交互式问题时自动填入路径，省去手动输入的麻烦。

执行命令后，终端会逐步询问几个问题。

第一个问题：

Generating public/private ed25519 key pair. Enter file in which to save the key (/Users/你的用户名/.ssh/id_ed25519):

由于我们用了-f参数，这里直接按回车即可，会自动使用默认路径。

第二个问题：

Enter passphrase (empty for no passphrase):

这里的 passphrase 是私钥的额外保护密码。如果设置了，每次使用私钥时都需要输入这个密码；如果不设置，直接按回车跳过，私钥就是裸奔状态。我的建议是：个人使用的 Mac 可以留空，方便日常操作；如果是公司配发的电脑或者有安全合规要求，建议设置一个。设置后可以通过 ssh-agent 配合钥匙串实现免密，后面会详细说。

第三个问题让你再输一遍 passphrase 确认，保持与之前一致即可。

生成完成后，终端会打印出密钥指纹和随机艺术图（一张 ASCII 图案），看到这些字符就说明密钥创建成功了。

3.2 两种密钥算法的选型对比

我知道有些朋友会有疑问：网上教程都让用rsa，为什么这里用ed25519？

确实，早期的大多数 SSH 配置教程都以 RSA 为主，因为 GitHub 对 RSA 的支持最成熟。但 RSA 密钥有一个明显短板：密钥长度越长，安全性越好，但文件体积和 CPU 开销也越大。GitHub 官方文档目前推荐的默认算法就是 Ed25519，它的安全性相当于 RSA 4096 位甚至更高，但密钥长度只有 256 位，生成和验证速度都快得多。

如果你偏好保守方案，用 RSA 也可以，命令改成：

ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"

-b 4096表示密钥长度。GitHub 在 2022 年前后取消了 RSA 密钥最低长度限制，现在 2048 位也能用，但 4096 位更稳妥。

两种方案我都实际用过，结论是：新配置一律用 Ed25519，只有老系统、旧设备等兼容性要求苛刻的场景才考虑 RSA。毕竟这和 HTTPS 协议选择 TLS 1.3 是一个逻辑——能用新标准就用新标准，安全性和效率都更好。

3.3 私钥文件的权限管理

密钥生成后，一个容易被忽略但非常关键的细节是文件权限。

SSH 对密钥文件的权限要求很严格，如果私钥文件的权限过于开放，SSH 会直接拒绝使用它。检查权限：

ls -l ~/.ssh/

正常情况下，私钥文件（id_ed25519）的权限应该是-rw-------，也就是只有当前用户可读可写。公钥文件（id_ed25519.pub）的权限是-rw-r--r--，这个无所谓。

如果权限不对，执行：

chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub

600代表只有属主可读写，644代表属主可读写、其他人可读。之所以公钥可以放宽权限，是因为公钥本身就是要给别人看的，而私钥必须私藏，权限越紧越好。这一步不做，后面测试连通性时会报Permissions 0644 for 'id_ed25519' are too open之类的错误，排查起来很浪费时间。

4. 将公钥添加到 GitHub 账号

4.1 复制公钥内容

公钥文件是.pub后缀的那个，内容是一长串文本，格式类似：

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... 你的邮箱@example.com

复制内容有两种方式。一是直接查看文件内容后手动全选复制：

cat ~/.ssh/id_ed25519.pub

选中输出内容，Cmd + C 复制。二是用 pbcopy 命令直接把文件内容复制到剪贴板：

pbcopy < ~/.ssh/id_ed25519.pub

pbcopy是 macOS 自带的命令，作用是把标准输入的内容写入剪贴板。第二种方式更优雅，不需要手动框选，也不用担心漏掉末尾字符。复制后可以直接在任意地方 Cmd + V 粘贴，验证一下剪贴板里是不是完整的公钥内容。

4.2 GitHub 网页端添加公钥的完整步骤

1. 打开 GitHub 官网并登录账号（确保网络能正常访问 GitHub 页面）。
2. 点击右上角头像，选择Settings。
3. 在左侧菜单栏中找到SSH and GPG keys。
4. 点击绿色按钮New SSH key。
5. 在Title输入框给这个密钥起一个容易识别的名称。我的习惯是写“设备名 + 日期”，比如MacBook Pro 2024-01。这样以后管理多台设备的密钥时，一目了然。
6. 在Key输入框粘贴刚复制的公钥内容（id_ed25519.pub文件里的全部内容）。
7. 点击Add SSH key按钮完成添加。

添加成功后，GitHub 可能会要求输入账号密码确认操作，输入后即可。这个流程我实操过很多次，每个步骤的入口位置可能会随着 GitHub 改版略有变化，但整体路径大差不差。

4.3 验证 SSH 连接是否成功

公钥添加完成后，回到终端测试连接：

ssh -T git@github.com

首次连接时终端会提示：

The authenticity of host 'github.com (IP地址)' can't be established. ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. Are you sure you want to continue connecting (yes/no)?

这是 SSH 在询问你是否信任这台服务器，输入yes确认即可。这里建议认真看一眼指纹串，GitHub 官方文档有对应的指纹记录，可以核对一下，防止中间人攻击。不过日常使用中，大多数人直接回车确认也没问题。

输入yes后，如果看到：

Hi your_username! You've successfully authenticated, but GitHub does not provide shell access.

恭喜你，SSH 认证已经打通。最后一步是把仓库的远程地址从 HTTPS 改成 SSH，这样才能走 SSH 通道。

在本地仓库中执行：

git remote -v

查看当前远程地址。如果开头是https://github.com/...，改成 SSH 格式：

git remote set-url origin git@github.com:你的用户名/仓库名.git

改完后再次执行git remote -v确认，地址应该变成git@github.com:开头。之后执行 push、pull 等操作，都不再需要输入任何凭据。

5. 进阶操作：多账号管理与 ssh-agent 配置

5.1 一台 Mac 管理多个 GitHub 账号的场景

很多开发者的痛点在这里：公司用企业版 GitHub 或 Gitee，个人用的是 github.com，两套账号有时还要同时操作。如果只生成一套密钥，后生成的会覆盖之前的配置，导致其中一个账号失效。

解决办法是为每个账号生成独立的密钥文件，再通过~/.ssh/config文件做路由。假设你有两个账号：

个人账号personal@example.com：密钥文件~/.ssh/id_ed25519_personal公司账号work@example.com：密钥文件~/.ssh/id_ed25519_work

分别生成两套密钥，注意-f参数指定不同文件名：

ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519_personal ssh-keygen -t ed25519 -C "work@example.com" -f ~/.ssh/id_ed25519_work

然后把两个公钥都添加到 GitHub（或对应的代码托管平台）上，标题分别标注清楚。

接下来编辑 SSH 配置文件：

nano ~/.ssh/config

如果没有这个文件，nano会直接创建。写入以下配置：

Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal Host github-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_work

第一段Host github.com表示默认访问 github.com 时使用个人账号的密钥。第二段Host github-work是一个别名，实际连接的服务器还是 github.com，但使用公司账号的密钥。

配套地，克隆仓库时地址也要做区分：

• 个人仓库：git clone git@github.com:用户名/仓库.git
• 公司仓库：git clone git@github-work:公司用户名/仓库.git

注意公司仓库用的是别名github-work，这样 SSH 才会匹配到对应的密钥文件。

5.2 让 ssh-agent 在钥匙串中记住密钥

如果你给私钥设置了 passphrase，那么每次 push 代码时都会提示输入密码，体验很差。解决办法是让 macOS 的钥匙串（Keychain）帮你记住。

在 macOS 上，使用--apple-use-keychain参数将密钥添加到 ssh-agent，并同步存入钥匙串：

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

之后在~/.ssh/config中，为对应 Host 添加以下配置：

Host github.com AddKeysToAgent yes UseKeychain yes IdentityFile ~/.ssh/id_ed25519

UseKeychain yes是 macOS 专属配置，只有装了 Command Line Tools 才能识别这个参数。配置后首次使用时输入一次 passphrase，之后 SSH 会自动从钥匙串读取，实现真正的免密操作。

额外提一个坑：如果你用的是旧版 macOS（比如 10.12 之前的版本），--apple-use-keychain参数可能会报错，需要换成-K参数：

ssh-add -K ~/.ssh/id_ed25519

macOS 新版本虽然兼容-K，但官方已经推荐使用--apple-use-keychain，建议优先用新版写法。

5.3 配置零星注意事项

多账号配置中容易踩的坑有两个。

第一个是权限问题。~/.ssh/config文件的权限也不能太开放。改完配置后最好执行一下：

chmod 600 ~/.ssh/config

否则 SSH 会提示bad permissions并忽略配置文件，导致路由不生效。

第二个是 ssh-agent 的清理。切换账号时，如果 ssh-agent 里缓存了旧密钥，可能选错密钥导致认证失败。可以先清空再重新添加：

ssh-add -D ssh-add --apple-use-keychain ~/.ssh/id_ed25519_personal ssh-add --apple-use-keychain ~/.ssh/id_ed25519_work

-D参数会删除 ssh-agent 中所有已缓存的密钥，相当于重启干净状态。重新添加后，系统会根据config文件自动选择合适的密钥。

6. 常见问题与排查技巧实录

6.1 Permission denied (publickey)

这是最经典的报错，出现概率极高。原因通常是以下几种：

• 公钥没有添加到 GitHub 账号。返回 Git 添加公钥的步骤检查一遍。
• 添加的公钥和本机私钥不匹配。检查~/.ssh/目录下是否有多个私钥文件，确认 GitHub 上添加的是对应公钥。
• SSH 没有使用正确的密钥。多账号场景下，config 文件配置有误，导致选错密钥。

排查命令很有用：

ssh -vT git@github.com

-v参数会输出详细的调试信息，观察输出中Offering public key后面的密钥文件名，就能知道当前用的是哪把私钥。如果是错误的密钥，就会在Authentications that can continue: publickey提示后认证失败。

6.2 修改密钥后仍然提示用户名或密码

如果你刚把 push 方式改成 SSH，终端却仍然弹出 GitHub 的用户名密码输入框，多半是凭据被缓存了。Git 在 macOS 上默认使用 osxkeychain 辅助程序存储 HTTPS 凭据，旧的 HTTPS 地址仍然被记录在钥匙串里。

解决办法是清除缓存凭据：

git credential-osxkeychain erase host=github.com protocol=https

输入后按回车，再按 Ctrl+D 结束输入。之后重新执行git remote -v确认远程地址是 SSH 开头，问题就能解决。

6.3 密钥验证时提示 Host key verification failed

这个报错通常出现在重装系统或换了新设备后，原因是你本机的~/.ssh/known_hosts中记录的 GitHub 服务器指纹和当前不一致。

解决办法是删除 known_hosts 中对应的旧记录：

ssh-keygen -R github.com

然后重新执行ssh -T git@github.com，再次确认指纹信息即可。

6.4 macOS 钥匙串权限弹窗

使用--apple-use-keychain添加密钥后，首次连接时系统会弹出“git 想要访问你的钥匙串”的提示。这属于正常安全机制，填写用户密码并选择“始终允许”即可。如果之前误点了“拒绝”，需要到 系统设置 > 隐私与安全 > 钥匙串访问 中手动授权。

6.5 常见问题速查表

7. 实操总结与我的经验之谈

整套流程走下来，核心操作其实只有四步：生成密钥、添加公钥、测试连接、切换远程地址。但我在帮别人排查问题的过程中发现，很多人恰恰是忽略了一些小细节，导致反复卡壳。

第一，公钥和私钥必须配对使用。有人从别的电脑拷贝了私钥文件，但公钥没有同步到 GitHub，或者 GitHub 上已经存在旧公钥，就会一直认证失败。最简单的验证方式是用ssh-add -l看本机是否已加载私钥，再用ssh -T git@github.com验证。

第二，密钥文件路径别瞎改。默认路径~/.ssh/id_ed25519已经被 SSH 内置为默认查找位置。如果你用-f指定了别的路径，后续每次操作 SSH 都要额外指定密钥路径，很容易出错。非必要不折腾。

第三，macOS 的钥匙串是一个非常好用的功能，但要注意它和 ssh-agent 是两个独立的东西。ssh-agent 负责进程内的密钥缓存，钥匙串负责磁盘上的密码存储。理解了这个区别，遇到“昨天还能免密，今天突然要密码”的情况时，你就知道先查 ssh-agent 状态，而不是去重新配置。

如果在这个配置过程中遇到什么问题，欢迎留言交流，我会把常见问题持续补充到这篇文章里。配置好的 SSH keys，会让你后续和 GitHub 的每一次交互都顺畅很多。