必须执行uv lock更新锁文件；若需升级依赖则加--upgrade，指定包用--upgrade-package，支持--prerelease=allow、--no-cache和--dry-run精准控制。

当你修改了 pyproject.toml 中的依赖声明（比如新增、删减或调整版本约束），但 uv.lock 仍停留在旧状态，导致后续 uv sync 安装的不是你预期的依赖树，就必须主动更新锁文件——这一步不能靠等待或重试自动触发，必须执行明确命令。

基础更新：检测到 pyproject.toml 变更后自动生成新锁

uv 在运行 uv sync 时，若发现 pyproject.toml 被修改过，且当前目录下没有 uv.lock，会自动调用依赖解析器生成一份新锁文件并立即安装。

但如果已有 uv.lock，uv 默认跳过重新解析，直接按锁文件安装——哪怕 pyproject.toml 已增删依赖。此时需手动触发更新。

执行：uv lock

这会读取当前 pyproject.toml 的全部依赖声明（包括 [project.dependencies]、[project.optional-dependencies]、[tool.uv.sources] 等），重新计算满足约束的最小兼容依赖图，并覆写 uv.lock。

强制升级依赖至最新兼容版本

默认的 uv lock 只在 pyproject.toml 显式变更时重算，它不会检查 PyPI 上是否有满足现有约束（如 ^2.31.0）的新版本。要让锁文件“向前走”，必须加 --upgrade 参数。

方法一：全局升级所有依赖

uv lock --upgrade

这会为每个依赖项尝试解析满足其语义化约束的**最新可用版本**（例如把 requests = "^2.31.0" 升到 2.32.3），并更新整个依赖树以解决新版本引入的传递依赖变化。

方法二：仅升级指定包

uv lock --upgrade-package requests --upgrade-package fastapi

该操作只对列出的包执行升级解析，其余包版本保持锁定不变。适合灰度验证某关键组件升级后的兼容性。

【注意：--upgrade 不会修改 pyproject.toml 中的版本约束字符串，只影响 uv.lock 中记录的具体版本】

精准控制升级行为

第一步：启用预发布版本支持（如需要）

uv 默认忽略 a、b、rc 等预发布标签的包。若项目明确依赖预发布版（例如测试 django==5.2a1），需显式允许：

uv lock --prerelease=allow

第二步：跳过已缓存的解析结果，强制全量重算

uv 内置强缓存机制，有时会复用旧解析结果导致看似没更新。加 --no-cache 可绕过缓存：

uv lock --upgrade --no-cache

第三步：预览变更而不实际写入文件

先确认升级是否符合预期，避免误操作污染锁文件：

uv lock --upgrade --dry-run

终端将打印将被升级/降级/新增/移除的包列表及其版本，不触碰磁盘上的 uv.lock。

验证锁文件是否生效

① 检查 uv.lock 文件修改时间是否更新

② 运行 uv tree requests（替换为任一包名），观察输出中显示的版本号是否与你期望的升级目标一致

③ 执行 uv pip sync，确认安装过程拉取的是新版本包（终端日志中会显示 requests==2.32.3 downloaded 类提示）