macOS 下配置 SSH 密钥，实现全应用 GitHub 完美同步

macOS 下配置 SSH 密钥，实现全应用 GitHub 完美同步

本文主要由 AI 总结写作，但已经过验证

这是我在 MacBook 上发布的第一篇文章！

目录

## 前言

你是否也曾在 macOS 上，为配置 Git 和 GitHub 的 SSH 连接而烦恼？明明在终端（Terminal）里一切正常，可到了像 Obsidian、VS Code 这样的图形化（GUI）应用程序里，却总是弹出 Permission denied (publickey) 的错误？

本文将带你从零开始，一步步在 macOS 上配置一个安全、高效且一劳永逸的 SSH 环境。最终目标是让你的 Obsidian Git 插件（以及其他任何程序）都能像在终端里一样，无需反复输入密码，流畅地与远程 GitHub 仓库同步。

这篇教程不仅仅是命令的堆砌，更会解释每一步背后的“为什么”，让你彻底告别这个困扰。

核心步骤概览

  1. 生成全新的 SSH 密钥对：创建你的数字身份。
  2. 将公钥添加到 GitHub：在 GitHub 上注册你的身份。
  3. 配置 SSH Agent 和钥匙串：让 macOS 记住你的密码，实现免密操作。
  4. 创建并配置 ~/.ssh/config 文件：这是解决 GUI 应用权限问题的“终极武器”。
  5. 附：在本地项目（如 Obsidian Vault）中关联远程仓库：完成最后的链接。

第一步：生成你的 SSH 密钥对

SSH 密钥对由一个私钥 (private key) 和一个公钥 (public key) 组成。私钥存放在你的电脑上，绝对不能泄露；公钥则可以安全地分享给 GitHub 这样的服务，用来验证你的身份。

  1. 打开 终端 (Terminal) 应用程序。

  2. 运行以下命令来生成一个新的 ed25519 密钥对（这是目前推荐的算法，比传统的 RSA 更安全高效）。记得将 your_email@example.com 替换成你自己的 GitHub 邮箱地址。

    1
    ssh-keygen -t ed25519 -C "your_email@example.com"

  3. 终端会询问你几个问题：

    • “Enter a file in which to save the key…”：直接按 回车 (Enter) 键，使用默认路径 (~/.ssh/id_ed25519)。
    • “Enter passphrase…”：强烈建议设置一个密码！ 这个密码是用来保护你的私钥文件的。即使你的电脑文件被盗，没有这个密码，别人也无法使用你的私钥。输入一个你能记住的、健壮的密码，然后按回车。
    • “Enter same passphrase again:”：再次输入密码确认。

    完成后，你会在 ~/.ssh/ 目录下看到两个新文件：id_ed25519 (私钥) 和 id_ed25519.pub (公钥)。

第二步：将 SSH 公钥添加到 GitHub

现在，你需要告诉 GitHub 你的公钥是什么，以便它能在你推送代码时认出你。

  1. 在终端运行以下命令，将你的公钥内容复制到剪贴板：

    1
    pbcopy < ~/.ssh/id_ed25519.pub

  2. 登录你的 GitHub 账户。

  3. 点击右上角的头像，选择 Settings。

  4. 在左侧菜单中，点击 SSH and GPG keys。

  5. 点击绿色的 New SSH key 按钮。

  6. 在 Title 栏里，给这个密钥起一个你能识别的名字（例如 “MacBook Pro M2”）。

  7. 在 Key 文本框里，粘贴 (Command + V) 你刚刚复制的公钥内容。

  8. 点击 Add SSH key。

第三步：配置 SSH Agent 和 macOS 钥匙串

这一步是实现“免密”操作的关键。我们将使用 ssh-agent 来管理密钥，并让它将你输入的密码安全地存储在 macOS 的钥匙串 (Keychain) 中。

  1. 首先，确保 ssh-agent 正在后台运行（在现代 macOS 上通常是自动的）：

    1
    eval "$(ssh-agent -s)"

  2. 将你的新 SSH 私钥添加到 ssh-agent，并告诉它使用系统钥匙串来存储密码。

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

  3. 此时，终端会要求你输入之前为密钥设置的密码 (passphrase)。正确输入后，你应该会看到 Identity added: 的提示。

    得益于 --apple-use-keychain 这个神奇的参数，以后每次你登录 Mac，系统都会自动从钥匙串中读取密码并加载到 ssh-agent，一劳永逸！

第四步：创建 config 文件 (解决 GUI 应用问题的核心)

为什么在终端里 git push 一切正常，但在 Obsidian 等 GUI 应用里却不行？因为 GUI 应用启动时继承的环境变量，和你在终端里交互式的环境可能不同，导致它找不到 ssh-agent。

~/.ssh/config 文件就是解决这个问题的“终极武器”。它像一个全局的“SSH 使用说明书”，告诉系统上任何程序（无论终端还是 GUI）如何正确地使用 SSH。

  1. 在终端中，运行以下命令来创建（如果尚不存在）并打开这个配置文件：

    1
    2
    3
    4
    5
    # 如果文件不存在，则创建它
    touch ~/.ssh/config

    # 使用默认文本编辑器打开它
    open -e ~/.ssh/config

  2. 一个文本编辑窗口会弹出。将以下配置内容完整地复制粘贴进去：

    1
    2
    3
    4
    Host *
      AddKeysToAgent yes
      UseKeychain yes
      IdentityFile ~/.ssh/id_ed25519

    请注意：

    • Host * 表示这个规则对所有 SSH 连接生效。
    • UseKeychain yes 再次强调了使用钥匙串，对 GUI 应用特别重要。
    • IdentityFile ~/.ssh/id_ed25519 明确指定了默认使用的私钥。如果你的私钥文件名是 id_rsa，请务必修改这一行。

  3. 保存文件 (Command + S) 并关闭文本编辑器。

至此，你的 SSH 环境已经配置得非常完善了！最好重启一次电脑，让所有配置在系统层面完全生效。

附录：链接本地项目到 GitHub

现在，我们以一个 Obsidian Vault 为例，演示如何将一个本地文件夹与远程 GitHub 仓库链接起来。

假设：

  • 你的本地 Obsidian Vault 路径是 ~/Documents/MyVault。
  • 你的远程 GitHub 仓库地址是 git@github.com:your-username/your-repo.git。

  1. 在终端里进入你的 Vault 根目录：

    1
    cd ~/Documents/MyVault

  2. 初始化本地 Git 仓库：

    1
    git init

  3. 关联远程仓库：

    1
    git remote add origin git@github.com:your-username/your-repo.git

  4. 拉取远程仓库的内容（比如 .gitignore 文件）并与本地合并。--allow-unrelated-histories 选项用于处理两个没有共同历史的仓库合并。

    1
    git pull origin main --allow-unrelated-histories

    (注：如果你的主分支是 master，请将 main 替换为 master)

  5. 添加、提交并推送你的本地文件：

    1
    2
    3
    4
    5
    6
    7
    8
    # 将所有未被忽略的文件添加到暂存区
    git add .

    # 提交你的更改
    git commit -m "Initial commit from local vault"

    # 推送到 GitHub
    git push -u origin main

现在，打开你的 Obsidian，进入设置 -> 第三方插件 -> Obsidian Git，点击 Pull 和 Push 按钮，你会发现一切都如丝般顺滑，再也不会有 Permission denied 的错误了！

技术
#git #技术 #macOS
macOS 下配置 SSH 密钥，实现全应用 GitHub 完美同步
https://idontwannago.cn/posts/60387/
作者
idontwannagoo
发布于
2025年10月17日
许可协议