这不是 bug，是 pip 在严格执行现代 Python 包构建规范；多数情况下，不用跳过 PEP 517，而是补全环境或换安装方式。
直接说结论：这不是 bug，是 pip 在严格执行现代 Python 包构建规范；多数情况下，不用跳过 PEP 517，而是补全环境或换安装方式。
为什么 pip 会卡在 "Building wheel for xxx (PEP 517)"？
PEP 517 是 Python 官方定义的构建接口标准。当包的 pyproject.toml 明确指定了构建后端（比如 setuptools.build_meta 或 hatchling.build），pip 就必须走这个流程——它不再允许用旧式 setup.py 直接构建。
报错本质不是“PEP 517 本身错了”，而是本地缺少该流程依赖的某个环节：
- 编译工具链缺失（Windows 缺 MSVC Build Tools，Linux 缺
build-essential，macOS 缺 Xcode Command Line Tools） - Python 开发头文件未安装（如
python3-dev或python-dev） -
pip、setuptools、wheel版本太旧，不支持包声明的构建要求 - 磁盘路径过长（尤其 Windows），导致写入临时 build 目录失败
先升级基础工具，再试安装
很多报错其实只是 pip 和构建工具太老。执行这两条命令基本能解决一半问题：
立即学习“Python免费学习笔记（深入）”；
python -m pip install --upgrade pip setuptools wheel
注意：pip install --upgrade pip 单独运行有时不生效，推荐用 python -m pip 方式确保调用的是当前环境的 pip。
升级后重试原命令，例如：
pip install numpy
如果仍失败，再往下排查。
按系统补全编译依赖
不同系统需要的底层组件不同，缺哪个就装哪个：
- Windows：安装 Microsoft C++ Build Tools，勾选 “CMake tools” 和 “Windows 10/11 SDK”
- Ubuntu/Debian：
sudo apt-get install build-essential python3-dev libssl-dev libffi-dev - CentOS/RHEL：
sudo yum groupinstall "Development Tools" && sudo yum install python3-devel openssl-devel libffi-devel - macOS：
xcode-select --install，再运行sudo xcode-select --reset
装完别忘了重启终端，让环境变量生效。
什么时候可以安全地跳过 PEP 517？
只有在确认包提供预编译 wheel、且你不需要源码定制时，才考虑用 --no-use-pep517：
pip install numpy --no-use-pep517
但要注意：
- 这个 flag 对纯 Python 包（如
requests）基本无效，因为它们本来就不需要编译 - 对
cryptography、numpy、opencv-python这类含 C 扩展的包，跳过 PEP 517 只是绕开编译，实际仍会尝试下载对应平台的 wheel——如果网络或镜像源没同步好，反而更易失败 - 某些包（如 PyCaret 依赖的
scikit-learn）在 Windows 上因路径长度限制崩溃，此时启用长路径支持（LongPathsEnabled=1）比禁用 PEP 517 更治本
真正难搞的从来不是 PEP 517 本身，而是它把原本被 pip 隐藏的构建依赖，赤裸裸地暴露了出来——你得直面编译环境、Python 版本、CUDA 工具链这些真实约束。
