Windows 上流畅的 Git 认证：Git Credential Manager、SSH 密钥、SSH 签名、多账号管理。

Windows 上的 Git 认证比 macOS/Linux 略复杂——Git Credential Manager（GCM）、OpenSSH 和 1Password agent 可能互相冲突。本指南提供一次性的干净配置，让你一年内无需再次折腾。

我认为 Windows 上 Git 认证问题的根本原因不在于工具质量，而在于多个认证层叠加后的优先级冲突。以前开发者靠反复尝试解决冲突；如今通过一次性明确配置 GCM 和 SSH 的分工，由于各自职责清晰，冲突从根本上被消除。

目标环境：Windows 11 + Git for Windows + GitHub（完成 Windows 初始设置之后）。

TL;DR

Git Credential Manager（GCM） — HTTPS 克隆使用 OAuth（浏览器登录）
OpenSSH 密钥 — SSH 克隆用。推荐 Ed25519
提交签名 — 使用 SSH 密钥（比 GPG 更简单）
工作/个人账号分离 — Include.path 或 ~/.ssh/config Host 别名
1Password SSH agent（可选）— 密钥存入保险库

前置条件

Git for Windows 2.40+ — winget install --id Git.Git（Windows 初始设置）
已启用 OpenSSH 客户端（Win11 默认）— 验证：Get-WindowsCapability -Online -Name "OpenSSH.Client*"

1. Git Credential Manager — HTTPS

GCM 随 Git for Windows 一起安装。HTTPS 克隆/推送会自动打开 OAuth 浏览器流程：

git clone https://github.com/user/repo.git
# 浏览器打开 → GitHub 登录 → 令牌自动存储

存储位置：Windows 凭据管理器（控制面板 → 用户账户 → 凭据管理器 → Windows 凭据）。

验证

git config --global credential.helper
# manager

如果显示 manager，GCM 已激活。否则：

git config --global credential.helper manager

多账号（工作 + 个人 GitHub）

为不同 URL 配置不同的 helper：

git config --global --add credential.https://github.com.useHttpPath true

现在同一主机上的不同路径会使用独立的凭据。

2. SSH 密钥

SSH 比 HTTPS 更流畅（无需浏览器）。生成 Ed25519 密钥：

ssh-keygen -t ed25519 -C "you@example.com"
# 路径：~/.ssh/id_ed25519（默认）
# 密码短语：推荐设置（1Password agent 可自动解锁）

显示公钥：

Get-Content ~/.ssh/id_ed25519.pub
# ssh-ed25519 AAAA... you@example.com

GitHub → Settings → SSH and GPG keys → New SSH key → 粘贴公钥。

启用 ssh-agent（自动解锁密码短语）

# 管理员 PowerShell
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
 
# 普通 PowerShell
ssh-add ~/.ssh/id_ed25519
# 输入一次密码短语，之后自动解锁

验证 SSH

ssh -T git@github.com
# Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.

切换远程 URL（HTTPS → SSH）

git remote set-url origin git@github.com:user/repo.git

3. SSH 提交签名

比 GPG 更简单，复用同一密钥。需要 Git 2.34+。

git config --global gpg.format ssh
git config --global user.signingkey "ssh-ed25519 AAAA... you@example.com"
git config --global commit.gpgsign true
git config --global tag.gpgsign true

user.signingkey 填写完整的公钥内容行，也可以填写文件路径：

git config --global user.signingkey "C:/Users/me/.ssh/id_ed25519.pub"

在 GitHub 注册签名密钥

在 GitHub → SSH and GPG keys → Add new SSH key → Key type 选择 Signing Key，注册同一公钥。

测试

git commit --allow-empty -m "test signed"
git log --show-signature -1
# Good "git" signature with ED25519 key SHA256:...

在 PR 页面确认「Verified」标记。

allowed_signers 文件（本地验证所需）

~/.config/git/allowed_signers：

you@example.com ssh-ed25519 AAAA...
coworker@example.com ssh-ed25519 BBBB...

git config --global gpg.ssh.allowedSignersFile "$HOME/.config/git/allowed_signers"

git log --show-signature 现在也能验证他人的提交。

4. 多 GitHub 账号（工作 + 个人）

4.1 SSH config — Host 别名

~/.ssh/config：

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  IdentitiesOnly yes

Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

克隆：

git clone git@github.com-personal:personal-user/repo.git
git clone git@github.com-work:company/repo.git

4.2 按文件夹设置 user.email — `includeIf`

~/.gitconfig：

[user]
    name = Your Name
    email = personal@example.com
 
[includeIf "gitdir:C:/Users/me/work/"]
    path = C:/Users/me/.gitconfig-work

~/.gitconfig-work：

[user]
    email = me@company.com
    signingkey = ssh-ed25519 AAAA... me@company.com

C:/Users/me/work/ 下的仓库会自动使用工作邮箱/密钥。

验证：

cd C:\Users\me\work\some-repo
git config user.email
# me@company.com
 
cd C:\Users\me\personal\some-repo
git config user.email
# personal@example.com

5. 1Password SSH Agent（可选）

参见密码管理器。在 Windows 上通过环境变量设置 agent socket：

1Password 桌面版 → Settings → Developer → 开启「Use the SSH agent」✅
将 SSH 密钥存入 1Password 保险库并在 GitHub 注册

PowerShell $PROFILE：

$env:SSH_AUTH_SOCK = '\\.\pipe\openssh-ssh-agent'

新终端 → ssh -T git@github.com → Windows Hello 认证一次

现在 SSH 和提交签名无需将 ~/.ssh/id_* 明文存储在磁盘上。

6. 验证

ssh -T git@github.com — 认证通过
git clone git@github.com:you/repo.git — 不提示密码短语（或生物识别一次）
git commit --allow-empty -m test && git log --show-signature -1 — 「Good signature」
GitHub 上的 PR 显示「Verified」标记
工作文件夹和个人文件夹中 git config user.email 返回不同值

故障排查

`ssh: connect to host github.com port 22: Connection timed out`

企业防火墙屏蔽了 22 端口。改用 443 端口的 SSH：

# ~/.ssh/config
Host github.com
  HostName ssh.github.com
  Port 443

`Permission denied (publickey)`

密钥文件权限 — icacls ~/.ssh/id_ed25519 /inheritance:r /grant:r "$($env:USERNAME):(R)"
公钥未在 GitHub 注册

GCM 未启用

git config --global credential.helper manager
git config --global credential.helperSelector prompt

1Password SSH agent 未被检测到

桌面应用运行中 + 已登录 + Developer 选项已开启
SSH_AUTH_SOCK 值必须精确（\\.\pipe\openssh-ssh-agent）
冲突：如果 OpenSSH agent 服务正在运行，其 socket 可能优先生效。Stop-Service ssh-agent 或禁用该服务

提交签名显示「Unverified」

需要在 GitHub 将 SSH 密钥注册为签名密钥（与认证密钥分开）
缺少 git config --global gpg.format ssh
密钥损坏 — 重新生成并注册

`includeIf` 未生效

需要 Git 2.36+（旧版 Git for Windows 不支持）
gitdir 路径末尾需加 /（C:/Users/me/work/）
Windows 上用 / 而非 \

参考资料

Windows 初始设置 — Git for Windows 预安装
密码管理器 — 1Password SSH agent 集成
跨平台 dotfiles — 用 chezmoi 在两台机器上共享 Git 配置
GCM（官方）

更新日志

2026-05-12：初稿。GCM + SSH 密钥 + SSH 签名 + 多账号 + 1Password agent + 六个故障排查案例。

Windows 上的 Git 认证 — Credential Manager · SSH · 提交签名