macOS 首次使用 Git 远程操作失败，需配置 SSH 密钥：一、检查并安装 Git，配置 user.name 和 user.email；二、生成 Ed25519 类型 SSH 密钥；三、启动 ssh-agent 并添加私钥至钥匙串；四、复制公钥添加到 GitHub/GitLab；五、执行 ssh -T git@github.com 测试连接。
如果您在 macOS 系统中首次使用 Git 进行远程仓库操作（如 clone、push、pull），但提示权限拒绝或认证失败，则很可能是尚未配置 SSH 密钥并将其添加至代码托管平台（如 GitHub、GitLab）。以下是为 macOS 配置 Git 环境并生成、添加 SSH Key 的具体步骤：
一、检查是否已安装 Git 并配置基础用户信息
Git 命令行工具需预先安装，且全局用户身份信息（用户名与邮箱）必须设置，否则部分远程操作会报错或提交记录无法正确关联。
1、打开终端（Terminal），输入 git --version 检查 Git 是否已安装；若返回版本号（如 git version 2.39.2），则已安装；若提示 command not found，请先通过 Homebrew 或官网下载安装 Git。
2、执行 git config --global user.name "YourName" 设置全局用户名，将 YourName 替换为您的实际用户名。
3、执行 git config --global user.email "youremail@example.com" 设置全局邮箱，该邮箱需与代码托管平台注册邮箱一致。
4、运行 git config --list 确认 user.name 和 user.email 已成功写入全局配置。
二、生成新的 SSH Key（Ed25519 类型）
推荐使用 Ed25519 算法生成密钥，因其安全性更高、密钥更短；若系统 OpenSSL 版本过低不支持，可回退至 RSA 方式。
1、在终端中执行 ssh-keygen -t ed25519 -C "youremail@example.com"，其中 -C 后的邮箱须与 git config 中设置的一致。
2、按回车键接受默认保存路径（~/.ssh/id_ed25519）；若路径被占用或需自定义，可手动输入新路径（如 ~/.ssh/github_ed25519）。
3、输入并确认一个安全的密码短语（passphrase）；该密码用于本地密钥加密，非必须但强烈建议设置。
4、执行 ls -al ~/.ssh 查看是否生成了 id_ed25519（私钥）和 id_ed25519.pub（公钥）两个文件。
三、启动 ssh-agent 并将私钥添加进管理
ssh-agent 是一个后台程序，用于缓存解密后的私钥，避免每次 Git 操作重复输入密码短语。
1、执行 eval "$(ssh-agent -s)" 启动 ssh-agent 并设置环境变量。
2、运行 ssh-add --apple-use-keychain ~/.ssh/id_ed25519 将私钥添加至 agent 并持久化存储到 macOS 钥匙串（仅限 macOS Monterey 及更新系统）；若为旧版系统（如 Catalina），请改用 ssh-add -K ~/.ssh/id_ed25519。
3、输入此前设置的密码短语完成添加；成功后终端将显示 Identity added。
4、执行 ssh-add -l 列出当前已加载的密钥指纹，确认 id_ed25519 已在列表中。
四、将公钥内容复制到剪贴板并添加至远程平台
公钥（.pub 文件）需完整粘贴至 GitHub/GitLab 等平台的 SSH Keys 设置页，服务端凭此验证客户端身份。
1、运行 pbcopy 将公钥内容复制到系统剪贴板。
2、访问 GitHub 网站 → 点击右上角头像 → Settings → SSH and GPG keys → New SSH key。
3、Title 栏填写易识别名称（如 “MacBook Pro – Ed25519”）；Key type 选择 Authentication key（GitHub 新版界面）；在 Key 栏粘贴刚刚复制的内容。
4、点击 Add SSH key 完成提交；页面将显示绿色提示条确认添加成功。
五、测试 SSH 连接有效性
验证密钥是否被远程平台正确识别，以及本地 SSH 配置是否生效，是确保后续 Git 操作免密通行的关键环节。
1、在终端中执行 ssh -T git@github.com（若使用 GitLab，请替换为 git@gitlab.com）。
2、首次连接时，终端将显示服务器指纹并提示是否继续；输入 yes 并回车。
3、若此前设置了密码短语，此时将弹出钥匙串访问窗口或命令行提示，输入该密码完成认证。
4、成功时终端输出类似 Hi username! You've successfully authenticated... 的欢迎信息，且末尾无错误提示。
