macOS Monterey下git提交报错gpg failed to sign data如何解决

问题背景 #

• 本地分支执行带GPG签名的提交时触发报错，无法完成commit写入
• 已排除密钥过期问题，所用GPG密钥有效期至2032年
• 已检索过同类公开问题，较早的帖子无参考性，同场景近期问题帖未给出有效解决方案

已采集的环境与报错信息 #

• 运行系统：Monterey macOS (12.4)
• Git版本：执行git --version返回 git version 2.32.1 (Apple Git-133)
• 执行GIT_TRACE=1 git commit -S -m "my-local-branch"抓取的追踪日志：

17:03:31.062430 exec-cmd.c:139          trace: resolved executable path from Darwin stack: /Library/Developer/CommandLineTools/usr/bin/git
17:03:31.062692 exec-cmd.c:238          trace: resolved executable dir: /Library/Developer/CommandLineTools/usr/bin
17:03:31.063037 git.c:455               trace: built-in: git commit -S -m here_goes_branch_name
17:03:31.065514 run-command.c:667       trace: run_command: gpg --status-fd=2 -bsau here_goes_my_actual_key

• 最终报错输出：

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

按优先级排查解决 #

1. 先剥离Git链路，测试GPG本身签名能力 #

直接在终端执行基础签名测试命令，先确认GPG本身工作正常：

echo "test" | gpg --clearsign

• 如果这一步直接报错，问题和Git配置无关，优先排查GPG环境：
  • 执行gpg --list-secret-keys --keyid-format=long，确认你配置给Git的密钥ID确实存在于返回的私钥列表中，没有输错ID
  • 这是macOS平台该类报错最高发的诱因：tty权限不足导致GPG无法唤起密码输入弹窗。根据你使用的shell，在对应配置文件（zsh对应~/.zshrc，bash对应~/.bashrc）中添加环境变量：

    export GPG_TTY=$(tty)
    

    保存后执行source ~/.zshrc（替换为你实际修改的配置文件路径）重载配置后重试
  • 如果使用GPG Suite管理密钥，打开系统设置-隐私与安全性-完全磁盘访问，给你当前使用的终端（系统终端/iTerm2/Warp等）勾选权限，重启终端后重试
  • 检查~/.gnupg目录权限，执行以下命令修复权限问题：

    chmod 700 ~/.gnupg
    chmod 600 ~/.gnupg/*
    

    避免因权限不符合GPG安全要求导致无法读取私钥

2. 核对Git侧GPG相关配置 #

Apple自带的Git版本经常出现GPG路径匹配错误的问题，逐项执行命令核对配置：

• 执行git config --global gpg.program查看当前配置的GPG程序路径，若返回空或者路径不对，直接执行以下命令配置为当前环境默认的GPG路径：

  git config --global gpg.program $(which gpg)
  

• 执行git config --global user.signingkey查看配置的签名密钥ID，和之前gpg --list-secret-keys查到的密钥ID逐字符核对，确保完全一致

3. 排除其他干扰项 #

• 手动执行gpg --edit-key 你的密钥ID，按提示输入密钥密码，手动解锁一次密钥，确认密码正确、密钥文件无损坏
• 执行git commit --no-gpg-sign -m "test commit"临时关闭签名测试提交，确认Git仓库本身无损坏、基础提交流程正常，再回头定位GPG链路问题

内容的提问来源于stack exchange，提问作者Papi Antoniadis