wheel 与 sdist 是什么
Python 两种分发形态：wheel（.whl）是预构建格式，安装时无需再编译；sdist（.tar.gz）是源码分发，安装时在目标环境执行构建步骤，容易受系统依赖与编译工具链影响。内部交付优先提供 wheel——把编译复杂度留在构建流水线，而不是部署机上。平台标签（如 manylinux）声明 wheel 兼容的 glibc 与平台范围。
基本信息
| wheel | 预构建格式，安装时无需编译（除非纯源码包标注） |
|---|---|
| sdist | 源码分发，安装时执行构建步骤 |
| 平台标签 | manylinux 等标签声明兼容的 glibc/平台范围 |
| 构建命令 | python -m build 一次生成两种产物 |
| 选择 | 内部交付优先 wheel；对外发布两者都提供 |
典型使用场景
- 部署加速：CI 构建 wheel 后分发，部署机只安装不编译
- 离线环境：预下载 wheel 及依赖，目标机无外网也能安装
- 跨平台交付：按目标平台构建对应标签的 wheel
- 缓存复用：wheel 进制品库，编译一次多处复用
- 兼容排查：安装失败先看平台标签与环境是否匹配
- 源码审计：需要审查构建内容时保留 sdist
构建与安装
构建与安装
python -m build # 一次生成 dist/*.whl 与 *.tar.gz
pip wheel . -w dist # 只构建 wheel 及其依赖的 wheel
pip install dist/app-1.9.0-py3-none-any.whl # 直接安装预构建包
pip install --no-index --find-links dist app # 离线从本地目录安装产物类型读法
| 产物 | 内容 | 安装时行为 |
|---|---|---|
| whl | 预构建归档 | 解包复制，无编译步骤 |
| tar.gz | 项目源码（sdist） | 先构建成 wheel 再安装 |
| 平台标签 | 兼容范围声明 | 标签不符则安装被拒 |
| py3-none-any | 纯 Python 通用包 | 任何平台可装 |
内部交付优先提供 wheel：把编译复杂度留在构建流水线，而不是部署机上。
manylinux 标签决定兼容边界：目标机 glibc 过老会装不上，构建镜像按最老的目标环境选。
wheel 与 sdist 成对保留：前者供安装，后者供审计，制品库按发布版本归档。
离线安装顺序：依赖 wheel 与主包一次给全，安装时指定本地目录，避免中途缺件。
团队协作
- 私有索引：wheel 发布到内部索引，团队按版本安装复用