使用超快的 `uv`，一站式发布你的 Python 包到 PyPI 和私有 Gitea

作为 Python 开发者，打包和发布项目是一个常见的流程。无论是将优秀的开源工具分享给全世界（通过 PyPI），还是在公司内部与团队共享私有组件（通过私有包索引），一个高效、现代的工具链都至关重要。

今天，我们就来介绍一个革命性的工具：uv，并手把手教你如何用它来打包你的项目，并发布到 PyPI 和私有的 Gitea 仓库。

1. 概念简介：uv, PyPI, Gitea

uv uv 是由 Astral 公司（打造了 Ruff 和 Astral Python 的公司）开发的一款用 Rust 编写的极速 Python 包管理和项目工作流工具。它的目标是成为一款统一的、替代 pip、pip-tools、virtualenv、pipenv 和 poetry 的工具。其最大的特点就是快，无论是安装依赖、创建虚拟环境还是打包发布，速度都远超传统工具。

PyPI (Python Package Index) PyPI 是官方的、主流的 Python 软件仓库。我们通常使用 pip install package-name 命令安装的包绝大部分都来自这里。它是 Python 开源生态的基石。

Gitea Gitea 是一个轻量级、开源、自托管的 Git 服务，类似于 GitLab 或 GitHub。很多团队会选择在自己的服务器上搭建 Gitea 来管理私有代码库。除了代码托管，Gitea 还提供了包注册表（Package Registry） 功能，这意味着你可以把它当作私有的 PyPI 仓库来使用，存放不希望公开的内部 Python 包。

2. 项目结构与 uv build

首先，你需要一个标准的 Python 项目结构。一个最简单的可发布项目看起来是这样的：

my-awesome-package/
├── src/
│   └── my_awesome_package/
│       └── __init__.py
├── tests/
├── pyproject.toml  # 最重要的配置文件
├── README.md
└── LICENSE

关键在于 pyproject.toml 文件。它遵循 PEP 621 标准，定义了项目的元数据和构建配置。

使用 uv 打包： 安装好 uv 后（pip install uv 或使用官方一键安装脚本），在项目根目录下执行打包命令：

uv build

这个命令会做两件事：

1. 构建分发格式：在 dist/ 目录下生成源代码包（.tar.gz）和构建包（.whl）。
2. 使用锁文件：uv 会利用其超快的解析器来确保构建环境的可重现性。

uv build 替代了传统的 python -m build 命令，速度更快。

3. 发布到 PyPI

在发布到 PyPI 之前，你需要一个 PyPI 账号。

1. 获取 API Token： 登录 pypi.org，进入账户设置 -> API tokens，创建一个新的令牌（Token）。为了安全，其作用范围（Scope）可以限制在单个项目。

2. 使用 uv publish： uv 提供了 publish 命令来直接上传包到索引服务器。你需要将上一步获取的 Token 设置到环境变量中。

   # 设置环境变量（Linux/macOS）
   export UV_PUBLISH_TOKEN=='pypi-your-api-token-here'
   
   # 对于 Windows (PowerShell)
   $env:UV_PUBLISH_TOKEN=='pypi-your-api-token-here'
   
   # 发布！
   uv publish
   

   uv publish 会自动读取 pyproject.toml 中的项目信息，找到 dist/ 目录下最新的包文件，并将它们上传到 PyPI。

   你也可以使用更传统的 twine，但 uv publish 更快更简洁。

4. 发布到 Gitea

Gitea 的包注册表功能让你可以把它当作一个私有 PyPI 服务器。发布流程和 PyPI 类似。

1. 使用 uv publish 发布到 Gitea： 你需要通过 --publish-url 参数指定 Gitea 的包索引地址。Gitea 的包索引地址格式通常是： https://<你的gitea域名>/api/packages/<所有者用户名>/pypi

   	uv publish -u 用户名 -p 密码 --publish-url https://git.xxxxx.cn/api/packages/组织名称/仓库名称/pypi
   

   同样，uv 会处理好上传的所有步骤。

5. uv 配置镜像仓库为 Gitea

对于安装在公司内网或私有环境中的包，我们肯定不希望每次安装都去公有 PyPI 查找。我们可以将 Gitea 配置为 uv 的额外索引源（extra index URL）。

uv 的配置可以通过命令行参数、环境变量或 uv.toml 文件完成。最持久的方式是创建项目级或全局的 pyproject.toml`。

在项目根目录创建 pyproject.toml 文件，内容如下：

# pyproject.toml

[[tool.uv.index]]
url = "https://git.xxxx.cn/api/packages/xxxxx/pypi/simple"

6. 下载安装

配置好之后，安装就变得非常简单。

安装来自 PyPI 的公有包：

uv add requests

安装来自 Gitea 的私有包（例如包名为 company-utils）：

uv add company-utils

无论是个人开发者还是团队，uv 都能显著提升你的 Python 项目管理和协作效率。现在就尝试用 uv 来管理你的下一个项目吧！

---