解构uv ：从使用到跨平台依赖解析、文件锁机制与 Monorepo 最佳实践

背景

在介绍uv的用法及底层原理之前，我想先说说，uv的存在有什么意义，他解决了python的哪些痛点，以至于我们现在提到Python的项目与工具链管理器，就绕不开它。

现在假定，你重生了，重生到一个没有uv的世界，你将面对：

• 1.破碎化的工具链：

  • 安装python版本： pyenv或conda。
  • 创建虚拟环境： virtualenv、venv、conda env。
  • 安装依赖包： pip
  • 锁定依赖版本： pip-tools，pip-compile。
  • 发布包：用 twine 和 build。
  • 安装全局命令行工具：用 pipx。
    就算是整合工具portry也有没能涵盖到python版本管理的范畴等等缺憾。你不得不阅读复杂的指南来研究这些工具如何配合。
    这是一个讲传统 Python 打包与分发流程教程创建、管理与分发你的Python项目 想了解的话可以看看。

• 2.缓慢的解析性能：

  • 传统 Python 工具因为解释器自身的开销，难以利用多核 CPU 加速复杂的**依赖回溯（Backtracking）**计算。这导致在安装如 Torch 等大型库时，解析过程超级慢。

  • 尤其pip使用的是回溯算法，在python的GIL限制下，单线程解析性能很差。

  这是关于GIL的一些解析Python GIL（全局解释器锁）机制对多线程性能影响的深度分析 ，不过python新版本的更新正在朝无GIL发展，解锁 Python 多线程新纪元

• 3.标准化的分裂

• 4.缺乏跨平台的一致性：

  • 某些包在不同操作系统上依赖树不一样，pip freeze只能看到当前环境的依赖，无法保证在其他平台上重现相同的依赖树。
  • python允许通过环境标记 来按需安装依赖，例如：colorama; sys_platform == 'win32' (只在 Windows 下安装)。然而pip freeze不会记录这些条件依赖，导致在不同平台上安装时可能缺少必要的包。
  • 缺乏锁文件，go有go.sum。node.js有package-lock.json/yarn/lock。python你呢！
    requirements.txt只是当前环境的依赖快照，并不属于全平台解析的结果。关于lockfile可以参考 File locking in Linux ,Linux内核现在主要支持的是建议性锁 (Advisory Locking) ，文档里的Mandatory Locking 已经寄了。本质上python加的锁是在"遥控"linux系统底层文件锁功能，如何给python实现加锁？Python文件锁实现与跨平台优化方案

how to uv

吓哭了吧！没关系！你的强来了！

uv 继承了 Rye 的"全栈工具链"愿景，并在底层实现了更高的性能。

uv（unified version） 不仅仅是更快的 pip。它是 Python 生态的 Cargo (Rust) ------ 一个统一了 Python 版本管理、虚拟环境、依赖解析、项目构建与发布的全链路工具链。

详细使用可以看官方文档：docs.astral.sh/uv/

1. 安装与配置

推荐使用官方脚本安装（与系统 Python 解耦）：

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

配置自动补全

能很大提升 CLI 体验。

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc
# bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
source ~/.bashrc
# powershell
if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
uv generate-shell-completion powershell | Out-File -Append -Encoding utf8 $PROFILE

---

2. 核心工作流 (The Core Workflow)

uv 默认会配置 Hatchling 当构建后端,配置标准为PEP 621 (pyproject.toml),核心引擎使用的是Rust编写的高性能解析器也就是uv本身。

2.1 初始化项目

# 初始化标准项目结构
uv init my-project

这会生成 pyproject.toml、.python-version 和 uv.lock（首次运行）。

2.2 锁定 Python 版本 (替代 pyenv)

不依赖系统 Python，为项目锁定特定版本：

uv python pin 3.12

*默认下， uv 会自动下载一个独立的 Python 3.12 解释器缓存在系统级的应用数据目录（AppData 或 .local/share）下的 python 子目录中，使用 符号链接 (Symlink) 或 硬链接，让虚拟环境指向这个全局目录。

常用管理命令：

uv python install 3.11  # 手动下载特定版本
uv python list          # 查看本机已安装的所有 Python 版本
uv python uninstall 3.8 # 卸载不需要的版本

2.3 添加依赖 (替代 pip/poetry)

# 添加运行时依赖 (自动更新 pyproject.toml 和 uv.lock)
uv add fastapi httpx
# 添加开发依赖
uv add --group dev pytest ruff
# 移除依赖
uv remove httpx
# 部署上线的时候用这个告诉uv不要安装开发依赖。
uv sync --no-dev

2.4 运行与执行

无需手动激活环境！使用 uv run，它会自动在正确的环境中执行命令。

# 运行脚本，自动创建临时环境并安装依赖
uv run main.py
# 向脚本添加依赖声明，自动修改脚本头部注释
uv add --script example.py requests
# 运行模块
uv run python -m http.server
# 运行依赖中的工具
uv run pytest

2.5 同步环境 (The Sync)

当从 Git 拉取代码后，或者手动修改了 pyproject.toml 后，使用这个命令确保环境与声明一致：

uv sync

• 作用 ：它会安装缺失的包，卸载多余的包，确保 .venv 严格等于 uv.lock。类似于一个go mod tidyplus版，还执行.venv的整理。

---

2.6 全局工具管理

# 临时运行工具 (用完就扔)
uvx / uv tool run

uv tool uninstall <tool-name>
uv tool install <tool-name>

# 永久安装工具
uv tool install black
# 列出已安装工具
uv tool list
# 升级 Shell 配置 (确保工具在 PATH 中)
uv tool update-shell

---

3. 一些特定依赖场景

3.1 PyTorch 最佳实践 (CPU/CUDA 分离)

我们都知道pytorch有两种版本，cpu版虽然通用性强但是性能有限，cuda版将运算交给gpu，性能提升但是文件体积巨大，如果什么都不配置的话，mac和windows用户会默认下载cpu版本，linux会默认下载cuda版本，但是一旦你有特殊需求，你就需要手动指定，这个时候就会用到手动配置pytorch索引和环境标记。

利用 marker 和 explicit 标志，就可以实现精准控制不同平台的 Torch 版本下载。

如何使用pytorch索引：

某些情况下，你可能希望全平台使用torch cpu版本，这个时候第一步，先把pytorch索引添加到pyproject.toml中：

   # CPU-only (仅限 CPU)
   [[tool.uv.index]]
   name = "pytorch-cpu"
   url = "https://download.pytorch.org/whl/cpu"
   explicit = true

使用 explicit = true，可以确保该索引仅用于 torch、torchvision 和其他 PyTorch 相关包，而不是用于像 jinja2 这样的通用依赖项，后者应继续从默认索引 (PyPI) 获取。

第二步，在 pyproject.toml 中为 torch 和 torchvision 指定索引源：

    [tool.uv.sources]
    torch = [
      { index = "pytorch-cpu" },
    ]
    torchvision = [
    { index = "pytorch-cpu" },
   ]

然后它就变成一个在全平台使用cpu版本的pytorch啦！

使用环境标记配置加速器 (Configuring accelerators with environment markers)

pytorch索引有一个问题：他是一刀切的，如果索引用的是cuda版本，那么mac用户不是炸了？

因此实际使用中，我们通常结合pytorch索引 和环境标记 来实现跨平台的CPU/CUDA版本控制。这样就可以准确控制不同操作系统下的不同pytorch版本。

以下就可以控制windows和mac用户安装cpu版本，linux用户安装cuda版本，其实就相当于if linux then cuda else cpu这种逻辑。

[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.14.0"
dependencies = [
  "torch>=2.9.1",
  "torchvision>=0.24.1",
]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]
torchvision = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

uv pip接口

通常情况下的首选是uv init/add sync，但是有些场景：例如你不知道目标机器有没有显卡，或者需要兼容旧有的 requirements.txt 流程时，才使用 uv pip。

他的特性是自动后端选择 (Automatic backend selection)

uv 支持通过 --torch-backend=auto 命令行参数（或 UV_TORCH_BACKEND=auto 环境变量）自动选择适当的 PyTorch 索引，如：$ uv pip install torch --torch-backend=auto

启用后，uv 将查询已安装的 CUDA 驱动程序、AMD GPU 版本和 Intel GPU 的存在，然后为所有相关包（例如 torch、torchvision 等）使用最兼容的 PyTorch 索引。如果未找到此类 GPU，uv 将回退到仅 CPU 索引。uv 将继续遵守 PyTorch 生态系统之外任何包的现有索引配置。

也可以使用 --torch-backend=cu126（或 UV_TORCH_BACKEND=cu126 环境变量）选择特定的后端（例如 CUDA 12.8）。

目前，--torch-backend 仅在 uv pip 接口中可用。

⭐️pay attention:

• 项目开发中使用 uv pip 安装包后，要手动补充包名到 pyproject.toml。
• uv pip 不会更新锁文件 (uv.lock)

3.2 配置私有源 (Private Mirror)

加速第三方库

在 pyproject.toml 中配置：

[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true  # 设为默认源，如果不用true的话，uv会把这个源当成备用。

加速python解释器下载

uv会自动从官方源下载，如果速度偏慢，可以通过系统层面设置环境变量
export UV_PYTHON_INSTALL_MIRROR="http://..."

---

4. Workspaces

在一个仓库中管理多个相互依赖的包（如 backend, library, worker）。

4.1 什么时候使用workspaces

首先，在说如何用uv进行管理时，得先提一句Workspaces 是为了"统一"和"协作"设计的，如果你需要"隔离"和"差异化"就不适合用。

不适合使用workspaces的场景：

• 1. 依赖版本冲突：例如，子项目A要求pandas>=2.0，子项目B要求pandas<2.0。一个uv.lock无法同时满足。
• 2. 需要独立的虚拟环境：workspaces创建的是一个巨大的虚拟环境，可能会产生项目A没有声明requests，但是B依赖requests,A竟然也能import requests的情况。
• 3. python版本不兼容。

路径依赖 (Path Dependencies) ：

如果你属于那种不适合用workspaces的场景，但是又想在一个仓库管理多个项目，可以考虑使用路径依赖。

只需要修改使用者的 pyproject.toml，将依赖指向本地路径即可，示例如下：

[project]
name = "my-backend"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi",
    "my-shared-lib",
]

# editable = true意味着它是可编辑模式安装。在 shared-lib 里改了代码，backend 不需要重新安装，立刻就能生效。
[tool.uv.sources]
my-shared-lib = { path = "../shared-lib", editable = true }

4.2 Monorepo vs Polyrepo

这俩属于代码仓库常见的物理架构，我最开始误以为monorepo和polyrepo属于workspaces的不同种类呢，实则不然啊。

在 uv（以及 Rust Cargo、npm、Yarn）的语境下，Workspaces 就是专门为 Monorepo 设计的工具特性。它不适用于 Polyrepo。

这篇文章对这俩进行了一下介绍：polyrepo -> monorepo。

4.3 如何使用 uv 管理 Monorepo

使用uv管理monorepo，其实就是通过 pyproject.toml 告诉 uv："不要去 PyPI 下载这个包，去硬盘上的这个文件夹里找。"

1. 目录结构示例

repo/
├── pyproject.toml (根配置：定义 workspace 成员)
├── uv.lock        (核心：全局单一锁文件)
└── packages/
    ├── api/       (子项目 A：依赖 common)
    └── common/    (子项目 B：被依赖库)

2. 根目录配置 (repo/pyproject.toml)

这是 Workspace 的"总指挥"，负责圈定哪些文件夹属于这个大家庭。

[project]
name = "my-monorepo-root"
requires-python = ">=3.12"
# 根目录通常不写具体业务依赖，只作为容器

[tool.uv.workspace]
members = ["packages/*"]

3. 子项目引用配置 (packages/api/pyproject.toml)

这是最关键的一步。假设 api 需要使用 common 包：

[project]
name = "api"
version = "0.1.0"
dependencies = [
    "fastapi",
    "common",  #  在这里直接写包名，保持标准兼容性
]

[tool.uv.sources]
# 逻辑引用替代物理路径
common = { workspace = true }

{ workspace = true } 的核心价值：

1. 逻辑解耦 ：你不需要写死 path = "../common" 这种脆弱的相对路径。即使你把 common 文件夹移动到别的地方，只要它还在 workspace 的 members 范围内，uv 都能自动找到它。
2. 安全阻断 ：它是一个"路由开关"，强制 uv 只在本地 workspace 查找该包，绝对禁止去 PyPI 下载。这能有效防止"依赖混淆攻击"（即有人在 PyPI 上发了一个同名的恶意包）。
3. 版本自动同步 ：uv 会自动读取本地 common 项目的版本号，无需手动维护版本约束。

最终效果 ：

执行 uv sync 会一次性解析所有子项目的依赖，且子项目之间的引用会自动识别为本地路径（Editable Install），无需手动执行 pip install -e。

---

5. Docker 容器化最佳实践

官方文档原文，虽然我也是从这看来的。Using uv in Docker

关于docker，推荐阅读从docker使用到底层原理 （自己给自己打广告见过没⸜₍๑•⌔•๑₎⸝ ）

• 推荐使用 COPY --from 模式从官方镜像中提取二进制文件。比使用安装脚本更安全、更可控。

• 推荐版本锁定

• 推荐分层依赖 安装与项目代码，启用挂载缓存 ，编译字节码。

• 挂载卷 ：开发时将项目目录挂载到容器中，但必须排除虚拟环境。

  使用匿名卷挂载 .venv，例如： docker run ... --volume .:/app --volume /app/.venv。

• 非可编辑模式 (Non-editable) ：默认情况下 uv 以可编辑模式安装项目。在多阶段构建中，应使用·--no-editable 标志。这允许你在一个阶段安装环境，然后仅将虚拟环境（不包含源代码绑定）复制到最终镜像中。

• workspaces/Monorepo 需要特殊处理，初始同步：使用--frozen代替 --locked。因为在复制所有工作区成员的 pyproject.toml 之前，uv 无法断言锁文件是最新的。

  排除工作区安装：初始同步时使用 --no-install-workspace 标志。

  最终同步：复制所有代码后，再使用 --locked 进行完整同步。

  对比polyrepo，直接COPY -> uv sync --locked即可。

# 1. 获取 uv
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.9.18 /uv /uvx /bin/

WORKDIR /app

# 2. 配置环境变量
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy
# 确保不复制本地 venv (需配合 .dockerignore)

# 3. 安装依赖 (中间层优化)
# 利用缓存挂载和绑定挂载
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev

# 4. 复制项目代码
COPY . /app

# 5. 安装项目本身，禁用开发依赖
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev

# 6. 设置路径并运行
ENV PATH="/app/.venv/bin:$PATH"
CMD ["uv", "run", "my_app"]

---

6. 构建与发布 (Build & Publish)

替代 build 和 twine，实现一条龙发布。

# 构建 Wheel 和 Source Distribution
uv build
# 发布到 PyPI (支持 Trusted Publishing)
uv publish

什么是pypl ，wheel 和sdist 呢？

pypl是puyhon官方包管理与发布平台，像包的超市，你发布上去的东西其他人可以通过一行命令安装使用。

wheel和sdist是python包的两种分发格式，wheel（.whl)是编译好的二进制格式，安装速度快，sdist(.tar.gz)是源码格式，兼容性好。后者安装时需要进行编译，如果代码里有C语言的话，就要求用户有C语言编译器。

---

7.维护与排查

7.1 缓存管理

uv 的缓存机制（详见后续模块）非常激进，定期清理有助于释放空间。
什么时候需要清理缓存呢？

发现硬盘红了，用工具扫描发现 ~/.cache/uv 竟然占了 10GB+，用uv cache prune 会删除很久没被引用的包。
什么时候用uv cache clean呢？

A. 下载的文件损坏。虽然uv有哈希检验，但是极少数网络不稳定会导致缓存.whl文件损坏。

B. 强制更新未锁定的依赖。有的时候开发新库可能会出现你推了新代码但是没有更新版本号的情况，uv可能会因为缓存一直安装旧代码。

C. CI/CD 环境的纯净构建在构建 Docker 镜像或流水线时，为了确保环境绝对纯净，不复用旧缓存。

# 查看缓存目录路径
uv cache dir
# 删除所有过期/未使用的缓存
uv cache prune
# 暴力清空所有缓存 (仅在解决顽固报错时使用)
uv cache clean

7.2 路径与环境查询

第三方工具集成或者ide配置可能会用到。

例如想在 Docker 运行时把宿主机的缓存挂载进去，来加速容器内的构建时，会需要运行 uv cache dir 确认宿主机路径，然后写 docker run -v $(uv cache dir):/root/.cache/uv。

# 查看 uv 管理的 Python 解释器安装位置
uv python dir
# 查看 uv 全局工具的安装位置
uv tool dir

7.3 自身管理

uv迭代很快的，可以考虑没事更新一下。

# 升级 uv 到最新版本
uv self update
# 查看 uv 版本与环境信息
uv self info

8. 常用命令对照

场景	旧方式 (Pip/Poetry)	uv 方式
创建环境	python -m venv .venv	uv init (自动管理)
激活环境	source .venv/bin/activate	uv run <cmd> (无需激活)
安装包	pip install reqs	uv add reqs
开发依赖	poetry add -D pytest	uv add --group dev pytest
同步依赖	pip install -r requirements.txt	uv sync (强制一致)
升级包	pip install -U reqs	uv lock --upgrade-package reqs
运行工具	pipx run black	uvx black
CI 安装	pip install ...	uv sync --frozen

---

uv的核心机制：

我希望上一个模块主要讲怎么用，这个模块就对上一个模块的操作进行一些解析补充。

跨平台解析机制 (Universal Resolution)

相较于pip生成的依赖列表是基于当前环境快照，uv的解析机制是平台无关的，它基于多平台依赖图 (Multi-platform Dependency Graph) 来生成一个统一的锁文件 uv.lock。

观Resolution 以及Resolver internals 有感。原文怎么会写的这么长难句。

使用 uv lock时，发生了什么？

逻辑层面上："全量解析" (Universal Resolution)

1.元数据查询 (Metadata Querying)

什么是元数据？ 一方面，它是检索、互操作性和数据治理的基础，另一方面，它是隐私泄露的高危区域，往往被低估。因此，元数据管理（Metadata Management）是数据仓库和数据湖成功的核心，而非边缘任务。

uv 不只是下载包，而是首先向 PyPI 发起大规模的元数据查询。它会抓取目标包（如 numpy）的所有可用版本，以及这些版本在 Windows、Linux、macOS 等不同平台下的差异化定义。

它不只看"我能在本机装什么"，而是看"这个包在所有可能的系统上长什么样"。

2.构建抽象依赖图 (Abstract Dependency Graph)

• uv 在内存中构建一个虚拟的、涵盖所有目标平台的依赖图谱 (Dependency Graph) 。
• 对比：传统的 pip 是"走一步看一步"（只针对当前环境），而 uv 是同时模拟出 Linux Python 3.9、Windows Python 3.12、macOS ARM64 等多种场景下的依赖树。

3.约束求解 (Constraint Solving)

利用高效PubGrub 算法 (PubGrub Algorithm) ，uv 在这个巨大的图谱中寻找一个最大公约数，也就是交集 (Intersection)。

大手子们感兴趣的话可以看看pubgrub的内部算法：Internals of the PubGrub algorithm

• 目标：找到一组版本组合，使得它们既能满足你的 pyproject.toml 要求，又能在所有目标平台上不冲突。
• 结果：如果不同平台需要不同的依赖（例如 Windows 需要 colorama 但 Linux 不需要），它会将带有**环境标记 (Environment Markers)**的条件表达式，明确地写入锁定文件中，而不是忽略它们。
• 提问！：会不会出现找不到交集的情况呢？
  当然会，这就是Resolution Impossible（无法解析）或 Version Conflict（版本冲突）的情况，uv会抛出错误，此时pubgrub会生成一个推导链，方便调整依赖声明。
  类似于下图：

4.生成锁定文件 (Lockfile Generation)

最终生成的 uv.lock 文件不是一份简单的清单，而是一份通用账本 (Universal Ledger)。

它记录了所有第三方包的精确版本（Hash），包含在 A 情况下用 B 版本，在 C 情况下用 D 版本的完整决策树。这就确保了无论在谁的电脑上（Windows/Mac/Linux），只要拉取代码，整个单体仓库的依赖拓扑完全一致且即时同步。

物理层面："文件锁" (File Locking)

这是 uv lock 能够高速并行且不崩溃（不同进程间不打架）的保障，对应之前在"背景"里提到的"Linux 文件锁机制"。在执行上述逻辑运算和随后的缓存写入时，uv 必须处理**并发 (Concurrency)**问题。

1.获取排他锁 (Acquiring Exclusive Lock) 在写入全局缓存（如下载新的 Wheel 包）或修改项目状态前，uv 会先在 .locks 目录中寻找对应的锁文件，并尝试获取文件锁 (File Lock)。

• 目的：防止竞态条件 (Race Condition) 。比如，防止你在终端 A 运行 uv lock 正在写入 numpy 的缓存时，终端 B 的uv sync突然把这个未写完的文件读走或覆盖。

• 什么是排他锁？
  排他锁 （也叫写锁、互斥锁 Mutex）是一种并发控制机制 。它的规则非常简单且霸总："我现在要占用这个资源（文件/数据库/内存），一次只准一个进程修改，在我用完之前，其他任何人（进程/线程）看都不准看。"

  感觉它和gil是不是有点像，但是他们的层级，作用范围，目的都不一样。

  有没有人被各种各样的"锁"打晕了，我也。

  总而言之，锁的硬度上：有劝导锁 (Advisory Lock)强制锁 (Mandatory Lock)。策略上有悲观锁 (Pessimistic Lock)乐观锁 (Optimistic Lock)无锁编程 (Lock-Free / Wait-Free)。锁的模式这个维度里有排他 (Exclusive / X锁)和共享 (Shared / S锁)。具体实现机制上有读写锁 (Read-Write Lock)互斥锁 (Mutex)自旋锁 (Spinlock)等等。除这四个维度，还有粒度，公平性，阻塞性的维度。锁在计算机体系中是分层存在的。期待有大佬能把这些整理一下੭ ˙ᗜ˙ ੭。

2.进程阻塞与协同 (Process Blocking & Coordination) 如果检测到锁被占用（说明另一个 uv 进程正在忙），当前的uv lock 进程会进入阻塞 (Blocking) 状态，自动排队等待。

• 因此，无需担心多开终端会搞坏环境，uv 会自动通过操作系统内核级的锁机制来协调顺序。

3.原子性写入 (Atomic Write) 一旦计算完成并拿到锁，uv 会确保对 uv.lock 文件和缓存文件的写入是原子性 (Atomic) 的。这意味着文件要么全写好，要么全不写，不会出现"写了一半断电导致文件损坏"的情况。

---

uv Workspaces 内部运行机制

uv workspaces机制类似于一个虚拟化的元项目管理器，运行uv sync时，它不只是简单轮询子项目，而是：

1. 发现与拓扑构建 (Discovery & Topology)
   在 uv 开始解决复杂的版本冲突或下载任何代码之前，他得先知道你本地硬盘有什么。

• uv 首先读取根目录 pyproject.toml 中的 tool.uv.workspace.members 列表。
• 执行 glob 扩展，遍历文件系统以定位所有潜在的子项目目录，根据三重验证：a.路径匹配 b.pyproject.toml存在检查 c.元数据有效性 来确认。

认识 Glob Pattern ，遍历范围严格控制在工作区根目录及其子目录。

• 注意：此时还不会安装任何东西，只是建立工作区成员注册表（Workspace Member Registry） ，它把物理上的文件系统路径映射成了逻辑上的包名，让后续的依赖解析算法能够把本地文件夹当做现成的安装包来处理，就不再去pypl上找了。

2.依赖聚合与统一 (Dependency Aggregation & Unification)

搞清楚了他们有啥，下一步就是把他们聚在一起。

虚拟化合并 ：

uv 将 Root 的依赖和所有 Member 的依赖进行并集操作，构造出一个巨大的"虚拟项目"需求清单。它不是隔离解析 A 和 B，而是将整个 Monorepo 视为一个整体来处理。

(注：这个巨大的需求清单也就是在上文提到的 PubGrub 算法中进行统一求解)。
版本一致性仲裁 (Consistency Arbitration) ：

这其实就是前文的约束求解。

3.锁文件生成 (The Universal Lock)

同上。

开发态重写 (Development Rewriting) ：

这是 Workspace 在锁文件中的核心特征。对于注册表内的包引用（如 api 依赖 common），uv 会触发重写逻辑：

• 不记录哈希：因为它时刻在变。
• 标记为 Editable：标记为可编辑模式。
• 指向相对路径：直接指向硬盘上的 ../packages/common。

重写机制其实有两种：
开发态重写 (Development Rewriting) ：发生在 uv sync，重写为相对路径（为了改代码生效）。
构建态重写 (Build Rewriting) ：发生在 uv build，重写为版本号（为了发布到 PyPI）。

4.虚拟环境布局 (Environment Layout & Strategy)

uv需要让 Python 解释器在执行 import 语句时，能够"看见"并加载那个位置的代码。

默认情况下，uv 只在 根目录 创建一个 .venv。它不会污染子项目的文件夹。

链接技术 (.pth Linkage) ：

简单来说，uv 利用了 Python 标准库 site 模块的一个原生特性，实现了一种"软连接"的效果。
Python 的 site 模块与 .pth 文件

• Python 启动时，会自动导入一个叫 site 的内置模块。这个模块负责配置 sys.path（也就是 Python 查找包的路径列表）。
• 机制: Python 启动，site 模块开始工作。
• 它会扫描标准库路径（如 lib/site-packages）。然后查找该目录下所有后缀为 .pth 的文件。
• 执行：对于每一个 .pth 文件，Python 会读取其中的每一行，并将其作为路径添加到 sys.path 中。
  在这个过程里，uv 不像 pip install -e . 那样生成复杂的 egg-link 或者去修改 easy-install.pth，而是直接生成一个专属的、纯净的 .pth 文件。

uv里的具体操作：

• 第三方库（如 pandas）：直接安装 wheel 到 .venv/lib/site-packages。
• Workspace 成员：uv 使用 .pth 文件机制。它会在 site-packages 下创建特殊的 .pth 文件，内容仅仅是子项目源码目录的路径字符串。

结果：当你 import potions时，Python 解释器读取 .pth 文件，直接跳转到 packages/potions/src 加载代码。从而实现毫秒级环境同步与热重载。

---

补充提问！

Q: 如果要发布子包到 PyPI，，{ workspace = true } 这种本地配置怎么办？会报错吗？

A: 不用担心 ，uv 已经处理好了。

它采用 "开发时用路径，构建时换版本" 的策略：

1. 自动转换 ：uv build 会自动处理这一"脏活累活"，无需手动修改配置。
2. 解决矛盾：完美平衡了 Monorepo 的本地调试便利性与公网分发的标准化。

前提 & 操作

被依赖的子包（如 common）必须也发布到 PyPI。

• 步骤 ：先构建并发布底层 common -> 再构建并发布上层 api。
• 替代 ：使用 uv publish 的批量发布功能，它会尝试自动处理依赖顺序。