首先使用pyproject.toml配置构建系统，再通过setuptools定义元数据，组织src目录结构并声明依赖，最后用build生成包、twine上传至PyPI。
如果您正在开发Python包并希望将其发布到PyPI或其他平台，但遇到打包失败或依赖项无法正确安装的问题，则可能是由于配置文件不完整或构建流程不符合标准。以下是根据Python官方文档整理的软件分发最佳实践步骤。
本文运行环境：MacBook Pro，macOS Sonoma
一、使用现代工具链进行打包
当前推荐的Python打包方式是使用setuptools配合pyproject.toml文件来声明构建系统和元数据，以确保兼容性和可维护性。
1、在项目根目录创建pyproject.toml文件，并指定构建后端为setuptools与wheel。
立即学习“Python免费学习笔记（深入）”；
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，按提示输入账户凭证。
