Skip to content

GPG Key 完全配置指南

Jump to bottom
DotnetInstall edited this page Aug 29, 2025 · 5 revisions

问：为什么要配置 GPG Key？🤔

答：想象一下，你在 GitHub 上提交（commit）代码，就像是寄出了一封信。默认情况下，这封信上只写了你的名字（git config里的 user.name 和 user.email）。但任何人都可以冒充你的名字去“寄信”。

而 GPG (GNU Privacy Guard) 就像是你的个人“数字签名+印章”。当你用 GPG Key 签名你的提交后，GitHub 就能验证这个提交确实是你本人发出的，而不是别人冒充的。验证通过后，你的提交旁边会出现一个绿色的 "Verified" 徽章，如下图所示：

image

这大大增加了你代码仓库的安全性和可信度。

准备工作

在开始之前，请确保你的电脑上已经安装了 Git。

✨ 配置步骤 ✨

我们将整个过程分为以下几大步：

  1. 安装 GPG 工具
  2. 生成你的 GPG 密钥对
  3. 将 GPG 公钥添加到 GitHub
  4. 配置 Git 使用 GPG 签名
  5. 进行一次签名提交并验证

第 1 步：安装 GPG 工具 (GnuPG)

你需要先在你的电脑上安装 GPG 命令行工具。

  • Windows 系统:

    1. 访问 Gpg4win 官网。
    2. 下载并安装最新版本。安装过程中保持默认选项即可。安装完成后，它会自动将 GPG 工具添加到系统环境中。
    3. 打开一个新的 Git Bash 终端（推荐使用 Git Bash，而不是 CMD 或 PowerShell）来执行后续命令。

  • macOS 系统:

    1. 最简单的方式是使用 Homebrew。如果你没有安装 Homebrew，请先访问官网安装。

    2. 打开“终端” (Terminal) 应用，运行以下命令：

      brew install gnupg

  • Linux 系统 (Debian/Ubuntu):

    1. GPG 通常是预装的。你可以通过运行 gpg --version 来检查。

    2. 如果未安装，打开终端，运行以下命令：

      sudo apt-get update
sudo apt-get install gnupg

第 2 步：生成你的 GPG 密钥对

现在，我们要创建属于你的独一无二的密钥对（一个私钥，一个公钥）。

  1. 打开你的终端 (Git Bash / Terminal)。

  2. 运行以下命令来开始生成过程：

    gpg --full-generate-key

  3. 接下来，程序会问你几个问题，请依次回答：

    • Please select what kind of key you want: (请选择您想要的密钥类型)

      (1) RSA and RSA (default)
...
Your selection?

      直接按 回车，使用默认的 (1) RSA and RSA 即可。

    • What keysize do you want? (您需要多长的密钥？)

      RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072)

      输入 4096 然后按 回车。这是目前最推荐的强度，非常安全。

    • Please specify how long the key should be valid. (请指定密钥的有效期限)

      0 = key does not expire
<n>  = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0)

      为了安全，建议设置一个有效期，比如1年或2年。你可以输入 1y 然后按 回车。当然，为了省事，你也可以直接按 回车 选择永不过期（不推荐）。

    • Is this correct? (y/N) (确认信息是否正确？) 输入 y 然后按 回车。

  4. 接着，你需要输入你的个人信息：

    • Real name: 你的真实姓名或昵称 (例如: Wang Xiaoming)。
    • Email address: 【❗极其重要❗】 这里必须输入你在 GitHub 上已经验证过的邮箱地址！否则 GitHub 无法匹配你的签名。
    • Comment: 备注，可以不填，直接回车。

    输入完毕后，会显示一个确认信息，检查无误后输入 O (Okay) 然后按 回车。

  5. 设置密码 (Passphrase) 此时，会弹出一个窗口或在命令行提示你输入一个密码。这个密码是用来保护你的私钥的，非常重要！

    • 请设置一个强度高且你能记住的密码。
    • 输入两次以确认。
    • 这个密码在你每次使用 GPG 签名时（比如 git commit）都需要输入。

    输入密码后，系统会开始生成密钥，可能会让你随机移动鼠标或敲击键盘来产生足够的“熵”（随机性）。请耐心等待片刻。

  6. 查看并获取你的 GPG Key ID 生成成功后，你需要找到你的 GPG Key ID。运行以下命令：

    gpg --list-secret-keys --keyid-format=long

    你会看到类似下面的输出：

    /Users/hubot/.gnupg/pubring.kbx
---------------------------------
sec   rsa4096/3AA5C34371567BD2 2025-08-28 [SC] [expires: 2026-08-28]
      B2A8C24C270A9448C01B34253AA5C34371567BD2
uid                 [ultimate] Wang Xiaoming <[email protected]>
ssb   rsa4096/4BB6D45482678BE3 2025-08-28 [E] [expires: 2026-08-28]

    你需要的是 sec 那一行斜杠 / 后面的那一长串字符，也就是你的 Key ID。

    在这个例子中，Key ID 就是 3AA5C34371567BD2。请复制你自己的 Key ID。

第 3 步：将 GPG 公钥添加到 GitHub

私钥你自己保管，公钥则要告诉 GitHub，这样它才能用公钥来验证你的签名。

  1. 运行以下命令，导出你的公钥。记得把 YOUR_KEY_ID 换成你上一步复制的 Key ID。

    gpg --armor --export YOUR_KEY_ID

    例如：

    gpg --armor --export 3AA5C34371567BD2

  2. 终端会输出一大段以 -----BEGIN PGP PUBLIC KEY BLOCK----- 开头，并以 -----END PGP PUBLIC KEY BLOCK----- 结尾的文本。完整地复制这一整块文本。

  3. 登录你的 GitHub 账号。

    • 点击右上角的头像 -> Settings。
    • 在左侧菜单中，点击 SSH and GPG keys。
    • 点击右上角的 New GPG key 按钮。

  4. 在 "Key" 文本框中，粘贴你刚才复制的全部公钥内容。

  5. 点击 Add GPG key。你可能需要输入 GitHub 密码来确认。

第 4 步：配置 Git 使用 GPG 签名

现在，你需要告诉本地的 Git 两件事：

  1. 用哪个 Key 来签名。

  2. 以后所有的提交都自动签名。

  3. 告诉 Git 你的 Signing Key 运行以下命令，把 YOUR_KEY_ID 换成你的 Key ID。

    git config --global user.signingkey YOUR_KEY_ID

    例如：

    git config --global user.signingkey 3AA5C34371567BD2

  4. 让 Git 自动为所有提交签名 运行以下命令。这样以后你每次 git commit 都会自动尝试签名，不用每次都手动加 -S 参数。

    git config --global commit.gpgsign true

第 5 步：进行一次签名提交并验证

大功告成！现在我们来实际操作一下，验证所有配置是否生效。

  1. 找一个你自己的 Git 仓库（或者新建一个），进入该仓库的目录。

  2. 随便修改一个文件，或者新建一个文件。

  3. 执行标准的 Git 提交流程：

    # 将文件添加到暂存区
git add .

# 提交更改
git commit -m "feat: This is my first signed commit"

  4. 在执行 git commit 后，系统很可能会提示你输入 GPG 密码（就是你在第 2 步设置的那个）。正确输入后按回车，提交就完成了。

    • 小提示：系统可能会通过 gpg-agent 缓存你的密码一段时间，所以短时间内多次提交可能不会重复要求输入密码。

  5. 将这次提交推送到 GitHub：

    git push

  6. 去 GitHub 验证！ 打开你的 GitHub 仓库页面，找到你刚刚的这次提交。你会发现，在提交记录的旁边，出现了一个闪亮的绿色 "Verified" 徽章！

常见问题与解决方案 (Troubleshooting)

  1. 问题：git commit 时报错 gpg failed to sign the data 或 Inappropriate ioctl for device

    • 原因： GPG 不知道在哪个终端窗口请求输入密码。

    • 解决方案： 在你的 shell 配置文件中（如 .bashrc, .zshrc 等）添加以下这行代码，然后重启终端。

      export GPG_TTY=$(tty)

  2. 问题：提交在 GitHub 上显示 "Unverified"

    • 原因1： 你生成 GPG Key 时使用的邮箱地址，和你 git config user.email 设置的邮箱，以及在 GitHub 绑定的邮箱不一致。
    • 解决方案1： 确保这三个地方的邮箱地址是完全相同的，并且该邮箱已经在 GitHub 上完成了验证。
    • 原因2： 你可能把错误的 GPG Key 添加到了 GitHub。
    • 解决方案2： 重新执行第 3 步，确保导出和添加的公钥是正确的。

恭喜你！你已经成功配置了 GPG 签名，从此你的每一次代码提交都有了官方认证，安全性和专业性都上了一个台阶！

Clone this wiki locally