这不是你代码或命令写错了，而是pip在尝试从源码编译时卡住了——要么没wheel可下，要么你机器缺编译工具、头文件或构建依赖。
直接说结论：这不是你代码或命令写错了，而是 pip 在尝试从源码编译时卡住了——要么没 wheel 可下，要么你机器缺编译工具、头文件或构建依赖。
为什么 pip 一定要 build wheel？
pip 默认优先下载 .whl（预编译二进制包），找不到才退回到源码（.tar.gz）并本地编译。一旦触发编译，就得有对应平台的编译链、Python 头文件、C/C++ 扩展依赖库（比如 libxml2-dev、cuda.h）。很多报错其实就卡在这一步。
- Windows 上常见缺失
Microsoft Visual C++ Build Tools或Windows SDK - Linux（如 Ubuntu/Debian）缺
build-essential、python3-dev、libxml2-dev等 - macOS 缺
Xcode Command Line Tools（xcode-select --install） - 某些包（如
mmcv-full、pyarrow）还强依赖 CUDA 版本或特定 Python 小版本（比如只支持cp310，你用的是cp311）
先试试不编译：强制用预编译 wheel
不是所有包都必须从源码装。多数主流包（numpy、pillow、lxml）在 PyPI 或第三方源都有大量预编译 .whl。别急着升级工具链，先确认有没有现成的可用。
- 运行
pip debug --verbose查看你的平台标签（比如cp310-cp310-win_amd64），再上 PyPI 对应包页 或 Gohlke 镜像站 手动核对是否有匹配的.whl - 如果确定有但 pip 没选中，加
--only-binary=all强制跳过源码：pip install --only-binary=all numpy - 国内用户可换源（如清华、中科大）提升命中率：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ numpy
必须编译时：检查三个关键依赖项
当你明确需要从源码构建（比如装 mmcv-full 或自定义 CUDA 版本），光升级 pip 不够，得确保底层三件套齐备：
-
wheel包本身必须存在：pip install wheel（不是可选，是构建流程硬依赖） -
setuptools版本不能太老（2026 年很多新pyproject.toml要求 ≥60）：pip install --upgrade setuptools - 系统级构建工具链完整：Ubuntu 运行
sudo apt install build-essential python3-dev；Windows 安装Build Tools for Visual Studio并勾选 “C++ build tools” 和 “Windows 10/11 SDK”
漏掉任意一个，ERROR: Failed to build installable wheels for some pyproject.toml based projects 就会反复出现，且错误日志里往往藏了真实线索（比如 fatal error C1083: Cannot open include file: 'Python.h' 就是缺 python3-dev）。
pyproject.toml 项目绕不开的坑
如果你是在 pip install -e . 一个本地项目，或装某个基于 pyproject.toml 的包（如 multidict、aiohttp），注意它可能用了 PEP 517 构建后端（如 setuptools、flit），而旧版 pip 默认不启用该协议。
- 显式启用：
pip install --use-pep517 your-package - 或者先升级到 pip ≥21.3：
pip install --upgrade pip - 更稳妥的做法是进干净虚拟环境：
python -m venv venv && source venv/bin/activate（Linux/macOS）或venv\Scripts\activate（Windows），再重装
复杂点在于：有些包的 pyproject.toml 里写的 requires = ["setuptools>=42"] 看似宽松，但实际构建时可能偷偷要求 setuptools>=68 —— 这类隐式版本冲突不会直接报错，只会让 wheel 构建静默失败。
