uv通过目录隔离识别项目，每个项目独享pyproject.toml；切换依赖环境需配合uv python pin指定Python版本后执行uv sync重解析依赖树。
uv 如何识别并切换不同项目的 pyproject.toml
uv 本身不支持“多配置文件共存于同一目录”这种模式，它只读取当前工作目录下唯一的 pyproject.toml。但你完全可以通过目录隔离 + uv python pin + uv sync 实现项目级多环境配置。关键不是“一个配置文件切多个环境”，而是“每个项目带自己专属的配置”。
为什么 uv sync 有时不读 pyproject.toml 的 requires-python
常见错误现象：uv sync 报错 No Python version found that satisfies the project's requirements，即使 pyproject.toml 里写了 requires-python = ">=3.9,。
原因在于：uv 默认不会自动安装缺失的 Python 版本，它只检查已安装版本是否匹配约束。解决步骤如下：
- 先运行
uv python list查看当前已安装哪些版本 - 若缺少符合
requires-python的版本，手动安装：uv python install 3.11.9 - 再执行
uv sync，它就会基于已装版本做兼容性筛选 - 注意：
uv venv --python 3.11创建的环境，和uv sync所用的 Python 版本必须一致，否则锁文件可能不生效
如何让 uv 在不同项目中自动加载对应 Python 版本
靠 .python-version 文件驱动。在项目根目录执行：
立即学习“Python免费学习笔记（深入）”；
安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。
uv python pin 3.11.9
会生成一个纯文本文件 .python-version，内容就是 3.11.9。之后只要你在该项目目录下运行：
-
uv sync→ 自动选用 3.11.9 解释器解析依赖 -
uv run python --version→ 输出Python 3.11.9 -
uv venv→ 默认创建绑定 3.11.9 的.venv
这个机制不依赖 shell 配置，也不需要 pyenv —— uv 自己读取该文件并调度本地已安装的对应版本。
pyproject.toml 中 tool.uv 配置项对多环境的影响
[tool.uv] 是 uv 的全局行为控制区，影响所有子命令。常见实用配置：
-
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"：指定镜像源，避免每个项目重复配置 -
python-install-dir = "./.python"（不推荐）：强制把 Python 解释器装进项目目录 —— 这会让项目体积暴涨，且无法跨项目复用解释器；更合理做法是用UV_PYTHON_INSTALL_DIR环境变量统一管理 -
no-cache = true：禁用 wheel 缓存，调试时有用，但会显著拖慢重复安装
真正影响多环境隔离的是 requires-python 和 dependencies 声明本身，[tool.uv] 只负责“怎么装”，不决定“装什么版本”。
最易被忽略的一点：uv 不会自动同步 .python-version 和 pyproject.toml 中的 requires-python。二者可以不一致 —— 前者决定实际运行用哪个解释器，后者仅用于依赖解析时的兼容性过滤。如果你改了 requires-python 却没更新 .python-version，uv sync 可能成功，但运行时直接报 ModuleNotFoundError，因为底层解释器版本不支持某个包的字节码。
