文档信息（用途、难度与维护记录）
| 属性 | 内容 |
|---|---|
| 模块 | 10-python-discovery |
| 象限 | 字典 |
| 难度 | ⭐ |
| 标签 | #uv #包管理 #锁文件 #PEP723 |
| 更新日期 | 2026年9月 |
uv 是 Rust 编写的 Python 包与项目管理器：替代 pip/venv/pip-tools 的安装与锁定职责，还能替你下载管理多个 Python 解释器本身。核心抽象是 pyproject.toml（声明意图）+ uv.lock（锁定精确依赖图），前者给人读，后者给机器复现。
# 项目生命周期：以下为具体示例，按当前任务选择命令，不必整块连续执行
uv init --app --python 3.14 # 应用项目；库项目改用 --lib
uv add httpx # 生产依赖；开发依赖如 uv add --dev pytest
uv remove httpx # 移除依赖
uv lock # 解析并生成 uv.lock；主动升级时加 --upgrade
uv sync --locked # 声明与锁文件不一致时失败；部署可再加 --no-dev
# --frozen 直接使用现有锁文件，不检查它是否与声明一致
uv run python main.py # 在项目环境中运行命令，必要时自动同步依赖
# 解释器管理
uv python install 3.14
uv python list # 列出解释器
uv python find # 定位当前使用的解释器
# 工具与兼容层
uvx ruff check . # 临时工具环境；等价于 uv tool run ruff check .
uv pip install httpx # pip 兼容接口；与 uv add 不同，不更新项目依赖声明
PEP 723 内联脚本元数据：单文件脚本头部写 # /// script 块声明依赖，uv run script.py 自动为其建环境。
mkdir demo && cd demo
uv init --python 3.14
uv add fastapi "uvicorn[standard]"
uv add --dev pytest ruff mypy
uv run uvicorn main:app --reload最后一条要求 main.py 中已定义 FastAPI 的 app；uv init 生成的默认脚本并不自动包含 Web 应用，先使用FastAPI 最小应用。
# analysis.py —— 自带依赖的单文件脚本
# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx"]
# ///
import httpx
print(httpx.get("https://example.com").status_code)uv run analysis.py # 自动创建临时环境、装好 httpx、执行| 陷阱 | 说明 |
|---|---|
绕过 uv run 直接敲 python |
可能使用不同解释器；可以用 uv run，或显式激活/指定项目虚拟环境，关键是确认解释器路径 |
不提交 uv.lock |
团队与 CI 依赖不可复现；.venv/ 才是忽略对象 |
uv sync 无脑带 --upgrade |
日常同步用 uv sync；升级是显式动作 uv lock --upgrade |
| 运行依赖与开发依赖混装 | pytest/ruff/mypy 进 --dev 组，生产镜像才能 --no-dev 裁剪 |
uvx 用于长生命周期环境 |
uvx 在隔离的工具环境运行，可复用缓存；项目依赖应走 uv add，不能假设工具环境就是项目环境 |
忽视 requires-python 下限 |
写 >=3.14 却用旧解释器运行，解析期就会报错（好事，别绕过） |
前置知识是虚拟环境和依赖版本。pyproject.toml 描述允许的依赖范围，uv.lock 记录解析结果，.venv 是当前机器上的安装产物。只复制 .venv 不能替代可重建的依赖声明；只改 pyproject 也不意味着运行环境已经变化。
在一个已有 uv.lock 的练习项目中，先运行 uv sync --locked，再执行 uv run python -c "import sys; print(sys.executable)"，确认命令来自项目环境。修改依赖声明后再次执行 --locked：若修改要求重新解析锁文件，它应失败，提醒你更新并审阅锁文件。
--frozen 使用现有锁文件而不检查它是否与声明保持最新；它不等于 --locked 的一致性检查。CI 一般需要明确选择哪一种语义，见锁定与同步说明。练习：在独立副本中比较两者对过期锁文件的反应，并记录哪一步修改了哪些文件。
- 📄 环境搭建教程 — uv 的入门工作流
- 📄 开发工具链 — uv 在工具链中的位置
- 📄 pytest 测试指南 —
uv add --dev pytest之后的事 - 📄 容器化部署 —
uv sync --frozen的镜像化用法