根本原因是pip调用git时SSH Agent未生效或密钥未加载：需确保ssh-agent运行、ssh-add添加私钥、SSH_AUTH_SOCK环境变量有效、Git URL含ssh://前缀且私钥权限为600。
pip install 时 Git 报错 “Permission denied (publickey)” 怎么办
根本原因不是 pip 本身不支持 SSH，而是 pip 调用 git 命令时，底层 Git 进程没读到你的私钥。常见错误现象包括：Permission denied (publickey)、fatal: Could not read from remote repository，哪怕 git clone git@github.com:user/repo.git 在终端能成功，pip install -e git+ssh://git@github.com:user/repo.git@main#egg=package 仍可能失败——因为 pip 可能以不同环境或用户身份执行 Git。
确保 SSH Agent 正在运行且密钥已加载
这是最常被跳过的一步。pip 启动的子进程依赖系统级 SSH Agent，不是你当前 shell 的临时配置。
- 运行
eval $(ssh-agent -s)启动 agent（如果还没启动） - 用
ssh-add -l检查密钥是否已列出；没看到？执行ssh-add ~/.ssh/id_rsa（替换成你实际的私钥路径） - 关键：确认
SSH_AUTH_SOCK环境变量在 pip 执行时依然有效。某些 IDE 或 CI 环境会清空它，可在安装前加一句echo $SSH_AUTH_SOCK验证
使用正确的 pip Git URL 格式（别漏掉 ssh://）
Git URL 格式不对会导致 pip 回退到 HTTPS 协议，或解析失败。必须显式使用 ssh:// 前缀，且域名前不能带 git@（那是 shell 命令语法，不是 URL）。
- ✅ 正确：
pip install git+ssh://git@github.com:user/repo.git@v1.0.0#subdirectory=src - ❌ 错误：
pip install git+git@github.com:user/repo.git（缺少ssh://，pip 会报Invalid URL） - ❌ 错误：
pip install git+https://github.com/user/repo.git（走 HTTPS，不会用 SSH 密钥）
注意：如果私钥有密码，SSH Agent 会在首次 ssh-add 时要求输入一次，之后 pip 调用就无需重复输。
立即学习“Python免费学习笔记（深入）”；
CI/CD 或 Docker 中的特殊处理
本地 OK 但 CI 失败？大概率是环境隔离导致 SSH Agent 不可用或密钥未注入。
- Docker 构建中：不要用
ssh-agent bash -c 'ssh-add key && pip install ...'这种写法——子 shell 退出后 agent 就没了。改用ssh-agent sh -c 'ssh-add /tmp/id_rsa && pip install ...'并确保/tmp/id_rsa权限为600 - GitHub Actions：用
webfactory/ssh-agentaction 注入，再确认pip步骤和 agent 在同一 job、同一 runner - 密钥权限：Git 要求私钥文件权限 ≤
600，否则直接拒绝读取，错误信息可能只显示Warning: Permanently added ...后静默失败
真正卡住的地方往往不是 pip 配置，而是 SSH 上下文传递断裂——agent 是否存活、密钥是否加载、权限是否正确、URL 是否合规，四者缺一不可。
