遇到依赖错误就删掉uv.lock文件：Python 3.15迁移实战经验

为什么我建议你遇到问题先删uv.lock

切换到 Python 3.15 之后，我开始偶尔遇到一些令人困惑的依赖错误。反复排查后，我总结出一条简单粗暴但极其有效的规则：如果拿不准，就删掉 uv.lock 文件。

这条经验来自一个真实的困境。我维护的大多数项目都是库（library），而按照惯例，库不应该附带 uv.lock 文件——因为如果库锁定了版本，会粗暴地影响所有使用它的下游项目。所以这些项目的 uv.lock 通常被写进 .gitignore，不会提交到仓库中。

但问题在于，运行 uv run pytest 之类的命令时，工具往往会顺手留下一个 uv.lock 文件。平时无伤大雅，可是一旦这个文件锁定了一个尚未提供 Python 3.15 wheel 的依赖版本，麻烦就来了。

一个典型的报错现场

就在今天早些时候，我遇到了一个很能说明问题的错误。执行测试时，uv 试图构建 watchfiles==1.1.1，结果直接失败，报错信息如下：

error: Failed to build `watchfiles==1.1.1`
  cause: Call to `maturin.build_wheel` failed

error: the configured Python interpreter version (3.15) is newer
than PyO3's maximum supported version (3.14)

这段报错的关键信息在后半句：当前配置的 Python 解释器版本是 3.15，而 PyO3 支持的最高版本是 3.14。也就是说，uv.lock 中钉死的那个 watchfiles 版本，底层依赖的 PyO3 还没有跟上 Python 3.15 的步伐，构建自然就失败了。

背后的机制

uv.lock 的作用是把依赖版本精确固定下来，确保不同环境下安装完全一致。这在应用项目里是好事，但在库项目里就成了负担：锁文件不会随着依赖更新而自动刷新，于是一个旧版本被牢牢钉住，哪怕新版本已经修复了兼容性问题，你也用不上。

当 Python 解释器升级到 3.15 后，这种滞后会被立刻放大。许多用 Rust 编写、通过 PyO3 暴露 Python 接口的包，需要等待 PyO3 更新到支持 3.15 的版本，才能发布对应的 wheel。而 uv.lock 里锁定的旧版本，恰好卡在这个时间差里。

uv.lock 与语义化版本解析

uv.lock 是 uv 工具生成的锁文件，其核心机制是将项目所有直接和传递依赖的版本、来源哈希、平台标记精确记录下来，从而实现跨机器、跨时间的可复现安装。uv 在解析依赖时通常遵循“最高可用版本”策略，但一旦存在锁文件，它会优先使用锁定版本，除非显式运行 uv lock --upgrade 或删除锁文件。

这种设计在应用项目中是优势，但在库项目中会导致“版本冻结”效应：当上游依赖发布修复了 Python 3.15 兼容性的新版本时，锁文件仍然指向旧版本，uv 不会自动感知并更新。因此，删除锁文件相当于强制 uv 重新走一遍依赖解析流程，根据当前环境（包括 Python 版本、平台标签）选择最新兼容版本。

PyO3 与 Python 版本兼容性

PyO3 是 Rust 生态中用于编写 Python 扩展模块的桥梁库，它通过 pyo3-build-config 在编译期检测目标 Python 解释器版本，并限制最大支持版本（如报错中的 3.14）。许多高性能 Python 包（如 watchfiles、pydantic-core、tokenizers）底层使用 Rust 和 PyO3 实现，因此每当 Python 发布新版本（如 3.15），这些包需要等待 PyO3 先行支持新版本，然后重新发布包含对应 wheel 的包版本。

这个过程存在天然的时间差：Python 3.15 发布后，PyO3 需要数周至数月适配，依赖 PyO3 的包再逐一发版。如果 uv.lock 恰好锁定了适配前的旧版本，构建就会因 PyO3 版本上限而失败。理解这一链条有助于判断：问题不在你的代码，而在版本锁定与生态适配的时间窗口。

删文件为什么有效

删掉 uv.lock 之后再次运行 uv run pytest，uv 会重新解析依赖，通常会选到一个更新的、已经支持 Python 3.15 的版本。于是问题消失。这个方法之所以有效，是因为它绕过了锁文件里那个已经过时的版本约束。

我并不是说锁文件没有价值。在部署生产应用时，锁定依赖版本是保证可复现性的重要手段。但对于库项目，以及本地开发时临时生成的锁文件，它的副作用往往大于收益。尤其当你在追踪一个诡异的构建错误时，删除锁文件是最快能排除干扰的步骤。

适用范围与注意事项

这条规则并不适用于所有场景。如果你在维护一个需要精确复现的生产环境，或者正在排查的问题与锁文件无关（比如确实是代码逻辑错误），删除锁文件反而可能掩盖问题。我的建议是把它当作一个诊断步骤：先删掉，看问题是否消失；如果消失，说明锁文件里存在过时版本；如果不消失，就继续排查其他方向。

另外，对于库项目，最好确认 uv.lock 已经加入 .gitignore，避免误提交。这既是尊重下游使用者的惯例，也能减少团队成员之间的环境差异。

库项目与锁文件的惯例

Python 库项目通常不提交锁文件，原因在于库的依赖声明（如 pyproject.toml 中的版本范围）应当保持宽松，以便下游项目能够自由解析出与自身环境兼容的依赖组合。如果库附带锁文件，下游工具可能误用该锁定版本，导致依赖冲突或版本滞后。

因此，库项目的 uv.lock 应写入 .gitignore，仅作为本地开发时的临时缓存。但 uv run、uv sync 等命令在缺少锁文件时会自动生成一个，这容易在无意中留下“本地锁文件”。当 Python 解释器升级后，这个本地锁文件可能锁定旧版本，成为构建失败的隐形源头。定期删除或忽略本地锁文件，是库项目开发中的一项低成本卫生习惯。

小结

Python 3.15 的迁移过程中，uv.lock 带来的版本滞后问题值得警惕。删掉它再重跑，往往能解决那些看似莫名其妙的依赖构建错误。这条经验简单，但在实际开发中非常管用。