本文档介绍了 uv 的工作区系统，该系统支持多项目 Python 代码库的管理。工作区提供了一种将相关项目分组、共享依赖项以及在单个存储库中协调多个包构建的方式。
有关工作区内单个项目管理的信息，请参阅 项目管理。有关项目初始化的详细信息，请参阅 项目初始化。
uv 支持两种主要的工作区配置：显式工作区和隐式单项目工作区。
来源：crates/uv-workspace/src/workspace.rs98-119 crates/uv-workspace/src/workspace.rs294-299
工作区系统围绕几个关键数据结构展开
| 组件 | 目的 | 代码位置 |
|---|---|---|
工作区 | 主工作区容器 | crates/uv-workspace/src/workspace.rs99-119 |
ProjectWorkspace | 带有当前项目上下文的工作区 | crates/uv-workspace/src/workspace.rs700-713 |
WorkspaceMember | 工作区中的单个包 | crates/uv-workspace/src/workspace.rs715-729 |
WorkspaceCache | 用于工作区发现的缓存 | crates/uv-workspace/src/workspace.rs36-41 |
工作区发现遵循一个系统化的流程来定位和验证工作区配置。发现从给定路径开始，遍历父目录以查找 pyproject.toml 文件。
来源：crates/uv-workspace/src/workspace.rs142-236 crates/uv-workspace/src/workspace.rs769-828
工作区发现过程通过 glob 模式收集成员并验证其结构
来源：crates/uv-workspace/src/workspace.rs830-965 crates/uv-workspace/src/workspace.rs967-1075
工作区支持对单个成员或整个工作区的操作
来源：crates/uv/src/commands/project/run.rs497-539 crates/uv/src/commands/project/sync.rs493-541
项目命令通过发现和目标选择与工作区系统集成
| 命令 | 工作区集成 | 实现 |
|---|---|---|
uv add | 发现工作区，选择目标包 | crates/uv/src/commands/project/add.rs196-214 |
uv remove | 工作区发现和成员选择 | crates/uv/src/commands/project/remove.rs91-111 |
uv sync | 支持工作区范围或成员特定的同步 | crates/uv/src/commands/project/sync.rs94-104 |
uv run | 带包选择的工作区发现 | crates/uv/src/commands/project/run.rs500-504 |
工作区支持分层来源配置，其中项目级别的来源会覆盖工作区级别的来源
来源：crates/uv-workspace/src/workspace.rs112-116 crates/uv/src/commands/project/mod.rs48
工作区系统采用缓存来避免重复的文件系统操作
来源：crates/uv-workspace/src/workspace.rs27-41 crates/uv/src/commands/project/add.rs195
工作区系统处理各种错误条件和边缘情况
| 错误类型 | 条件 | 错误代码 |
|---|---|---|
MissingPyprojectToml | 目录树中未找到 pyproject.toml | crates/uv-workspace/src/workspace.rs46 |
NonWorkspace | 项目明确标记为不管理 | crates/uv-workspace/src/workspace.rs55 |
NestedWorkspace | 工作区成员包含工作区定义 | crates/uv-workspace/src/workspace.rs56-57 |
DuplicatePackage | 多个成员具有相同的包名 | crates/uv-workspace/src/workspace.rs58-63 |
来源：crates/uv-workspace/src/workspace.rs43-77 crates/uv/src/commands/project/run.rs522-538