Mac 系统 Git 与 GitHub 完整配置教程（含用户名查询与 SSH 密钥配置）

前言

本教程专为 Mac 系统用户 设计，覆盖从 Git 环境验证、基础用户信息配置、SSH 密钥生成与关联，到 GitHub 账号绑定的全流程，同时包含 Git 与 GitHub 各类用户名的查询方法，帮助你一站式实现本地 Git 与远程 GitHub 仓库的安全、免密连接。

一、准备工作与环境验证

1.1 确认 Git 已安装（或安装 Git）

Mac 通常预装 Git，先通过终端验证是否已安装：

git --version

• 若已安装：输出类似 git version 2.45.1，直接进入下一步。
• 若未安装：通过 Homebrew 安装（推荐，后续更新更便捷）：

# 1. 安装 Homebrew（若未安装，复制整行执行）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. 安装 Git
brew install git

1.2 注册并登录 GitHub 账号

1. 访问 GitHub 官网，注册账号（若已有账号，直接登录）。
2. 记录两个关键信息（后续配置需用到）：
   • GitHub 用户名：登录后右上角「头像下拉菜单」最上方显示的名称（如 octocat）。
   • GitHub 注册邮箱：注册时使用的邮箱（用于关联 Git 提交记录和 SSH 密钥）。

二、配置 Git 基础用户信息

Git 需要通过「用户名」和「邮箱」关联你的提交记录，建议与 GitHub 账号信息完全一致，避免提交记录归属混乱。

2.1 配置全局用户信息（推荐）

全局配置适用于 Mac 上所有本地 Git 仓库，终端执行以下命令（替换为你的信息）：

# 配置全局用户名（需与 GitHub 用户名一致）
git config --global user.name "你的GitHub用户名"

# 配置全局邮箱（需与 GitHub 注册邮箱一致）
git config --global user.email "你的GitHub邮箱@example.com"

2.2 验证配置结果

执行以下命令，确认配置是否生效：

# 查看所有全局 Git 配置
git config --global --list

• 输出中需包含 user.name=你的GitHub用户名 和 user.email=你的GitHub邮箱，说明全局配置成功。

2.3 （可选）为单个仓库配置独立用户信息

若某一仓库需要使用不同的用户信息（如工作仓库用公司邮箱），可进入仓库目录后单独配置（覆盖全局配置）：

# 1. 进入目标仓库目录（替换为你的仓库路径）
cd /Users/你的Mac用户名/Documents/work-repo

# 2. 配置当前仓库的用户名和邮箱（无需 --global 参数）
git config user.name "工作专用用户名"
git config user.email "工作邮箱@company.com"

# 3. 验证当前仓库配置
git config --list | grep user.name

三、查询各类用户名（Git 与 GitHub）

配置过程中可能需要确认「Git 本地配置用户名」和「GitHub 账号用户名」，避免混淆，以下是具体查询方法：

3.1 查询 Git 配置的用户名

场景	终端命令	说明
全局用户名（所有仓库）	git config --global user.name	直接输出全局配置的用户名
当前仓库用户名	进入仓库后执行 git config user.name	若有独立配置则输出，无则不显示内容

3.2 查询 GitHub 账号用户名

方法 1：通过 GitHub 官网（最直接）

1. 登录 GitHub 后，点击右上角「头像」，展开下拉菜单。
2. 菜单 最上方显示的名称 即为你的 GitHub 用户名（如 john-doe）。

方法 2：通过个人资料 URL

1. 登录 GitHub 后，点击右上角「头像」→ 选择 Your profile（个人资料）。
2. 浏览器地址栏 URL 格式为 https://github.com/用户名，其中 / 后的部分即为 GitHub 用户名（例：https://github.com/mary-lee 中的 mary-lee）。

方法 3：通过本地仓库远程地址（已有克隆仓库时）

若本地已克隆 GitHub 仓库，可通过远程地址反推用户名：

# 1. 进入本地仓库目录
cd /Users/你的Mac用户名/Documents/test-repo

# 2. 查看远程仓库地址
git remote -v

• 输出示例（SSH 或 HTTPS 格式）：

  origin  git@github.com:john-doe/test-repo.git (fetch)  # SSH 格式
  origin  https://github.com:john-doe/test-repo.git (push)  # HTTPS 格式
  

• 解析：github.com/ 与 / 之间的部分即为 GitHub 用户名（上例中为 john-doe）。

四、配置 SSH 密钥（免密码连接 GitHub）

SSH 密钥是 Mac 与 GitHub 交互的安全认证方式，配置后无需每次操作仓库都输入 GitHub 账号密码，是推荐的连接方式。

4.1 检查是否已有 SSH 密钥

先确认本地是否已存在 SSH 密钥（避免重复生成），终端执行：

# 列出 ~/.ssh 目录下的文件（.ssh 是隐藏目录，存储 SSH 密钥）
ls -la ~/.ssh

• 若已有密钥：能看到 id_ed25519（私钥）和 id_ed25519.pub（公钥），或 id_rsa（旧版 RSA 私钥）和 id_rsa.pub（旧版 RSA 公钥），直接跳到 4.3 节。
• 若没有密钥：继续执行 4.2 节生成新密钥。

4.2 生成新的 SSH 密钥（Mac 特化步骤）

推荐使用更安全的 ed25519 算法（Mac 系统默认支持），终端执行：

# 替换为你的 GitHub 注册邮箱，生成密钥
ssh-keygen -t ed25519 -C "你的GitHub邮箱@example.com"

执行后按以下提示逐步操作：

1. 提示 Enter file in which to save the key (/Users/你的Mac用户名/.ssh/id_ed25519)：直接按回车，使用默认路径（无需修改）。
2. 提示 Enter passphrase (empty for no passphrase)：
   • 可选设置「密钥密码」（增强安全性，后续使用密钥时需输入该密码），或直接按回车（无密码）。
3. 提示 Enter same passphrase again：再次输入密码确认（若第一步设置了密码）。

• 生成成功后，终端会显示密钥保存路径，类似：

  Your identification has been saved in /Users/你的Mac用户名/.ssh/id_ed25519
  Your public key has been saved in /Users/你的Mac用户名/.ssh/id_ed25519.pub
  

4.3 将 SSH 密钥添加到 ssh-agent（Mac 关键步骤）

ssh-agent 是管理 SSH 密钥的工具，Mac 中需将密钥添加到 agent 并关联「系统钥匙串」，避免重启终端后密钥失效或重复输入密码。

步骤 1：启动 ssh-agent

eval "$(ssh-agent -s)"

• 成功启动会输出类似 Agent pid 12345 的进程 ID。

步骤 2：添加私钥到 ssh-agent

• 若使用 ed25519 算法（推荐）：

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

• 若使用旧版 RSA 算法：

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

• 说明：--apple-use-keychain 是 Mac 特有的参数，用于将密钥密码保存到系统钥匙串，后续无需重复输入。

4.4 将公钥添加到 GitHub 账户

GitHub 需要识别你的本地公钥才能建立信任，需将 id_ed25519.pub（或 id_rsa.pub）的内容添加到 GitHub 账号。

步骤 1：获取公钥内容

终端执行以下命令（根据生成的算法选择）：

# 若使用 ed25519 算法（推荐）
cat ~/.ssh/id_ed25519.pub

# 若使用旧版 RSA 算法
cat ~/.ssh/id_rsa.pub

• 输出格式类似（完整复制这段内容，包括开头的 ssh-ed25519 和结尾的邮箱）：

  ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKZxv3jXk8j5G9wQabcdefghijklmnopqrstuvwxyz 你的GitHub邮箱@example.com
  

步骤 2：在 GitHub 中添加公钥

1. 登录 GitHub → 点击右上角「头像」→ 选择 Settings（设置）。
2. 在左侧菜单中找到 SSH and GPG keys → 点击右上角 New SSH key。
3. 填写公钥信息：
   • Title：自定义名称（如"我的 Mac 笔记本"，用于区分不同设备）。
   • Key：粘贴刚才复制的公钥内容（确保无多余空格、换行或字符缺失）。
4. 点击 Add SSH key，若弹出密码验证，输入 GitHub 账号密码确认。

4.5 验证 SSH 连接是否成功

终端执行以下命令，确认 Mac 与 GitHub 的 SSH 连接是否生效：

ssh -T git@github.com

• 首次连接提示：

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

  • 输入 yes 并回车（仅首次连接需要，后续不再提示）。

• 连接成功提示：

  Hi 你的GitHub用户名! You've successfully authenticated, but GitHub does not provide shell access.
  

  • 看到此提示，说明 SSH 密钥配置完全成功！

五、（可选）配置 HTTPS 连接的凭证存储

若你偏好使用 HTTPS 连接 GitHub（而非 SSH），可配置 Mac 「钥匙串」自动保存凭证，避免每次操作仓库都输入用户名密码。

终端执行以下命令：

# 配置 Git 使用 Mac 钥匙串存储 HTTPS 凭证
git config --global credential.helper osxkeychain

• 配置后，首次通过 HTTPS 拉取/推送代码时，输入一次 GitHub 用户名和密码，后续会自动保存到钥匙串，无需重复输入。

六、测试配置（验证仓库操作）

通过实际克隆、修改、推送仓库，验证 Git 与 GitHub 的配置是否完整生效。

步骤 1：在 GitHub 上创建测试仓库

1. 登录 GitHub → 点击右上角「+」→ 选择 New repository。
2. 填写仓库信息：
   • Repository name：输入 test-github-config（自定义名称）。
   • 勾选 Initialize this repository with a README（生成 README 文件）。
3. 点击 Create repository，创建完成后进入仓库页面。

步骤 2：克隆仓库到 Mac 本地

1. 在 GitHub 测试仓库页面 → 点击 Code 按钮 → 选择 SSH（若配置了 HTTPS 则选 HTTPS）→ 复制仓库地址（如 git@github.com:你的GitHub用户名/test-github-config.git）。
2. 终端执行以下命令（替换为你的仓库地址）：

# 克隆仓库到本地
git clone git@github.com:你的GitHub用户名/test-github-config.git

# 进入克隆后的仓库目录
cd test-github-config

步骤 3：提交并推送测试文件

# 1. 创建一个测试文件
echo "Mac 配置 GitHub 成功！" > test.txt

# 2. 将文件添加到 Git 暂存区
git add test.txt

# 3. 提交文件到本地仓库（备注提交信息）
git commit -m "添加测试文件 test.txt"

# 4. 推送到 GitHub 远程仓库
git push origin main

步骤 4：验证结果

1. 刷新 GitHub 上的测试仓库页面。
2. 若能看到新增的 test.txt 文件，说明本地 Git 与 GitHub 已能正常交互，配置完全生效！

七、常见问题与解决方案

问题现象	解决方案
ssh -T git@github.com 提示 Permission denied (publickey)	1. 检查公钥是否完整添加到 GitHub（4.4 节）； 2. 重新执行 ssh-add --apple-use-keychain ~/.ssh/id_ed25519 确认私钥已添加到 agent。
重启终端后 SSH 密钥失效，需重新添加	确保添加密钥时使用了 --apple-use-keychain 参数（4.3 节），该参数会将密钥信息持久化到系统钥匙串。
HTTPS 连接时钥匙串不保存密码	1. 重新执行 git config --global credential.helper osxkeychain； 2. 打开「钥匙串访问」→ 删除旧的 GitHub 凭证 → 重新推送时输入密码保存。
忘记 GitHub 用户名	访问 GitHub 登录页 → 点击"Forget password?" → 输入注册邮箱，GitHub 会发送包含用户名的邮件。