pip 访问私有 IP 索引，报 check_hostname requires server_hostname

使用 https:// 加 IP 地址的私有包索引时，pip 在握手阶段抛出 ValueError: check_hostname requires server_hostname。先保留完整异常链，区分 TLS 调用缺少服务器身份参数，与证书链本身不被信任的错误。

pip 24.2、24.3 的一条旧故障路径涉及 IP 地址、系统证书信任接口与 pip 内置的 HTTP 库。相关修复已进入 pip 26.1；本文不是建议所有 HTTPS 错误都靠升级消失，也不把关闭验证作为下载私有依赖的处理办法。

确认运行版本和实际请求路径

在失败项目使用的解释器中检查：

python -m pip --version
python -c 'import sys; print(sys.executable); print(sys.version)'

核对索引 URL 是否用了 IP、是否经过 HTTP 或 HTTPS 代理、现有 CA 配置，以及栈中是否经过 pip/_vendor/urllib3、truststore 和 ssl.wrap_socket。日志中的 server_hostname 是 TLS 接口参数，不是让你在普通 pip 命令后随便添加一个同名选项。

对外分享日志前隐藏索引凭据、代理认证和内部路径。检查应保持原网络入口，不能拿公共 PyPI 的成功证明私有 IP 路径已经正常，也不能为了对照将带认证的请求改发到其他服务。

如果错误是 CERTIFICATE_VERIFY_FAILED，程序已经在做另一类校验，应检查 CA、证书链、有效期及访问身份。只把两种报错都称为“证书问题”，会让处理步骤失去针对性。

修复 pip 的内置传输库路径

在受支持的项目 Python 环境里，按项目既有工具管理流程评估兼容的正式 pip 版本。以 pip 26.2.1 为例，要求 Python 至少为 3.10；旧 Python 环境不能盲目安装这版，应先确定受支持的环境迁移与工具组合。

当前内置传输实现会将 IP 对应的 server_hostname 继续传给 TLS 包装接口，避免旧路径中仅依靠关闭 hostname checking 的处理。升级后仍应核对真正执行的 pip，而不是只看到安装命令曾经返回成功。

给应用安装一个普通的新版 urllib3，通常不会替换 pip 自己 vendored 的库。不要在 pip 安装目录里手改源码，也不要把曾经用于诊断的 legacy-certs 开关写成每个私有索引的默认方案。

工具升级修复的是这条旧调用路径。当前版本仍报同样异常时，需要重新检查完整栈、代理隧道和自定义 SSL 配置，不能仅凭相同错误文字断定又是旧问题。

私有 CA 与访问身份仍然要正确

在 Python 3.10 及以上，pip 24.2 起默认将系统证书与 certifi 一起用于验证。系统尚未配置私有 CA 时，也可以按现有组织规则，通过 --cert 或 PIP_CERT 指定已核实的 CA bundle；这些配置选择信任材料，不会自动关闭服务器身份验证。

用 IP 访问时，服务端证书需要与实际访问的 IP 身份匹配。证书只覆盖域名、已经过期或链不完整，不能靠增加一个无关 CA 修复。若服务本来设计为域名入口，应按实际 DNS 和证书配置访问该入口，不为消除错误随意换域名。

私有 CA 应从已确认的管理渠道取得。不要把 trusted-host、HTTP 索引或禁用验证留在最终配置中，再把下载成功当作安全连接已恢复。

保存原工具版本、索引与 CA 配置，在独立可重建环境先验证原私有来源、正常证书校验和原依赖安装，再运行应用需要的功能。回退时恢复相应工具与配置组合；恢复文本不会自动撤销环境里已下载、安装的包。若通过 HTTPS 代理且错误发生在代理连接，应另外区分代理 CA 与目标 CA。