如何构建 Python 包 (2026版)¶

说明

本文更新于 2026 年，反映了 Python 打包生态的最新最佳实践。现在的核心是 pyproject.toml 标准化配置和高性能工具链 uv。不再推荐使用 setup.py 进行新项目的配置。

1. 核心概念：pyproject.toml¶

在过去（2020年以前），Python 项目通常依赖 setup.py 来定义元数据和构建过程。现在，社区已经全面转向 pyproject.toml。

pyproject.toml 是一个标准化的配置文件（PEP 518, PEP 621），它统一了以下内容： * 构建系统要求：告诉前端工具（如 pip, uv）使用哪个后端（如 hatchling, flit, setuptools）来构建项目。 * 项目元数据：名称、版本、作者、许可证、依赖等。 * 工具配置：Ruff (代码格式化), Pytest (测试), MyPy (类型检查) 等工具的配置都可以写在这里。

2. 推荐工具：uv¶

uv 是目前（2026年）最流行的 Python 项目管理工具。它由 Astral 团队（Ruff 的开发者）开发，使用 Rust 编写，以极致的速度著称。

uv 是一个“一体化”工具，它替代了以下工具的功能： * pip / pip-tools：依赖安装和解析 * poetry / pdm / flit：项目依赖管理和打包 * virtualenv / venv：虚拟环境管理 * pyenv：Python 版本管理（是的，uv 甚至可以帮你安装 Python） * twine：发布包到 PyPI

3. 实战流程：从零开始构建¶

下面演示如何使用 uv 创建、开发并发布一个 Python 包。

3.1 初始化项目¶

首先安装 uv (如果未安装):

curl -LsSf https://astral.sh/uv/install.sh | sh

初始化一个新库（library）：

uv init --lib my-awesome-pkg
cd my-awesome-pkg

生成的目录结构如下（推荐使用 src 布局）：

.
├── .gitignore
├── .python-version      # 锁定的 Python 版本
├── pyproject.toml       # 项目配置文件
├── README.md
├── src
│   └── my_awesome_pkg
│       ├── __init__.py
│       └── py.typed
└── uv.lock              # 依赖锁定文件（自动生成，勿手改）

3.2 依赖管理¶

不再需要手动维护 requirements.txt。

添加运行时依赖（用户安装你的包时会自动安装的库）：

uv add requests pydantic

添加开发依赖（仅开发时需要，如测试、文档工具）：

uv add --dev pytest mkdocs-material ruff

uv 会自动解析版本冲突，更新 pyproject.toml，并将精确的版本锁定在 uv.lock 文件中，确保团队协作时环境一致。

3.3 开发与测试¶

uv 会自动管理虚拟环境。你不需要手动激活它（虽然也可以）。

运行脚本或工具：

# 运行 pytest
uv run pytest

# 运行 Python 脚本
uv run python src/my_awesome_pkg/main.py

3.4 构建 (Build)¶

当准备发布时，需要构建源码包 (sdist) 和二进制包 (wheel)。

uv build

构建产物会生成在 dist/ 目录下： * my_awesome_pkg-0.1.0.tar.gz * my_awesome_pkg-0.1.0-py3-none-any.whl

3.5 发布 (Publish)¶

将包发布到 PyPI（Python Package Index），让全世界都能通过 pip install 使用你的包。

你需要先在 PyPI 注册账号并申请 API Token。

# 首次发布可能需要配置 token
uv publish --token pypi-AgEIcHlwaS5vcmc... 

# 或者设置环境变量 UV_PUBLISH_TOKEN 后直接运行
uv publish

4. 文档 (MkDocs)¶

文档是开源项目的门面。2026年，MkDocs 配合 Material for MkDocs 主题依然是黄金标准。

由于我们已经添加了 mkdocs-material 到开发依赖，直接初始化：

uv run mkdocs new .

修改 mkdocs.yml 配置主题：

site_name: My Awesome Package
theme:
  name: material

本地预览文档：

uv run mkdocs serve

部署到 GitHub Pages：

uv run mkdocs gh-deploy

5. 进阶：自动化 (CI/CD)¶

在 GitHub Actions 中使用 uv 也非常简单。Astral 提供了官方 Action。

.github/workflows/ci.yml 示例：

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v1

      - name: Install dependencies
        run: uv sync

      - name: Run tests
        run: uv run pytest

      - name: Check format
        run: uv run ruff check .

总结¶

相比于几年前复杂的 setup.py、requirements.txt、MANIFEST.in 组合，现代 Python 打包流程极大地简化了：

配置：一切皆在 pyproject.toml。
工具：一个 uv 搞定所有（环境、依赖、构建、发布）。
结果：更快、更稳定、更标准。