笙亿网络策划

VSCode Git 提交报错 gpg 签名失败如何配置密钥

约 5 分钟读完 42 阅
文章导读
遇到 VSCode Git 提交报 gpg 签名失败，最直接的解决方式是确认是否必须开启签名。若无需强制签名可暂时关闭，若需要则补全密钥配置。
📋 目录
  1. A 命令速用版
  2. B 为什么会这样
  3. C 分步处理
  4. D VSCode 界面配置
  5. E 密钥备份与迁移
  6. F 怎么验证是否生效
  7. G 常见坑
A A

遇到 VSCode Git 提交报 gpg 签名失败，最直接的解决方式是确认是否必须开启签名。若无需强制签名可暂时关闭，若需要则补全密钥配置。

先说结论：大多数情况是 Git 配置了自动签名但本地没有有效密钥。优先检查配置项，再决定是生成密钥还是关闭签名。

  • 先确认：检查 Git 配置中是否开启了 commit.gpgsign
  • 先处理：根据需求生成 GPG 密钥或关闭自动签名（注意团队合规）
  • 再验证：尝试提交并查看日志确认签名状态

命令速用版

# 临时关闭全局签名（注意：团队项目请谨慎使用，可能违反合规要求）
git config `--global` commit.gpgsign false

# 查看当前是否有密钥
gpg `--list-secret-keys` `--keyid-format` LONG

# 指定密钥 ID（替换为实际 ID）
git config `--global` user.signingkey 3AA5C34371567BD2

# 指定 gpg 程序路径（Windows 用户需先确认路径）
# Windows 查找路径命令：where gpg
# Mac/Linux 查找路径命令：which gpg
git config `--global` gpg.program "C:/Program Files (x86)/gnupg/bin/gpg.exe"

为什么会这样

Git 支持使用 GPG 对提交记录进行加密签名，用来证明提交确实来自你且未被篡改。当你在 Git 配置中开启了 commit.gpgsign 选项，或者仓库强制要求签名时，每次提交都会调用本地的 GPG 工具。

报错通常是因为 Git 找到了开启签名的指令，但找不到可用的私钥，或者找不到 GPG 程序本身。VSCode 内置的 Git 功能直接调用系统 Git，所以表现和命令行一致。

分步处理

1. 确认是否必须签名

如果你只是个人项目，或者团队没有强制要求，关闭签名是最快的方法。运行 git config `--global` commit.gpgsign false 后重试提交。

注意：企业级项目或开源协作项目通常强制要求签名以确保身份可信，关闭前请务必确认团队规范。

2. 生成新密钥（如果需要签名）

安装 GPG 工具后，运行 gpg `--full-generate-key`。按提示选择算法（默认 RSA 即可），设置有效期和密码。生成完成后，用 gpg `--list-secret-keys` `--keyid-format` LONG 查看密钥 ID。

3. 告诉 Git 使用哪个密钥

VSCode Git 提交报错 gpg 签名失败如何配置密钥

复制密钥 ID，运行 git config `--global` user.signingkey <密钥 ID>。同时确保 git config `--global` user.email 和密钥中的邮箱一致，否则签名会显示无效。

4. Windows 用户注意路径

在 Windows 上，Git 有时找不到 gpg.exe 的位置。使用 where gpg 找到路径，然后通过 git config `--global` gpg.program "完整路径" 指定。不要直接复制示例路径，需根据实际安装位置调整。

VSCode 界面配置

除了命令行，你也可以在 VSCode 设置中管理签名配置：

  1. 打开设置：点击左下角齿轮图标，选择“设置”（或使用快捷键 Ctrl + ,）。
  2. 搜索配置项：在搜索框输入 git.gpgsign。
  3. 修改配置：
    • 若需关闭签名：取消勾选 Git: Gpgsign。
    • 若需开启签名：勾选该选项，并确保下方 Git: Signingkey 填入了正确的密钥 ID。
  4. 保存后重试提交，观察右下角 Git 状态栏是否有报错。

密钥备份与迁移

生成密钥后建议备份，避免更换电脑后无法提交历史签名：

# 导出私钥（注意保护文件安全）
gpg `--export-secret-keys` -a YOUR_KEY_ID > private.key

# 导出公钥
gpg `--export` -a YOUR_KEY_ID > public.key

# 迁移到新电脑后导入
gpg `--import` private.key

备份文件建议加密存储，避免私钥泄露。

怎么验证是否生效

完成配置后，在 VSCode 中进行一次提交。打开终端运行 git log `--show-signature` -1。

如果看到 gpg: Signature made ... 且显示 Good signature，说明配置成功。如果之前是关闭签名，日志中不会显示签名信息，但提交不会再报错。

常见坑

  • 邮箱不匹配：Git 用户邮箱必须与 GPG 密钥中的邮箱一致，否则签名会显示“无效”。
  • 密钥过期：检查密钥有效期，过期的密钥会导致签名失败，需延长有效期或生成新密钥。
  • Pinentry 弹窗卡住：有时输入密码的弹窗不显示，导致超时失败。可尝试修改 gpg-agent 配置或重启电脑。
  • WSL 环境混用：在 Windows 版 VSCode 中调用 WSL 里的 GPG 容易出错，建议统一环境。
  • 合规风险：随意关闭签名可能违反公司安全红线，操作前请咨询团队负责人。