怎么用python-mbuild构建分发包?
详细讲解如何使用官方推荐的 python -m build 命令构建 Python 分发包,包括 pyproject.toml 配置规范、源码包 (sdist) 与轮子包 (wheel) 构建步骤、构建隔离原理及常见问题排查。
python -m build 构建分发包的核心流程非常简单:在安装了官方构建前端 build 并在项目根目录编写好 pyproject.toml 配置文件后,只需在项目目录下执行 python -m build。该命令会自动拉起隔离的临时虚拟环境、下载构建后端依赖,并调用指定后端生成源码分发包(.tar.gz)与二进制轮子包(.whl),直接输出到 dist/ 目录。这一方案完全替代了传统且存在安全隐患的 python setup.py sdist bdist_wheel。
一、为什么现代 Python 打包推荐使用 build 工具?
在过去的 Python 打包生态中,开发者习惯通过直接执行 python setup.py sdist bdist_wheel 来生成安装包。但这种方式存在两个核心痛点:一是执行 setup.py 会直接运行用户项目中的任意 Python 代码,缺乏执行隔离;二是构建依赖无法在打包前自动解析并声明,安装环境容易与宿主环境发生冲突。
为了解决这些历史问题,Python 官方制定了 PEP 517 和 PEP 518 规范,将“构建前端”(Build Frontend)与“构建后端”(Build Backend)进行了解耦。build(即 PyPI 上的 build 库,通过 python -m build 调用)就是 Python 官方 Packaging Authority (PyPA) 维护的标准构建前端。它的核心价值在于:
- 自动隔离构建环境(Build Isolation):在临时虚拟环境中运行构建,避免本地残留包干扰构建结果。
- 统一配置文件:使用声明式的
pyproject.toml替代命令式的setup.py,规范项目元数据。 - 后端无关性:可以无缝配合 Hatchling、Flit、Setuptools、PDM 等任意符合 PEP 517 标准的后端使用。
二、构建前的环境准备与项目目录规范
在开始构建之前,第一步是确保当前 Python 环境中安装了 build 库。推荐在激活的虚拟环境中通过 pip 进行安装:
pip install build
一个规范的 Python 工程需要具备清晰的目录层次。目前社区普遍推荐采用 src/ 布局(src-layout),这种结构能彻底避免在项目根目录下测试时误导入本地尚未打包的代码,确保测试与分发的一致性。
my_project/
├── pyproject.toml # 核心配置文件(必须)
├── README.md # 项目长描述文档(推荐)
├── LICENSE # 开源许可证文件(推荐)
└── src/
└── my_package/ # 实际的 Python 包目录
├── __init__.py # 模块初始化
└── core.py # 业务逻辑代码
图 1:Python 标准项目结构与 python -m build 构建产物映射关系
三、核心配置文件 pyproject.toml 的编写
pyproject.toml 是现代 Python 打包的基石。在没有这个文件或文件缺少声明的情况下,python -m build 会报缺少构建配置错误。
该文件至少需要包含两个核心块:[build-system](指定由哪个构建后端负责执行打包)以及 [project](声明包名、版本号、作者和运行时依赖等元数据)。
以 Hatchling 为例的现代轻量配置
Hatchling 是当前官方推荐的快速、纯净的 PEP 517 构建后端,以下是标准完整的配置示例:
pyproject.toml 配置示例(采用 Hatchling 后端)[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my_sample_package"
version = "0.1.0"
description = "一个用于演示分发包构建的示例项目"
readme = "README.md"
requires-python = ">=3.8"
license = { text = "MIT" }
authors = [
{ name = "Developer", email = "dev@example.com" }
]
dependencies = [
"requests>=2.28.0",
]
[project.urls]
Homepage = "https://github.com/example/my_sample_package"
setuptools,也可以将 [build-system] 的 requires 设为 ["setuptools>=61.0", "wheel"],build-backend 设为 "setuptools.build_meta"。无论使用哪种后端,后续执行 python -m build 的命令与流程完全一致。
四、执行构建与常用命令参数详解
完成文件结构与 pyproject.toml 配置后,打开终端,切换到包含 pyproject.toml 的项目根目录下,执行核心构建命令。
python -m build
命令实际执行控制台输出(示例)
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
- hatchling
* Getting build dependencies for sdist...
* Building sdist...
* Building wheel from sdist
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
- hatchling
* Getting build dependencies for wheel...
* Building wheel...
Successfully built my_sample_package-0.1.0.tar.gz and my_sample_package-0.1.0-py3-none-any.whl
命令完成后,项目根目录下会自动生成一个 dist/ 文件夹,里面包含了两个成品分发包文件。
图 2:python -m build 隔离构建的核心执行步骤与状态流转
常用定制构建参数
根据不同的 CI/CD 流程或特殊环境需求,build 提供了若干实用参数:
-
仅构建源码包(--sdist 或 -s):
python -m build --sdist只生成.tar.gz源码分发包,不编译二进制轮子包。 -
仅构建二进制轮子包(--wheel 或 -w):
python -m build --wheel只生成.whl轮子包。 -
禁用环境隔离(--no-isolation 或 -n):
python -m build --no-isolation默认情况下build会在每次构建时创建独立的虚拟环境联网下载依赖。如果在断网、内网离线机房,或者宿主环境中已经安装好了所有构建后端,加上-n可以跳过创建临时环境和联网拉取依赖,大幅加快构建速度。 -
指定输出目录(--outdir 或 -o):
python -m build -o target_dir/将生成的分发包输出到指定目录,而不是默认的dist/。
五、分发包产物校验与差异对比
构建成功后,切忌盲目直接上传发布。需要验证 dist/ 目录中的包格式与元数据是否完备。
1. 源码包 (sdist) 与二进制包 (wheel) 的区别
python -m build 默认同时产出两种包,它们在分发和安装中分工不同:
图 3:sdist (源码分发包) 与 wheel (二进制轮子包) 关键维度对比矩阵
2. 检查包内文件完整性
可以无需解压直接查看打包产物内的文件列表,确认是否有核心源码被漏掉,或者不小心将本地虚拟环境、测试缓存等冗余文件打包进去:
查看源码包与轮子包内容(命令示例)# 查看源码包目录结构(Linux / macOS)
tar -tzf dist/my_sample_package-0.1.0.tar.gz
# 查看 wheel 包内文件列表
python -m zipfile -l dist/my_sample_package-0.1.0-py3-none-any.whl
3. 使用 twine 检查元数据合规性
利用 PyPI 官方上传工具 twine 的 check 命令,可以严格校验描述文本(README 的 Markdown 或 rST 语法)、许可证声明等是否符合 PyPI 的规范:
twine check dist/*
校验通过的输出(示例)
Checking dist/my_sample_package-0.1.0-py3-none-any.whl: PASSED
Checking dist/my_sample_package-0.1.0.tar.gz: PASSED
六、常见报错与排查指南
1. 报错:No module named build
原因:执行命令的当前 Python 解释器环境中尚未安装 build 库。
解决方法:确认当前终端是否激活了正确的虚拟环境,并执行 pip install build。
2. 构建隔离超时或 Connection timeout / ProxyError
原因:build 默认会建立全新的临时虚拟环境,并使用 pip 连接 PyPI 官方源下载 pyproject.toml 中声明的 requires 依赖。在网络受限环境或内网离线机房中容易超时。
解决方法:
先在本地环境通过镜像源或离线 wheel 安装好 hatchling(或对应后端),然后附加 --no-isolation(或简写 -n)参数进行构建:
python -m build --no-isolation
3. 打包后发现缺失静态文件或特定子包
原因:构建后端默认根据纯 Python 代码发现机制扫描。如果项目中包含 .json、.yaml、静态资源等非 .py 文件,需要明确在 pyproject.toml 中告知后端包含这些文件。
解决方法:例如在 Hatchling 中增加文件包含规则:
[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]
[tool.hatch.build.targets.sdist]
include = [
"/src",
"/README.md",
"/LICENSE",
]
七、完整生命周期总结速查
通过 python -m build,Python 分发包的制作已经完全摆脱了对动态执行 setup.py 的依赖,实现了标准、纯净且可复现的打包流程。
图 4:Python 包从开发、构建到发布的完整生命周期与命令速查
核心操作备忘表
| 操作任务 | 执行命令 | 适用场景与主要说明 |
|---|---|---|
| 环境初始化 | pip install build |
只需安装一次标准前端工具 |
| 标准全量构建 | python -m build |
在项目根目录下执行,生成 sdist 和 wheel |
| 仅生成轮子包 | python -m build --wheel |
内部服务快速部署或特定平台二进制构建 |
| 内网/离线构建 | python -m build -n |
跳过临时虚拟环境,直接使用当前环境依赖 |
| 产物合规检查 | twine check dist/* |
在上传 PyPI 前校验包元数据与描述渲染 |
| 本地试装验证 | pip install dist/*.whl |
在干净虚拟环境中验证导入和功能正常 |
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









