pip install 在代理下失败？超时、407 与证书错误排查

浏览器能访问网站，pip install 却超时或报证书错误，先核对 pip 实际使用的 Python、代理入口和包索引。连接超时、407 代理认证和 HTTPS 证书校验属于不同环节，换节点或增加超时时间不能同时解决它们。先做一次不安装软件的索引查询，再按完整错误继续定位。

作者：小仓｜资料核对日期：2026-10-11

先保留完整错误，不只看最后一行

日志中的线索	优先检查	不宜直接下的结论
Connection refused	指定地址是否有代理监听	不能仅凭这一行判定远端节点故障
ConnectTimeout、ReadTimeout	超时发生的地址与连接阶段	超时不等于缺少 CA
407 Proxy Authentication Required	代理的认证要求	不是 PyPI 账户密码错误的同义词
CERTIFICATE_VERIFY_FAILED	TLS 名称、证书链与信任来源	不应先把校验关掉
No matching distribution found	前面是否已有网络失败，随后才查包与 Python 兼容性	最后一行不能单独证明包不存在

记录首次异常、失败主机和前后的重试信息。日志若显示本机端口就连接失败，先修复本机入口；若已经查询成功、失败出现在构建依赖阶段，则保留那一阶段的单独输出。

在项目平时安装依赖的终端中运行：

python --version
python -m pip --version
python -m pip config debug
python -m pip config list

python -m pip 使用这里指定的解释器；同时保留 pip 输出的安装路径，避免把系统 Python 的配置与虚拟环境混在一起。Windows 若平时使用 py，应先确定它选择的解释器，不能假设它与 IDE 项目环境一致。pip 用户指南说明了模块调用方式。

config debug 用来列出配置文件及其中的值，config list 查看配置；它们不会替你保证代理可达，具体功能见 pip config 文档。输出可能含代理账号或私有索引凭据，留在本机核对，分享时只保留脱敏后的地址与配置来源。

重点找 proxy、index-url、extra-index-url、cert 和 trusted-host，并检查终端的代理环境变量。不要只看一个 pip.ini 就认定它生效：pip 选项通常按命令行、环境变量、配置文件的顺序覆盖，文件内还有命令专属项，见配置优先级。

官方代理指南列出了 --proxy、配置文件以及 http_proxy、https_proxy、no_proxy 等方式。如果项目终端从 IDE 启动，修改另一窗口中的变量后，应回到项目终端核对，不能默认两个进程拿到了同一配置。

从客户端界面确认 HTTP 或兼容 HTTP 的混合入口、监听地址和实际端口。下面的 7890 是示例，必须替换；若你只有 SOCKS 入口，不要给它强加 HTTP 协议。

python -m pip index versions pip --proxy http://127.0.0.1:7890 --index-url https://pypi.org/simple --no-cache-dir

这条命令查询包索引信息，不安装包，命令用途见 pip index 文档。示例适用于需要访问公共 PyPI 的环境；使用公司私有索引时，应保持获准的目标地址，并核对是否还有额外索引，不把测试误变成更换软件来源。

--no-cache-dir 在本次调用禁用缓存，使对照更容易解释；结果仍不能保证安装时访问的包文件主机、构建依赖或其他服务全部可达。旧环境不支持某个参数时，先查看同一解释器下的 python -m pip index --help。

不一定。代理 URL 的 http:// 描述连接代理入口的协议，不是目标网站的协议。HTTP 代理可以通过 CONNECT 为 HTTPS 目标建立隧道；https:// 则要求先与代理建立 TLS。机制见 urllib3 的代理说明。入口协议填错时，增加重试并不会让它变成另一种代理。

本机入口还不确定，可先阅读本站 Windows 终端代理排查。容器或 WSL 中的 127.0.0.1 也不能未经核对就当成 Windows 主机。

407 表示这次请求需要向代理认证，区别于目标资源的 401，定义见 RFC 9110 第 15.5.8 节。应确认报错的是本地入口、上游代理还是企业网关，并向该代理的管理员核对认证方式。

不要把机场订阅链接、节点密钥或 PyPI 令牌直接填进代理密码栏。它们不是同一套凭据。即使允许在代理 URL 中带用户名密码，也要避免在共享脚本、终端历史和截图里留下明文；本文的示例使用无凭据地址。

若公司网关进行 HTTPS 检查，浏览器与 pip 使用的信任来源可能不同。先核对证书签发者、访问名称和本机时间，再向管理员取得经过确认的 CA，不导入报错页面或聊天链接随手提供的证书。通用检查可参考 TLS 证书排障。

pip 的 24.2 变更记录说明，在 Python 3.10 及以上环境，默认校验加入系统证书与 certifi；更早的 pip 不能直接套用这一默认行为。因此反馈时必须同时给出 Python 和 pip 版本。

确需指定 CA 时，使用官方支持的 --cert 或 PIP_CERT，指向经过核对的 PEM CA 集合；不要将服务器叶子证书或含私钥的文件随意当作 CA 集合。具体证书来源与行为见 pip HTTPS 证书文档。

--trusted-host 允许信任没有有效 HTTPS 的主机，它不会修复证书链。该参数的定义见 pip 通用选项。不建议把它作为公共包索引证书报错的默认修复。

只改变一个条件后重复同一查询。查询通过，再回到原项目安装过程；若仍失败，记录新的失败主机与阶段，不能把索引成功写成“全部依赖下载正常”。本文没有执行节点测速，也不保证某条代理路径的速度。

系统、Python 版本、pip 版本与路径：
是否在虚拟环境、WSL 或容器内：
代理协议、地址、端口（不含凭据）：
索引地址（删除令牌）：
首个异常与失败主机：
证书签发者、CA 配置来源：
本次只改了什么、复测结果：