前言
默认情况下，pip 下载第三方Python库会访问国外PyPI官方服务器，国内服务器、本地电脑经常出现下载缓慢、超时失败、连接中断等问题。
通过切换国内镜像源，可以大幅提升下载速度，解决 ReadTimeoutError、连接超时等常见报错。
国内主流稳定镜像源清单：
本文覆盖：临时使用源、全局永久配置、多版本Python区分配置、配置文件手动编写、清除缓存、常见问题。同时兼容 Windows / Linux / MacOS。
一、临时使用镜像源（单次生效）
适合临时加速安装，只对当前这一条安装命令生效，不需要修改任何配置文件。
语法格式：
pip install 包名 -i 镜像地址
示例（使用清华源安装requests）：
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple
针对你服务器多版本Python场景（python39 / python312）：
# Python3.12
pip312 install requests -i https://pypi.tuna.tsinghua.edu.cn/simple
# Python3.9
pip39 install requests -i https://pypi.tuna.tsinghua.edu.cn/simple
二、全局永久配置pip国内源（推荐）
配置完成后，所有pip安装命令默认走国内镜像，无需每次加 -i 参数。
方式1：命令一键配置（最简单，pip 10.0+ 支持）
Linux / MacOS
# 配置清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
多Python版本注意：
如果你服务器存在多个Python，需要分别执行对应pip命令单独配置
pip312 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip39 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
Windows CMD/PowerShell
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
方式2：手动创建配置文件（兼容所有低版本pip）
Linux / MacOS
pip配置文件路径：~/.pip/pip.conf
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << EOF
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF
trusted-host 作用：关闭https证书校验，避免部分环境报ssl信任错误。
Windows系统
在用户目录下创建 pip 文件夹，新建 pip.ini
路径：C:\\Users\\你的用户名\\pip\\pip.ini
内容：
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
三、查看当前pip源配置
确认配置是否生效：
pip config list
# 多版本
pip312 config list
pip39 config list
输出包含index-url地址，代表配置成功。
四、恢复官方默认源
如果后续需要切回原始PyPI源，执行清除命令：
pip config unset global.index-url
# 指定版本
pip312 config unset global.index-url
或者直接删除配置文件
rm -rf ~/.pip/pip.conf
五、高级可选配置（优化下载体验）
扩展配置写入 pip.conf / pip.ini，增加超时时间、开启并发下载：
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 120
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
max-parallel-downloads = 8
参数说明：
- timeout：下载超时时间，弱网络服务器建议调高
- max-parallel-downloads：开启多包并行下载
六、常见问题解决
问题1：配置源之后依然下载很慢
pip cache purge
问题2：报错 Could not fetch URL xxx: There was a problem confirming the ssl certificate
解决方案：配置文件添加 trusted-host，上文模板已自带；
或者安装命令追加参数：–trusted-host pypi.tuna.tsinghua.edu.cn
问题3：多版本Python，只有一个pip生效
核心原因：不同Python拥有独立pip，必须分别使用 pip39 / pip312 各自执行config命令，不能只配置系统pip。
问题4：虚拟环境不继承全局源
正常现象，虚拟环境可以进入环境内部再次执行配置命令，或者把pip.conf放置到项目内。
七、备选镜像地址（源失效时切换）
清华源
https://pypi.tuna.tsinghua.edu.cn/simple
阿里云
https://mirrors.aliyun.com/pypi/simple
中科大源
https://pypi.mirrors.ustc.edu.cn/simple
总结
建议编译安装完Python3.12.10之后，立刻执行
pip312 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
避免后续安装第三方库出现超时问题。
