Python 环境问题：pip 安装包时出现 SSL 证书错误

在使用 Python 进行开发时，通过 pip 安装第三方库是最常见的操作。然而，网络环境复杂或系统配置不当常会导致安装失败，其中 SSL: CERTIFICATE_VERIFY_FAILED 是最令人头疼的错误之一。这通常表现为连接超时或证书验证不通过。

本指南将提供一套从“临时解决”到“彻底修复”的完整方案，适用于 Windows、macOS 及 Linux 系统。

方案一：使用国内镜像源加速（推荐首选）

绝大多数 SSL 错误是由网络连接不稳定或国外官方源响应慢导致的。切换到国内镜像源不仅能解决大部分连接问题，还能显著提升下载速度。

1. 打开 终端（Windows 用户打开 CMD 或 PowerShell，Mac/Linux 用户打开 Terminal）。

2. 执行 以下命令格式，将 <package_name> 替换为你需要安装的包名。

   pip install <package_name> -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 如果上述命令提示 SSL 错误，请尝试信任镜像源主机（仅用于解决镜像源连接时的证书问题）：

   pip install <package_name> -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

常用的国内稳定镜像源如下表所示，可随时替换使用。

方案二：全局信任主机（临时绕过验证）

如果切换镜像源后依然报错，或者你必须使用官方源，可以通过添加参数临时关闭 SSL 证书验证。这是一种“暴力”但有效的临时方案。

1. 输入 以下命令进行安装：

   pip install <package_name> --trusted-host pypi.org --trusted-host files.pythonhosted.org

2. 若上述命令无效，尝试 同时信任 pypi.python.org：

   pip install <package_name> --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org

方案三：检查系统时间（根本原因排查）

SSL 证书具有有效期。如果计算机系统时间与实际时间偏差过大，会导致证书被系统判定为“无效”或“过期”，从而引发验证失败。

1. 查看 屏幕右下角（Windows）或顶部状态栏的系统时间。
2. 确认 当前日期和年份是否正确。例如，如果当前是 2023 年，而系统时间显示为 2015 年，SSL 验证必然失败。
3. 调整 系统时间至正确时区与日期。
   • Windows：右键点击时间，选择“调整日期/时间”，开启“自动设置时间”。
   • macOS：进入 系统偏好设置 -> 日期与时间 -> 点击锁图标解锁 -> 勾选“自动设置日期和时间”。
   • Linux：执行 timedatectl set-ntp true 命令。

方案四：更新 pip 版本（修复旧版 Bug）

旧版本的 pip 可能存在 SSL 处理逻辑的缺陷或内置证书库过旧。升级 pip 自身往往能修复此类底层问题。

1. 运行 以下命令尝试升级 pip。如果当前 pip 无法使用，请使用 Python 模块调用方式。

   python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 升级完成后，重新尝试 安装目标包。

方案五：针对 macOS 系统的特殊修复

如果你使用的是 macOS，且 Python 是通过官网安装包安装的（非 Homebrew），系统可能未自动安装根证书，导致无法验证 HTTPS 连接。

1. 打开 访达。
2. 进入 应用程序文件夹，找到 Python 3.x 文件夹（3.x 代表你的版本号，如 Python 3.9）。
3. 双击 运行文件夹内的 Install Certificates.command 文件。
4. 等待 弹出的终端窗口自动执行完毕并显示 close 或自动关闭。
5. 重新执行 pip 安装命令。

方案六：解决企业内网代理拦截（高级场景）

在公司网络环境下，防火墙或代理设备可能会拦截 HTTPS 请求并重新签发证书。由于系统不信任该证书，pip 安装会失败。

1. 获取 公司 IT 部门提供的根证书文件（通常为 .crt 或 .pem 格式）。

2. 执行 pip 命令时指定该证书文件路径：

   pip install <package_name> --cert /path/to/your/corporate_cert.crt

3. 若不想每次都指定证书，设置 环境变量 REQUESTS_CA_BUNDLE 指向证书文件路径。

   • Windows (PowerShell)：

     $env:REQUESTS_CA_BUNDLE="C:\path\to\corporate_cert.crt"

   • Linux/macOS：

     export REQUESTS_CA_BUNDLE=/path/to/corporate_cert.crt

方案七：处理 Python 源码编译安装的 SSL 模块缺失

如果你在 Linux 上通过源码编译安装 Python，且编译时系统缺少 OpenSSL 开发包，Python 的 ssl 模块将不可用，导致 pip 完全无法工作。

1. 验证 ssl 模块是否存在。输入 python 进入交互模式：

   import ssl

2. 若报错 No module named _ssl，说明需要重新编译 Python。

3. 退出 Python 交互模式（exit()）。

4. 安装 系统依赖（以 Ubuntu/Debian 为例）：

   sudo apt-get install libssl-dev libffi-dev

   （CentOS/RHEL 用户请执行 sudo yum install openssl-devel libffi-devel）

5. 进入 Python 源码解压目录，重新编译 并安装：

   ./configure --with-openssl=/usr/local/ssl
   make
   sudo make install