3.4 项目 on 编程那些事儿

3.4.1 项目结构与文件

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/layout/

3.4.1 项目结构与文件

`pyproject.toml`

Python 项目元数据定义在 pyproject.toml 文件中。uv 需要该文件来识别项目的根目录。

提示

可以用 uv init 创建新项目。细节请参阅创建项目。

最小的项目定义包含名称和版本：

3.4.2 创建项目

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/init/

3.4.2 创建项目

uv 支持用 uv init 创建项目。

创建项目时，uv 支持两种基本模板：应用和库。默认情况下 uv 会创建应用项目。使用 --lib 标志可以改为创建库项目。

在两种情况下，uv 都倾向于定义构建系统，并把源文件放在专用的 src/<project_name>/ 目录中。定义构建系统可以使用各种 Python 打包特性，例如添加命令行入口点，并避免 Python 导入系统中常见的困惑。可以通过 --no-package 或 --bare 选项禁用构建系统。

3.4.3 管理依赖

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/dependencies/

3.4.3 管理依赖

依赖字段

项目的依赖在几个字段中定义：

project.dependencies：发布出去的依赖。
project.optional-dependencies：发布出去的可选依赖，即 “extras”。
dependency-groups：仅本地的开发依赖。
tool.uv.sources：开发期间依赖的替代来源。

注意

即使项目不打算发布，也可以使用 project.dependencies 和 project.optional-dependencies 字段。dependency-groups 是最近才标准化的特性，可能尚未被所有工具支持。

3.4.4 运行命令

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/run/

3.4.4 运行命令

处理项目时，项目会被安装到 .venv 中的虚拟环境里。默认情况下该环境与当前 shell 隔离，因此需要该项目的调用（例如 python -c "import example"）会失败。请改用 uv run 在项目环境中运行命令：

3.4.5 锁定与同步

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/sync/

3.4.5 锁定与同步

锁定是指把项目依赖解析为锁文件的过程。同步是指把锁文件中的一部分包安装到项目环境的过程。

自动锁定与同步

在 uv 中，锁定和同步是自动的。例如使用 uv run 时，会在调用所请求的命令之前先锁定并同步项目。这确保项目环境始终是最新的。同样，读取锁文件的命令（例如 uv tree）也会在运行前自动更新锁文件。

3.4.6 配置项目

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/config/

3.4.6 配置项目

Python 版本要求

项目可以在 pyproject.toml 的 project.requires-python 字段中声明它所支持的 Python 版本。

建议设置 requires-python 值：

1
2
3
4
5


# pyproject.toml
[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.12"

Python 版本要求决定项目允许使用的 Python 语法，并影响依赖版本的选择（它们必须支持相同的 Python 版本范围）。

3.4.7 构建分发包

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/build/

3.4.7 构建分发包

要把项目分发给他人（例如上传到 PyPI 之类的索引），你需要把它构建成可分发的格式。

Python 项目通常同时以源码分发（sdist）和二进制分发（wheel）形式分发。前者通常是包含项目源代码及一些附加元数据的 .tar.gz 或 .zip 文件，后者是包含可直接安装的预构建产物的 .whl 文件。

3.4.8 导出锁文件

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/export/

3.4.8 导出锁文件

uv 可以把锁文件导出为不同格式，以便与其他工具和工作流集成。uv export 命令支持多种输出格式，各自适用于不同场景。

关于锁文件及其创建方式的更多细节，请参阅项目结构和锁定与同步文档。

3.4.9 使用工作区

Fri, 25 Sep 2026 19:02:24 +0800

原文链接: https://docs.astral.sh/uv/concepts/projects/workspaces/

3.4.9 使用工作区

工作区（workspace）的概念受 Cargo 同名概念启发，指“一个或多个称为工作区成员的包的集合，它们被一起管理”。

工作区通过把庞大的代码库拆分为多个具有公共依赖的包来组织它们。可以想象：一个基于 FastAPI 的 Web 应用，连同若干作为独立 Python 包进行版本管理和维护的库，全部位于同一个 Git 仓库中。