Git 拉取子模块报错 Permission denied (publickey) 的排查与解决

在 Linux 环境下拉取一个带子模块（submodule）的 GitHub 项目时，我遇到了一个典型但很影响进度的问题：主仓库可以正常 clone，但在初始化子模块时失败，提示 git@github.com: Permission denied (publickey)。

本文记录问题现象，并详细给出基于 SSH Key 的解决流程，希望能帮助遇到同样问题的开发者。

我先正常克隆项目主仓库：

bash 复制代码

git clone https://github.com/MisEty/RTG-SLAM.git
cd RTG-SLAM/

然后执行子模块初始化与递归更新：

bash 复制代码

git submodule update --init --recursive

此时 Git 会尝试拉取多个子模块，但全部在 clone 阶段失败，错误信息核心如下：

text 复制代码

git@github.com: Permission denied (publickey).
致命错误：无法读取远程仓库。
请确认您有正确的访问权限并且仓库存在。
致命错误：无法克隆 'git@github.com:...xxx.git' 到子模组路径 '...'

注意： 日志里子模块地址是 SSH 形式（git@github.com:xxx/yyy.git），不是 HTTPS。只要本机没有正确配置 GitHub 的 SSH Key，或者 Key 没有被 GitHub 账户授权，就会出现 publickey 权限拒绝。

这个报错的本质原因是：子模块仓库配置为使用 SSH 协议拉取 （即地址以 git@github.com 开头），但本机缺少可用的 SSH 私钥，或者没有把对应的公钥添加到 GitHub 账户中。因此，GitHub 服务器拒绝了连接认证。

适用前提：

你确实需要使用 SSH（例如仓库 .gitmodules 文件中硬编码了 SSH 地址），并且你对这些子模块仓库有访问权限（公开仓库或已授权的私有仓库）。

执行以下命令生成密钥对（如果不熟悉 RSA，推荐使用更现代的 ed25519 算法）：

bash 复制代码

ssh-keygen -t ed25519 -C "your_email@example.com"

执行后通常会提示输入保存路径与密码短语。一般一路回车使用默认即可，最终会在 ~/.ssh/ 下生成：

为了让 Git 能在当前会话里使用这把私钥，需要启动 ssh-agent 并添加 key：

bash 复制代码

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

如果执行成功，ssh-add 不会报错。你也可以通过以下命令确认 key 是否已加载：

bash 复制代码

ssh-add -l

能看到对应的 key 指纹信息就说明加载成功。

把公钥内容输出并复制：

bash 复制代码

cat ~/.ssh/id_ed25519.pub

然后登录 GitHub，进入：
Settings → SSH and GPG keys → New SSH key

把复制的公钥粘贴进去，取一个识别用的 Title（例如 "my-laptop" 或 "server-rtg-slam"），保存即可。

添加完后，建议立即测试 SSH 是否认证成功：

bash 复制代码

ssh -T git@github.com

正常情况下会出现类似提示（内容可能因账号不同略有差异）：

Hi xxx! You've successfully authenticated, but GitHub does not provide shell access.

看到这句话基本就说明 SSH Key 配置与授权已经完成。

回到仓库根目录，再执行一次：

bash 复制代码

git submodule update --init --recursive

此时 Git 应该会正常克隆各个子模块，不再出现 Permission denied (publickey)。