macOS SSH 密钥配置全流程：从生成到 GitHub 添加的 5 个关键步骤与排错

张

张建站

2026/7/7 23:35:14

10分钟阅读

macOS SSH 密钥配置全流程从生成到 GitHub 添加的 5 个关键步骤与排错对于 macOS 开发者来说配置 SSH 密钥连接 GitHub 是日常开发中必不可少的一环。然而即使是经验丰富的开发者也可能会遇到Permission denied (publickey)这样的错误提示。本文将带你从零开始通过五个关键步骤完成 SSH 密钥的完整配置流程并提供详细的排错指南确保你一次性配置成功。1. 准备工作与环境检查在开始生成 SSH 密钥之前我们需要确保环境已经准备就绪。首先打开终端Terminal可以通过 Spotlight 搜索Command Space输入 Terminal 快速启动。检查你的 macOS 是否已经安装了 Git 和 SSHgit --version ssh -V如果尚未安装 Git可以通过 Homebrew 安装brew install git接下来检查你的用户目录下是否已经存在.ssh文件夹ls -la ~/.ssh如果该目录不存在可以使用以下命令创建mkdir -p ~/.ssh chmod 700 ~/.ssh注意.ssh目录的权限必须设置为 700这是 SSH 协议的安全要求。2. 生成 SSH 密钥对现在我们可以开始生成 SSH 密钥对。GitHub 目前推荐使用 Ed25519 算法它比传统的 RSA 更安全、更高效ssh-keygen -t ed25519 -C your_emailexample.com如果你使用的系统较旧不支持 Ed25519可以改用 RSAssh-keygen -t rsa -b 4096 -C your_emailexample.com执行命令后你会看到以下提示Generating public/private ed25519 key pair. Enter file in which to save the key (/Users/you/.ssh/id_ed25519):你可以直接按回车使用默认路径或者输入自定义路径。接下来会询问是否设置密码Enter passphrase (empty for no passphrase):设置密码会增加安全性但每次使用密钥时都需要输入。对于开发环境你可以选择不设置密码直接回车两次。成功生成密钥后你会看到类似这样的输出Your identification has been saved in /Users/you/.ssh/id_ed25519 Your public key has been saved in /Users/you/.ssh/id_ed25519.pub The key fingerprint is: SHA256:jX3j5k3l5m6n7o8p9q0r1s2t3u4v5w6x7y8z9 your_emailexample.com The keys randomart image is: --[ED25519 256]-- | .oo | | o o.o . | | . o o | | . o | | S . | | | | . . | | E | | .. | ----[SHA256]-----3. 配置 SSH Agent 和 config 文件为了让 SSH 密钥更方便地使用我们需要配置 SSH Agent 来管理密钥。首先启动 SSH Agenteval $(ssh-agent -s)然后添加你的私钥到 SSH Agentssh-add --apple-use-keychain ~/.ssh/id_ed25519提示如果你使用的是 macOS Monterey (12.0) 之前的版本需要使用-K参数代替--apple-use-keychain。接下来我们配置 SSH 的 config 文件让系统自动管理密钥touch ~/.ssh/config open ~/.ssh/config在打开的配置文件中添加以下内容Host github.com AddKeysToAgent yes UseKeychain yes IdentityFile ~/.ssh/id_ed25519如果你的密钥不是默认路径或名称需要相应修改IdentityFile的值。4. 将公钥添加到 GitHub 账户现在我们需要将公钥添加到 GitHub 账户。首先复制公钥内容pbcopy ~/.ssh/id_ed25519.pub如果pbcopy不可用你可以直接打开公钥文件查看内容cat ~/.ssh/id_ed25519.pub然后手动复制输出内容。公钥内容通常如下ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJl3j5k3l5m6n7o8p9q0r1s2t3u4v5w6x7y8z9 your_emailexample.com登录 GitHub按照以下步骤添加公钥点击右上角头像选择 Settings在左侧边栏选择 SSH and GPG keys点击 New SSH key在 Title 字段输入一个描述性名称如 My MacBook Pro在 Key 字段粘贴你复制的公钥内容点击 Add SSH key 完成添加5. 测试连接与常见问题排查完成上述步骤后我们可以测试 SSH 连接是否正常工作ssh -T gitgithub.com如果一切正常你会看到类似这样的欢迎信息Hi username! Youve successfully authenticated, but GitHub does not provide shell access.常见问题排查问题1Permission denied (publickey)如果看到这个错误可以按照以下步骤排查确认 SSH 密钥已添加到 SSH Agentssh-add -l如果没有列出你的密钥使用ssh-add命令添加。检查 GitHub 上的公钥是否匹配diff (ssh-keygen -lf ~/.ssh/id_ed25519.pub) (ssh-keygen -lf (curl -s https://github.com/username.keys))将username替换为你的 GitHub 用户名。问题2SourceTree 无限转圈如果在 SourceTree 中遇到连接问题确保 SourceTree 使用的是系统自带的 SSH而不是内置的打开 SourceTree 偏好设置选择 General 标签在 SSH Client 选择 Use system SSH重启 SourceTree 并重新克隆仓库问题3ssh-agent 未自动启动如果每次打开新终端都需要手动启动 ssh-agent可以将以下内容添加到你的 shell 配置文件如~/.zshrc或~/.bashrcif [ -z $SSH_AUTH_SOCK ]; then eval $(ssh-agent -s) ssh-add --apple-use-keychain ~/.ssh/id_ed25519 fi高级配置与最佳实践多账户管理如果你需要在同一台电脑上使用多个 GitHub 账户可以这样配置为每个账户生成独立的密钥对ssh-keygen -t ed25519 -C workexample.com -f ~/.ssh/id_ed25519_work修改 SSH config 文件# 个人账户 Host github.com-personal HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal # 工作账户 Host github.com-work HostName github.com User git IdentityFile ~/.ssh/id_25519_work克隆仓库时使用对应的主机别名git clone gitgithub.com-work:company/repo.git密钥安全最佳实践定期轮换密钥建议每6-12个月更换一次 SSH 密钥使用强密码如果设置了密钥密码确保它是强密码限制密钥使用在 GitHub 上可以为密钥添加使用限制审计密钥定期检查 GitHub 账户中的已授权密钥# 查看本地所有授权密钥 ssh-add -L # 查看 GitHub 上的授权密钥 curl -s https://github.com/username.keys自动化验证脚本为了快速验证 SSH 配置是否正确可以使用以下脚本#!/bin/bash echo SSH 配置验证 echo 1. 检查 SSH 密钥文件... ls -la ~/.ssh/id_* echo -e \n2. 检查 SSH Agent... ssh-add -l || echo SSH Agent 中没有密钥 echo -e \n3. 测试 GitHub 连接... ssh -T gitgithub.com echo -e \n4. 检查 config 文件... cat ~/.ssh/config 2/dev/null || echo 没有找到 config 文件 echo -e \n 验证完成将上述内容保存为check_ssh.sh然后赋予执行权限chmod x check_ssh.sh ./check_ssh.sh密钥备份与迁移当你更换电脑或需要备份密钥时可以按照以下步骤操作备份.ssh文件夹cp -r ~/.ssh ~/ssh_backup在新电脑上恢复mkdir -p ~/.ssh cp -r ~/ssh_backup/* ~/.ssh/ chmod 700 ~/.ssh chmod 600 ~/.ssh/*重新添加到 SSH Agenteval $(ssh-agent -s) ssh-add --apple-use-keychain ~/.ssh/id_ed25519重要提示私钥文件 (id_ed25519) 等同于密码必须妥善保管不要通过不安全的渠道传输。

GRUB 2.12 双模式安装：单U盘部署Arch Linux的3个关键配置与排错

GRUB 2.12 双模式安装：单U盘部署Arch Linux的3个关键配置与排错 1. 理解双模式引导的核心机制在移动介质上同时支持UEFI和BIOS引导并非简单的命令叠加，而是需要对GRUB工作原理有深入理解。现代GRUB 2.12版本通过模块化设计实现了这种兼容性&#xff0c…...

2026/7/7 23:34:06 阅读更多 →

CPT Markets：把运营连贯性做扎实，注重效率的使用者更容易感受到的维度

对多数外汇相关用户来说，判断平台并不需要复杂术语，关键在于信息能否被快速理解、关键提示是否容易找到、服务体验是否稳定一致。以CPT Markets为例，这里聚焦这些更贴近实际使用的亮点与细节。在外汇相关服务中，读者最在意的通常是…...

2026/7/7 23:33:18 阅读更多 →

Ghost 11.5.1 系统还原避坑：3个关键步骤避免数据覆盖与引导失败

Ghost 11.5.1 系统还原避坑指南：3个关键步骤避免数据覆盖与引导失败当系统崩溃或需要迁移时，Ghost 11.5.1 仍然是许多技术用户首选的系统备份还原工具。但看似简单的操作背后，隐藏着可能导致数据永久丢失或系统无法启动的陷阱。本文将深入解析…...

2026/7/7 23:27:16 阅读更多 →

6个月转型AI工程师：实战路径与核心技能

1. 项目概述：6个月转型AI工程师的可行性路径在2023年大模型技术爆发的背景下，AI工程师岗位需求同比增长217%（LinkedIn数据）。不同于传统算法工程师需要3-5年培养周期，现代AI工程师更侧重工程化落地能力。我在硅谷科技公…...

2026/7/7 18:08:05 阅读更多 →

Python通达信数据读取终极指南：告别复杂解析，开启量化分析新篇章

Python通达信数据读取终极指南：告别复杂解析，开启量化分析新篇章【免费下载链接】mootdx 通达信数据读取的一个简便使用封装项目地址: https://gitcode.com/GitHub_Trending/mo/mootdx 你是否曾为获取高质量股票数据而烦恼？是否在复…...

2026/7/7 5:07:29 阅读更多 →

5分钟掌握抖音内容永久保存：免费工具助你轻松下载视频与直播

5分钟掌握抖音内容永久保存：免费工具助你轻松下载视频与直播【免费下载链接】douyin-downloader A practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fallback…...

2026/7/7 14:42:45 阅读更多 →