Windows下IntelliJ调用WSL2 Git无法完成GPG提交签名如何解决

问题场景 #

• 运行环境：Windows 10 搭载WSL2 Ubuntu发行版
• IDE配置：Windows端安装IntelliJ，配置调用WSL2虚拟机内的Git二进制文件，执行commit时启用GPG签名
• 前置校验通过项：
  • WSL2虚拟机内GPG签名功能正常，可正常弹出密码短语输入对话框
  • Windows终端内GPG签名功能正常，可正常弹出密码短语输入对话框
  • 直接使用Git CLI执行提交操作时GPG密钥工作正常，手动提交无异常
• 故障表现：IntelliJ内执行签名提交时触发报错，无法完成签名流程

故障根因 #

IntelliJ通过后台非交互通道调用WSL2内的Git进程时，不会为WSL侧分配可交互的tty终端，WSL内默认配置的gpg-agent找不到可用的终端或GUI入口唤起密码输入程序，直接返回签名失败，和两侧GPG、Git的基础配置正确性无关。

解决步骤 #

1. 调整WSL侧GPG Agent配置
   编辑WSL内的~/.gnupg/gpg-agent.conf文件，新增或修改以下配置项（注意pinentry路径要替换为你本机Gpg4win的实际安装路径）：

   # 密码缓存时长，可按需调整
   default-cache-ttl 3600
   max-cache-ttl 86400
   # 直接调用Windows侧的pinentry程序，规避WSL内无GUI/tty的问题
   pinentry-program /mnt/c/Program Files (x86)/Gpg4win/bin/pinentry.exe
   # 允许loopback模式传递密码请求
   allow-loopback-pinentry
   

2. 重启GPG Agent加载配置
   在WSL终端执行以下命令重启agent，确保新配置生效：

   gpgconf --kill gpg-agent
   gpg-agent --daemon
   

3. 配置WSL侧Git适配GPG调用模式
   在WSL终端执行全局Git配置：

   git config --global gpg.program gpg
   git config --global gpg.loopbackMode true
   

4. 修正IntelliJ运行与配置项
   • 不要以管理员权限启动IntelliJ：管理员权限运行的Windows进程和普通权限运行的WSL、gpg-agent进程处于不同安全上下文，会直接阻断跨进程的pinentry调用、缓存读取逻辑，用普通用户权限启动IDE即可。
   • 打开IntelliJ Settings > Version Control > Git配置页，确认Git路径为WSL原生路径格式，例如\\wsl$\Ubuntu\usr\bin\git，不要使用盘符映射的路径，点击Test按钮确认Git可被正常识别。
   • 进入Settings > Version Control > Git > Configure GPG Key页面，确认选中的签名密钥ID和你WSL侧配置的GPG密钥完全一致，不要误选Windows侧独立存储的密钥副本。
5. 预填充GPG密码缓存
   在WSL终端手动执行一次带签名的测试提交，输入GPG密码完成签名，让gpg-agent缓存密码，后续IntelliJ调用时可直接复用缓存，无需重复唤起密码输入框：

   mkdir -p /tmp/test-gpg && cd /tmp/test-gpg
   git init
   touch test.txt
   git add .
   git commit -S -m "test gpg signature"
   # 确认提交成功、签名有效后可删除测试目录
   rm -rf /tmp/test-gpg
   

补充排查点 #

如果完成上述配置后仍然报错，依次检查以下项：

• 确认WSL内的签名密钥已设置为最终信任等级：执行gpg --edit-key 你的密钥ID，输入trust后选择等级5（最终信任），保存退出后重试。
• 避免两端GPG Agent冲突：打开Windows任务管理器，在启动项中禁用Gpg4win的gpg-agent自启，统一由WSL侧的gpg-agent处理签名请求，避免两个进程抢占锁文件导致调用失败。
• 检查WSL内~/.gnupg目录权限：执行chmod 700 ~/.gnupg && chmod 600 ~/.gnupg/*修正权限，避免GPG因权限过宽拒绝读取配置、密钥文件。

内容的提问来源于stack exchange，提问作者Francisco Solis