uv 锁文件：本地能跑，CI 为什么还会失败

先区分“依赖需求”“解析结果”和“本机环境”。术语定义见 锁文件，本文只讲排障步骤。

三份内容不能混为一谈

pyproject.toml 声明需求，uv.lock 固定解析结果，.venv/ 是当前机器安装好的环境。只在本机手工安装一个包，别人拉代码后不一定能复现。

一次检查的顺序

在项目根目录按目的选择命令，不必全部运行：

uv lock --check
uv sync --locked
uv run --locked python -c "import sys; print(sys.version)"

第一条检查声明与锁文件的一致性；后两条在需要改锁时失败。--frozen 跳过一致性检查，适合特定构建分层，不能替代 CI 的一致性校验。

如果刚改了依赖，先用 uv lock 生成解析结果，审查变化，再把声明与锁文件一起提交。升级和冲突合并也先看需求，不为消除冲突直接删锁文件。

还会有哪些差异

锁文件不锁操作系统、驱动和外部服务。确认 Python 版本、依赖组、extras 及平台条件，再比较本地与 CI。同步可能移除不属于目标依赖集合的包，项目依赖应通过项目配置维护。

参考：uv 锁定与同步。命令语义复核：2026-10-14；本文未声称对任意项目实际执行上述命令。