Python 项目打包发布完整指南
本文介绍如何将开发完成的 Python 项目打包成可分发的格式，并上传至 Python 包索引（PyPI），以便他人通过 pip 安装使用。
1. 环境准备
首先确保本地安装了最新版本的 pip，以避免构建过程中的兼容性问题。
# Unix/macOS
python3 -m pip install --upgrade pip
# Windows
py -m pip install --upgrade pip
建议创建一个独立的虚拟环境进行开发和打包，避免污染全局环境。
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
2. 项目结构
推荐使用 src 布局来组织项目，这有助于隔离包代码与测试代码，减少导入错误。
packaging_tutorial/
└── src/
└── example_package_YOUR_USERNAME_HERE/
├── __init__.py
└── example.py
- init.py：将目录识别为包。即使为空也需保留。
- example.py：包含核心逻辑的模块文件。
示例 example.py 内容：
def add_one(number):
"""返回输入数字加一的结果"""
return number + 1
3. 配置元数据 (pyproject.toml)
现代 Python 项目推荐使用 pyproject.toml 替代传统的 setup.py。该文件定义了项目的依赖、元数据和构建后端。
3.1 选择构建后端
常见的构建后端包括 hatchling, setuptools, flit_core 等。以下以 hatchling 为例：
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
3.2 定义项目信息
在 pyproject.toml 中添加 [project] 部分：
[project]
=
=
=
=
=
= [
{ name=, email= },
]
= [
,
,
,
]
=
=
