Python Academy · 课时

使用 build 构建

创建 wheel 和 sdist

使用 build 构建 是 CoddyKit 上的免费 Python Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Python Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Python Academy 课程共包含 4 节课。

构建意味着什么

您的源代码必须转换成 pip 可以安装的分发产物。现代工具是 build，运行方式为 python -m build。

它会生成两种文件：源代码分发包和预构建分发包。

源代码分发包与预构建分发包

两种产物类型：

源代码分发包（.tar.gz）：源代码归档；pip 会在安装时构建它
预构建分发包（.whl）：预构建归档；pip 只需将其解包

预构建分发包安装更快，也更受欢迎。源代码分发包是后备方案，也是规范的源代码来源。

安装构建工具

使用 pip install build 安装一次即可。它是一个轻量级前端：读取您的 pyproject.toml，设置隔离环境，然后调用构建后端来创建产物。

您不需要直接调用后端；build 会负责协调这一过程。

执行构建

请在项目根目录中运行 python -m build。默认情况下，它会同时生成源代码分发包和预构建分发包，并将它们放入新的 dist/ 目录。

使用 --wheel 或 --sdist 可以只构建其中一种。

args = []
targets = []
if '--sdist' in args:
    targets.append('sdist')
if '--wheel' in args:
    targets.append('wheel')
if not targets:
    targets = ['sdist', 'wheel']
print('Will build:', targets)

分发包文件名

分发包名称会编码元数据：mytool-0.1.0-py3-none-any.whl 表示名称为 mytool、版本为 0.1.0、使用 Python 3、不需要 ABI、适用于任何平台。纯 Python 包会获得 py3-none-any。

name = 'mytool'
version = '0.1.0'
wheel = name + '-' + version + '-py3-none-any.whl'
print(wheel)
print('Parts:', wheel[:-4].split('-'))

构建隔离

默认情况下，build 会创建一个全新的虚拟环境，安装 [build-system] 中的 requires，并在其中构建。这可以确保构建不会意外依赖当前环境中恰好存在的包。

检查 dist 文件夹

构建完成后，dist/ 中会包含您的产物。上传前列出其中的内容，可以确认实际生成了什么。这只是普通的目录列表操作。

dist = ['mytool-0.1.0.tar.gz', 'mytool-0.1.0-py3-none-any.whl']
for f in dist:
    kind = 'sdist' if f.endswith('.tar.gz') else 'wheel'
    print(kind.ljust(6), f)

检查分发包

分发包实际上只是一个 ZIP 归档。您可以将其解压，以确认模块和数据文件都存在，并检查是否遗漏了重要内容。如果某个文件在这里缺失，安装后也会缺失。

清理构建

build/ 或 dist/ 中的过时文件可能会产生令人困惑的结果。发布构建前请删除这些目录，这样发布的内容就完全是当前源代码生成的内容。

stale_dirs = ['build', 'dist', 'mytool.egg-info']
for d in stale_dirs:
    print('Remove before clean build:', d)

可复现构建

同一份源代码应始终构建出相同的产物。请在 [build-system] requires 中固定构建后端的版本，并避免从当前运行环境读取值。可复现性意味着团队成员或持续集成服务器得到的输出完全一致。

再结合清理构建，就能消除“在我的机器上能运行”这类意外。

在持续集成中构建

多数项目在持续集成服务器上而不是笔记本电脑上构建。持续集成任务会检出代码、运行 python -m build 并保存产物。这样可以确保每次发布都来自已知且干净的状态。

您在本地运行的完全相同的命令也会在持续集成中运行。

快速检查

测试您对构建的了解。

回顾

您已经学会构建产物：

使用 pip install build 安装工具，然后运行 python -m build
在 dist/ 中生成源代码分发包（.tar.gz）和预构建分发包（.whl）
使用 [build-system] 中的 requires，在隔离环境中完成构建
发布前检查分发包并执行清理构建

常见问题解答

「使用 build 构建」课时是免费的吗？

是的 — 「使用 build 构建」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Python Academy 课程的其余内容，请升级到 CoddyKit PRO。 Python Academy 课程共包含 4 节课。

「使用 build 构建」这节课中我会学到什么？

创建 wheel 和 sdist 你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Python Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Python Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「使用 build 构建」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Python Academy 课中编写并运行代码吗？

能。每节 Python Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Python Academy