笙亿网络策划

VSCode Git 提交报错 gpg 签名失败怎么配置密钥

约 6 分钟读完 23 阅
文章导读
在 VSCode 中提交代码遇到 GPG 签名失败，核心原因通常是 Git 无法调用 GPG 程序或找不到对应的私钥。最直接的解决办法是生成一个新的 GPG 密钥，并在 Git 配置中明确指定该密钥的 ID，同时确保系统 GPG 代理正常运行。
📋 目录
  1. Ⅰ 快速修复命令
  2. Ⅱ 详细配置步骤
  3. Ⅲ 配置 GPG 代理避免频繁输入密码
  4. Ⅳ 上传公钥到代码托管平台
  5. Ⅴ 常见错误日志与排查
  6. Ⅵ 经验总结与注意事项
  7. Ⅶ 参考来源
A A

在 VSCode 中提交代码遇到 GPG 签名失败，核心原因通常是 Git 无法调用 GPG 程序或找不到对应的私钥。最直接的解决办法是生成一个新的 GPG 密钥，并在 Git 配置中明确指定该密钥的 ID，同时确保系统 GPG 代理正常运行。

先说结论：这通常是 Git 无法调用 GPG 程序或找不到对应密钥导致的，配置正确后无需每次手动干预。

  • 先确认：检查本地是否已生成 GPG 密钥以及 Git 是否开启签名选项
  • 先处理：生成密钥并将 Key ID 填入 Git 配置项 user.signingkey
  • 再验证：通过 git log 查看提交记录是否显示 Signature verified

快速修复命令

如果你希望快速跳过原理直接尝试修复，可以在终端依次执行以下命令。注意将<YOUR_KEY_ID>替换为实际的密钥 ID，<YOUR_EMAIL>替换为你的邮箱。

gpg `--full-generate-key`

git config `--global` commit.gpgsign true

git config `--global` user.signingkey <YOUR_KEY_ID>

git config `--global` gpg.program gpg

详细配置步骤

1. 备份原有密钥（重要）

在生成新密钥前，建议备份现有的 .gnupg 目录，防止误操作导致旧密钥丢失无法解密历史提交。

VSCode Git 提交报错 gpg 签名失败怎么配置密钥

cp -r ~/.gnupg ~/.gnupg.backup

2. 检查是否已有密钥

在终端输入 gpg `--list-secret-keys` `--keyid-format` LONG。如果有输出，记录下一行中 sec 后面的密钥 ID（通常是 40 位十六进制字符串）。如果没有输出，说明需要生成新密钥。

3. 生成新密钥（如果没有）

执行 gpg `--full-generate-key`，按提示输入姓名、邮箱（需与 Git 配置的 user.email 一致）和 passphrase。生成完成后，再次执行步骤 2 获取密钥 ID。

4. 配置 Git 使用密钥

执行以下命令告诉 Git 使用刚才生成的密钥：

VSCode Git 提交报错 gpg 签名失败怎么配置密钥

git config `--global` user.signingkey <YOUR_KEY_ID>

同时确保开启了自动签名：

git config `--global` commit.gpgsign true

5. 指定 GPG 程序路径（Windows 常见）

在 Windows 上，Git 有时找不到 gpg.exe。如果上述步骤无效，先通过 where gpg 命令查找实际安装路径，然后配置：

git config `--global` gpg.program "查找到的实际路径"

配置 GPG 代理避免频繁输入密码

为了避免每次提交都输入 passphrase，可以配置 gpg-agent 缓存密码。编辑或创建 ~/.gnupg/gpg-agent.conf 文件，加入以下内容：

default-cache-ttl 600

VSCode Git 提交报错 gpg 签名失败怎么配置密钥

max-cache-ttl 7200

保存后重启代理：gpgconf `--kill` gpg-agent

上传公钥到代码托管平台

本地配置完成后，还需将公钥上传至 GitHub 或 GitLab，否则远程仓库无法验证签名。

1. 导出公钥

gpg `--armor` `--export` <YOUR_EMAIL>

复制输出的内容（包含 BEGIN 和 END 行）。

2. 上传至平台

  • GitHub：Settings -> SSH and GPG keys -> New GPG key，粘贴内容。
  • GitLab：Settings -> SSH Keys -> GPG Keys，粘贴内容。

常见错误日志与排查

  • error: gpg failed to sign the data：通常是 gpg-agent 未启动或 pinentry 弹窗被拦截。尝试重启 agent 或检查桌面环境权限。
  • No secret key：Git 配置的 key ID 与本地实际密钥不匹配。重新运行 gpg `--list-secret-keys` 核对 ID。
  • Unknown signature：公钥未上传到远程仓库，或本地密钥邮箱与 Git user.email 不一致。

经验总结与注意事项

  • 邮箱一致性：GPG 密钥中的邮箱必须与 git config user.email 完全一致，否则签名会显示无效。
  • 密钥 ID 格式：配置 user.signingkey 时，建议使用长格式 ID（16 位或 40 位），短格式（8 位）在某些新版 GPG 中可能不被识别。
  • WSL 环境：如果在 Windows 上使用 WSL，需确保 Windows 版的 VSCode 能调用 WSL 内的 gpg，或者直接在 WSL 内开发。
  • Pinentry 弹窗不显示：在 macOS 或某些 Linux 桌面环境下，如果 gpg-agent 配置不当，密码输入框可能不弹出导致超时失败。尝试重启 gpg-agent 或配置 pinentry-program。

参考来源

  • Git SCM Documentation, "Signing Your Work", https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work
  • Visual Studio Code Docs, "Version Control", https://code.visualstudio.com/docs/sourcecontrol/overview
  • GnuPG Documentation, "Howto Configure GnuPG", https://gnupg.org/documentation/howtos.html