# 错误：无法为 <package> 构建 wheel，这是安装基于 pyproject.toml 的项目所必需的

- **ID:** `python/pip-could-not-build-wheels-required-to-install-pyproject`
- **领域:** python
- **类别:** install_error
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

包使用 PEP 517，pip 必须构建 wheel，但 wheel 构建失败——通常由于缺少 C 工具链、缺少头文件（如 libssl-dev），或 C 扩展中的编译器错误。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| 3.9 | active | — | — |
| 3.10 | active | — | — |
| 3.11 | active | — | — |
| 3.12 | active | — | — |

## 解决方案

1. **** (80% 成功率)
   ```
   # Debian/Ubuntu
sudo apt-get install -y build-essential python3-dev libssl-dev libffi-dev
# macOS
brew install openssl@3
pip install <package>
   ```
2. **** (75% 成功率)
   ```
   pip install --only-binary=:all: <package>
# fallback: download from https://pypi.org/project/<package>/#files
   ```

## 无效尝试

- **** — Cache is not the issue; the compile step fails every time. (90% 失败率)
- **** — Pre-releases rarely ship wheels for every platform; the compile still fails. (80% 失败率)