Git

macOS SSH Key 建立與 GitHub 設定

使用 macOS 建立 SSH Key 並設定 GitHub 帳號，同時設定多個身份方便在不同專案中使用。

更新於 2026-10-20發布於 2026-10-20閱讀時間 8 分鐘

前言

其實這篇文章是自己需要兩組 SSH Key 給分別不同的 GitHub 帳號使用，但因為每次設定完成後，腦袋就會很自然地給它遺忘，導致每次需要設定時，就需要再次查找相關文章後做設定，因為近期也碰到相關問題（已經不是第一次），所以就順手紀錄整個設定流程，以及 RSA 與 Ed25519 的差別。

至於，為什麼需要設定兩組 SSH Key? 因為需要同時使用個人專案及公司專案的情況下，必須讓電腦可以連上兩個不同的 GitHub 做 push or clone 等操作。除非，使用兩個不同的硬體直接去做切換，那麼就不需要設定兩組了，但作者我是非常節儉的，所以只有一台硬體設備。再來，會因為在專案的角色不同去設定 git config username or email 資訊，以下也都會帶入講解，請接續往下看閱讀。

先理解 SSH Key

SSH（Secure Shell）是一種安全連線協定。使用 SSH Key 連線 GitHub 時，主要透過公鑰／私鑰進行身分驗證。

名稱	用途	是否可以分享
私鑰（Private Key）	保存在自己的 Mac，用來證明身分	絕對不要分享
公鑰（Public Key，`.pub`）	登記到 GitHub 或伺服器，供驗證使用	可以公開
SSH Agent	管理已載入的私鑰，協助 SSH 驗證	—
`~/.ssh/config`	設定連線主機、別名及要使用的私鑰	內容可能包含敏感環境資訊，分享前應檢查
`~/.ssh/known_hosts`	記錄已驗證的遠端 SSH 主機金鑰	不等於自己的 SSH 公鑰

RSA 與 Ed25519 的差別

這兩種是不同的密碼學演算法，不是兩種文字編碼。

比較	RSA	Ed25519
常見金鑰長度	3072／4096 bits	256 bits
主要用途（SSH Key）	數位簽章驗證	數位簽章驗證
金鑰檔案	通常較大	通常較小
新建 SSH Key 建議	需支援舊系統時可考慮	通常優先使用

檢查 Mac 已有的 SSH Key

ls -al ~/.ssh

例如目前已有：

~/.ssh/
├── config
├── id_work          # 既有私鑰
├── id_work.pub      # 既有公鑰
└── known_hosts

查看現有金鑰的演算法和指紋：

ssh-keygen -lf ~/.ssh/id_work.pub

輸出末尾可能顯示 (ED25519) 或 (RSA)。

重點：已存在的 id_work 不必重新建立；以下示範新增 id_personal，不會主動修改 id_work。

建立新的 Ed25519 SSH Key

先確認目標名稱尚未使用：

ls -l ~/.ssh/id_personal*

若顯示找不到檔案，通常表示尚未有這組金鑰；如果已存在，請換另一個名稱，不要覆蓋。

建立：

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_personal

參數	說明
`ssh-keygen`	建立 SSH 金鑰的指令
`-t ed25519`	指定演算法
`-C "..."`	金鑰註解（通常是 Email，不是帳號綁定機制）
`-f ~/.ssh/id_personal`	指定輸出路徑與檔案名稱

接著會看到：

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

建議設定 Passphrase（私鑰保護密碼），避免私鑰檔案外洩後被直接使用。輸入時 Terminal 不會顯示字元，屬正常現象。

建立完成後新增：

~/.ssh/
├── id_work
├── id_work.pub
├── id_personal       # 新私鑰：請妥善保管
├── id_personal.pub   # 新公鑰：可以上傳到 GitHub
└── config

將 SSH Key 加入 macOS SSH Agent

macOS 通常已有 SSH Agent，可先查看目前載入的金鑰：

ssh-add -l

如果顯示 The agent has no identities.，只是代表目前沒有載入金鑰，不代表 ~/.ssh 沒有金鑰。

如果新金鑰有設定 Passphrase，建議執行：

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

此選項可將 Passphrase 儲存於 macOS Keychain。

如果沒有設定 Passphrase：

ssh-add ~/.ssh/id_personal

再次確認：

ssh-add -l

如果 SSH Agent 尚未執行，才視需要執行 eval "$(ssh-agent -s)"。一般 macOS 使用情境不必每次手動啟動。

管理多組金鑰

先查看原有設定，不要直接覆蓋：

cat ~/.ssh/config

開啟編輯：

nano ~/.ssh/config

在原本內容後面新增以下設定：

# 個人 GitHub：使用新建立的 SSH Key
Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_personal
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes

如果沒有設定 Passphrase，UseKeychain yes 可以省略。

設定	用途
`Host github-personal`	自訂的連線別名
`HostName github.com`	實際連線的 GitHub 主機
`User git`	GitHub SSH 使用的帳號名稱（固定為 `git`）
`IdentityFile`	指定要使用哪個私鑰
`IdentitiesOnly yes`	限制此連線使用設定的身分金鑰，避免 Agent 中的其他金鑰干擾
`AddKeysToAgent yes`	協助將金鑰加入 Agent
`UseKeychain yes`	macOS 可從 Keychain 取得 Passphrase

在 nano 中：按 Control + O 儲存、Enter 確認、Control + X 離開。

使用情境：

github-personal → 使用 id_personal。
原本的 github.com → 繼續依既有 config 設定運作；不要為了新增帳號而刪除既有設定。

若只有一個 GitHub 帳號，也可以只使用一把 SSH Key；多組金鑰不是必需的。

把 SSH 公鑰加到 GitHub

複製公鑰至 Mac 剪貼簿：

pbcopy < ~/.ssh/id_personal.pub

接著到 GitHub：

https://github.com/settings/keys

進入 Settings → SSH and GPG keys。
點選 New SSH key。
Title 輸入易辨識名稱，例如 MacBook Personal。
Key type 選擇 Authentication Key。
在 Key 欄位貼上剛才複製的 .pub 內容。
點選 Add SSH key。

安全提醒：不要複製或上傳 ~/.ssh/id_personal（沒有 .pub 的私鑰）。

測試 GitHub SSH 連線

由於設定了 github-personal 別名，測試指令是：

ssh -T git@github-personal

驗證成功會看到類似：

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

GitHub 不提供互動式 Shell，所以成功訊息中的 does not provide shell access 不是錯誤。

使用指定的金鑰 Clone／操作 Git 專案

因為 github-personal 是你在 SSH Config 定義的別名，Clone 時應這樣寫：

git clone git@github-personal:USERNAME/REPOSITORY.git

如果專案已經存在，進入專案目錄後修改 remote：

git remote -v

git remote set-url origin git@github-personal:USERNAME/REPOSITORY.git

git remote -v

USERNAME 和 REPOSITORY 請替換成實際 GitHub 帳號／儲存庫名稱。

SSH Key 和 Git Commit 身分是兩回事

SSH Key 決定連線 GitHub 時使用哪個驗證身分；Commit 作者名稱／Email 是另一組 Git 設定。如果個人與工作專案需要不同 Commit 身分，可在專案目錄設定：

git config user.name "Your Name"
git config user.email "your_email@example.com"

以上指令（沒有 --global）只影響目前 Repository。

常見問題排查

1. Permission denied (publickey)

通常表示 GitHub 沒有接受本次提供的金鑰。請檢查：

id_personal.pub 是否已加入正確的 GitHub 帳號。
~/.ssh/config 的 Host 與 IdentityFile 是否正確。
你是否使用 ssh -T git@github-personal，而不是無意間連到另一個別名。

查看詳細驗證過程：

ssh -vT git@github-personal

2. The agent has no identities.

表示 Agent 目前沒有載入私鑰，可執行：

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

但只要 SSH Config 正確，沒有預先載入 Agent 不一定會造成連線失敗。

3. 查詢 SSH 實際採用的設定

ssh -G github-personal | grep -E '^(hostname|user|identityfile|identitiesonly) '

4. SSH 私鑰權限問題

若權限不正確，可使用：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_personal
chmod 644 ~/.ssh/id_personal.pub
chmod 600 ~/.ssh/config

指令速查表

目的	指令
查看 SSH 檔案	`ls -al ~/.ssh`
看既有 Key 演算法	`ssh-keygen -lf ~/.ssh/id_work.pub`
建立 Ed25519 Key	`ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_personal`
加入 macOS Keychain／Agent	`ssh-add --apple-use-keychain ~/.ssh/id_personal`
查看 Agent 已載入金鑰	`ssh-add -l`
編輯 SSH 設定	`nano ~/.ssh/config`
複製公鑰	`pbcopy < ~/.ssh/id_personal.pub`
測試個人 GitHub	`ssh -T git@github-personal`
SSH 詳細除錯	`ssh -vT git@github-personal`
查看 Git remote	`git remote -v`

重點總結

SSH 是安全連線協定；RSA／Ed25519 是可供 SSH 身分驗證使用的不同密碼學演算法。
新建 SSH Key 通常建議採用 Ed25519。
f 決定檔案名稱與儲存位置，所以 id_work、id_personal 是自訂名稱。
私鑰留在自己的 Mac，公鑰登記到 GitHub。
有多個 GitHub 帳號時，可透過 ~/.ssh/config 的 Host 別名區分金鑰。
設定完成後，以 ssh -T 確認身分驗證成功。