Git提交签名需GPG密钥、Git配置、密码管理三者对齐才能稳定工作；单独设commit.gpgsign true易因邮箱不匹配、pinentry失效或公钥未上传导致签名失败或平台不显示Verified。
Git 提交签名不是“开了就自动生效”的开关，而是需要 GPG 密钥、Git 配置、密码管理三者对齐才能稳定工作。单独配 commit.gpgsign true 很可能卡在输密码或验证失败上。
检查 GPG 是否就绪且密钥匹配邮箱
Git 签名失败最常见的原因是：你生成的 GPG 密钥里没包含当前 git config user.email 所用的邮箱，或者该邮箱未在 GitHub/GitLab 上验证过。
- 运行
git config user.email确认当前提交者邮箱 - 运行
gpg --list-secret-keys --keyid-format=long，找uid行，确认它包含上面那个邮箱 - 若不匹配，要么重新生成密钥（
gpg --full-generate-key），要么用gpg --edit-key KEYID添加邮箱并保存 - 导出公钥：
gpg --armor --export KEYID，粘贴到 GitHub 的 Settings → SSH and GPG keys 页面
配置 Git 使用指定密钥和签名行为
仅设 commit.gpgsign true 不够，Git 还得知道用哪个密钥、调哪个 GPG 程序——尤其 macOS 或 WSL 下容易用错二进制。
- 设置签名密钥：
git config --global user.signingkey ABCDEF1234567890（用你自己的长 ID） - 启用全局提交签名：
git config --global commit.gpgsign true - 显式指定 GPG 程序（避免
gpg被 alias 或 PATH 混淆）：git config --global gpg.program gpg或git config --global gpg.program /usr/bin/gpg - 如果用的是较新 macOS + GPG Suite，可加
git config --global gpg.ssh.allowedSignersFile ~/.gnupg/allowed_signers（仅限 SSH 签名场景）
解决每次提交都弹密码框或直接报错
GPG 默认每次签名都唤起 pinentry，但终端环境（如 VS Code 内置终端、某些远程 SSH 会话）可能无法渲染 GUI 弹窗，导致卡住或报 gpg: signing failed: No pinentry。
- 先确认是否启用了 loopback 模式：
grep "pinentry-mode" ~/.gnupg/gpg.conf，应有pinentry-mode loopback - 重启 agent：
gpgconf --kill gpg-agent && gpgconf --launch gpg-agent - macOS 用户优先装 GPG Suite，它自动集成钥匙串；Windows 用户用 Gpg4win 自带的 Kleopatra 管理密码缓存
- 测试是否通：
echo test | gpg --clearsign 2>/dev/null，不报错即基本可用
验证签名是否真被平台识别
本地签名成功 ≠ GitHub/GitLab 显示 “Verified”。平台只认你账户里上传过的公钥，且要求签名时用的邮箱必须是平台已验证邮箱。
- 推送后访问 GitHub 仓库 → Commits 页面，找最新提交，看右上角是否显示
Verified - 若显示
Unverified，点开提交详情页，再点 “Verify signature” 查具体错误（常见是邮箱不匹配或公钥未上传） - 用命令行验证：
git show -s --show-signature HEAD，输出里出现Good signature from才算本地签成功 - GitLab 需额外注意：它不查公钥服务器，只认你账户里手动粘贴的公钥；且密钥中必须至少有一个邮箱与 GitLab 账户绑定的已验证邮箱完全一致
真正麻烦的从来不是生成密钥或敲几行 config，而是密钥生命周期管理——比如密钥过期后忘记更新平台上的公钥，或者换公司邮箱却没同步 GPG uid。这些不会报错，只会让新提交默默变成 Unverified，而你可能两周后才在 PR 里注意到。
