Python打包分发指南与实战方法

本文系统梳理了Python官方推荐的现代打包与分发全流程，从配置pyproject.toml、组织标准src目录结构、精准声明依赖（含可选依赖），到使用build生成跨平台源码包（sdist）和高效轮子包（wheel），最后通过twine安全上传至PyPI——每一步均紧扣PEP 517/518标准，直击开发者在发布包时常见的配置缺失、依赖不生效、打包失败等痛点，助你一次构建成功、合规发布。

如果您正在开发Python包并希望将其发布到PyPI或其他平台，但遇到打包失败或依赖项无法正确安装的问题，则可能是由于配置文件不完整或构建流程不符合标准。以下是根据Python官方文档整理的软件分发最佳实践步骤。

本文运行环境：MacBook Pro，macOS Sonoma

一、使用现代工具链进行打包

当前推荐的Python打包方式是使用setuptools配合pyproject.toml文件来声明构建系统和元数据，以确保兼容性和可维护性。

1、在项目根目录创建pyproject.toml文件，并指定构建后端为setuptools与wheel。

2、在文件中添加build-system字段，内容如下：

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

二、编写setup.py与setup.cfg（可选）

虽然pyproject.toml可以完全替代传统配置，但在某些复杂场景下仍需使用setup.py来自定义构建逻辑。

1、创建setup.py文件，并导入setuptools.setup()函数。

2、调用setup()函数时传入必要的参数，如名称、版本、作者、描述、包含的包列表等。

3、若使用setup.cfg，则将所有静态元数据写入该INI格式文件，保持代码简洁。

三、组织项目结构

合理的目录结构有助于自动化工具识别源码和资源文件，避免遗漏或错误打包。

1、采用标准结构：src/your_package_name/存放模块代码，外部测试和文档独立放置。

2、在setup.py或pyproject.toml中设置package_dir映射源路径。

3、通过find_packages(where="src")自动发现所有子包。

四、管理依赖关系

准确声明依赖项可防止用户环境缺失关键库，同时避免版本冲突。

1、在pyproject.toml中的project表下添加dependencies数组。

2、列出运行时所需的所有第三方包及其版本约束，例如"requests>=2.25.0"。

3、使用optional-dependencies定义可选功能组，如开发、测试或文档构建依赖。

五、生成源分发与轮子包

源分发（sdist）适用于跨平台安装，而轮子包（wheel）提供更快的安装速度和预编译支持。

1、安装build工具：pip install build。

2、执行命令python -m build，该命令会同时生成.tar.gz源包和.whl轮子包。

3、输出文件位于dist/目录，可用于本地测试或上传至仓库。

六、上传到PyPI

通过Twine工具上传包能保证传输安全，并支持签名验证。

1、安装twine：pip install twine。

2、运行twine check dist/*检查包文件的格式合规性。

3、使用twine upload dist/*推送所有文件到PyPI，按提示输入账户凭证。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~