macOS下执行git commit -S报错gpg failed to sign the data如何解决

报错信息如下：

error: gpg failed to sign the data
fatal: failed to write commit object

排查修复步骤 #

• 步骤1：确认GPG密钥与Git配置匹配
  首先执行命令查看本地GPG密钥列表：
  gpg --list-secret-keys --keyid-format=long
  确认输出中存在你绑定到GitHub/GitLab的有效密钥，复制sec行后缀/后的密钥ID，执行命令配置到Git：
  git config --global user.signingkey 你的密钥ID
• 步骤2：配置TTY环境变量
  macOS新版终端默认不会将TTY变量传递给GPG代理，需在shell配置文件（zsh对应~/.zshrc，bash对应~/.bash_profile）中添加如下内容：

  export GPG_TTY=$(tty)
  export PINENTRY_USER_DATA="USE_CURSES=1"
  

  执行命令使配置立即生效：
  source ~/.zshrc（bash用户替换为对应配置文件路径）
• 步骤3：测试GPG独立签名能力
  先跳过Git直接测试GPG本身是否正常工作：
  echo "test" | gpg --clearsign
  如果运行后无法弹出密码输入框或直接报错，先重启GPG代理再重试：
  gpgconf --kill gpg-agent
• 步骤4：修复pinentry密码输入程序配置
  系统默认的pinentry程序兼容性较差，建议通过Homebrew安装pinentry-mac：
  brew install pinentry-mac
  编辑~/.gnupg/gpg-agent.conf文件，添加如下配置（M系列Mac路径为/opt/homebrew/bin/pinentry-mac）：
  pinentry-program /usr/local/bin/pinentry-mac
  编辑完成后重启GPG代理生效：
  gpgconf --kill gpg-agent
• 步骤5：确认Git的GPG程序路径配置
  部分场景下Git无法自动找到正确的GPG程序路径，先执行命令查看本地GPG路径：
  which gpg
  将输出的路径配置到Git中：
  git config --global gpg.program 上一步输出的GPG路径
• 步骤6：设置密钥信任级别
  导入的外部密钥如果未设置信任级别也会导致签名失败，执行命令编辑密钥属性：
  gpg --edit-key 你的密钥ID
  依次输入trust、5（选择终极信任）、save完成配置。

验证 #

所有配置完成后，再次执行提交命令测试：
git commit -S -m 'test'
如果仍报错，可执行GIT_TRACE=1 git commit -S -m 'test'查看详细运行日志，定位具体故障点。

内容的提问来源于stack exchange，提问作者Matúš Rebroš