pip安装依赖时，浏览器能打开PyPI项目页并不能证明网络正常。pip通常访问“简单索引”接口，再下载由索引返回的Wheel或源码包；文件可能托管在另一个域名。加上用户级、全局和虚拟环境配置，问题很容易被误判成“Python版本不兼容”。
一、先看错误发生在哪个阶段
| 阶段 | 常见现象 | 检查方向 |
|---|---|---|
| 解析索引 | 找不到版本、连接超时 | index-url、DNS、代理与证书 |
| 下载包文件 | 重试、连接重置 | 真实文件域名、带宽与超时 |
| 校验或解包 | 哈希不匹配、文件损坏 | 缓存、完整性和存储 |
| 构建源码包 | 编译失败 | 构建工具链，不一定是网络 |
| 安装依赖 | 版本冲突 | requirements和解析器 |
二、pip有哪些代理入口
pip可通过命令行代理参数、常见环境变量或配置文件获取网络设置。临时诊断时使用命令参数边界清晰，但不要将带密码的参数留在Shell历史。长期配置应明确是计算机、用户还是虚拟环境范围，并查询当前生效配置。
三、index-url和proxy不是一回事
index-url决定从哪个Python包索引查询，proxy决定请求如何到达目标。更换镜像不等于启用代理；使用代理也不会自动把公共索引换成内部源。团队应分别管理包来源信任和网络出口。
四、requirements.txt不该包含什么
requirements文件适合记录包名、版本、来源和哈希约束，不应包含共享代理密码。若使用带令牌的私有源URL，还要防止它进入Git、构建日志和错误报告。优先通过CI秘密、凭据助手或权限受限的配置注入。
五、虚拟环境如何影响排查
虚拟环境改变Python与pip可执行文件位置，也可能有环境级pip配置，但它不等于独立网络空间。先运行python -m pip --version确认正在使用哪个pip，再查询配置来源。IDE、Notebook和系统服务可能使用另一解释器。
六、Python Requests能用，pip为什么仍失败
pip自身版本、证书包、缓存、索引协议和重试逻辑可能不同。一个Requests脚本访问出口检测页，只能证明该脚本路径可用，不能覆盖pip索引和包下载。Python客户端代理可参考Requests与HTTPX代理配置。
七、证书错误不要依赖trusted-host掩盖
证书不受信任应检查系统时间、Python及pip使用的CA、企业代理证书链和目标域名。将域名标记为可信或禁用校验会削弱HTTPS身份验证，可能掩盖中间证书缺失和错误代理。正式环境应修复CA。
详细步骤见TLS、SNI与系统时间排查。
八、407、401和找不到版本怎么区分
- 407：代理要求认证，检查代理凭据和机制；
- 401/403：私有索引认证或权限不足；
- No matching distribution：检查Python版本、平台标签、索引内容和版本约束；
- ReadTimeout：检查文件下载阶段、代理容量和超时；
- Hash mismatch：停止安装，核对来源、缓存和锁定哈希。
九、缓存会怎样影响结果
pip缓存可让重复安装绕过网络，也可能保留上次中断留下的问题线索。验证网络时应通过详细日志确认是否真正下载，不要在共享环境直接清空全部缓存。遇到哈希异常，应先隔离可疑文件并核对官方或私有源记录。
十、私有源和公共PyPI如何分流
企业可能要求内部源直连、公共源经代理，或完全由内部镜像代理公共包。应基于供应链策略选择，不要无审查地混用多个额外索引，因为同名包的来源优先级可能带来依赖混淆风险。
十一、排查清单
- 记录Python、pip和虚拟环境路径；
- 查看pip配置来源、索引与代理；
- 提取实际访问的索引和文件主机；
- 区分DNS、TCP、407、TLS和源401；
- 用一个已批准的小包做无缓存验证；
- 检查Wheel兼容、哈希和来源；
- 清理临时密码和详细日志。
十二、结论
pip代理排查应把包索引、文件下载、Python环境和证书信任分开。先确认实际pip和配置来源，再验证索引到文件托管的完整链路，才能避免用更换镜像掩盖真正的网络或供应链问题。
