"在我机器上能跑"大概是程序员最心虚的一句话。而它背后十有八九是依赖在作怪:同一份 requirements.txt,今天装和上周装,拉到的版本可能就不一样;更离谱的是,两台机器同时装,也可能因为某个间接依赖悄悄发了新版而结果不同。依赖锁不住,构建就不可复现(reproducible builds)——你没法向同事、向生产环境、向三个月后的自己保证"跑出来的东西一模一样"。
这件事今年更该被提上日程了:uv 已经坐稳 Python 依赖管理的事实标准,0.13 版本起默认直接拉取 Python 3.15;与此同时 PEP 751 把 pylock.toml 推上了台面,锁文件有望跨工具通用。换句话说,"把依赖锁死"不再是可选项,而是基本功。
更现实的代价是排障成本:当生产环境因为一个没锁住的间接依赖崩了,你要在几百个包里大海捞针。可复现,省下的就是这些深夜救火。
本文对比 pip / Poetry / uv,讲清为什么该用 uv 来锁依赖,并给你能直接抄走的 CI 与 Docker 模板。
三款工具怎么选
先把三者的定位对齐,免得你还在纠结"要不要换":
- pip
:装得快,但只管"装"、不管"锁"。requirements.txt 默认只记顶层包名,连版本都可能不写全,一撞上版本漂移就抓瞎。 - Poetry
:有 poetry.lock,能做到可复现,生态也成熟;但它是纯 Python 写的解析器,在大依赖树上安装偏慢,而且这套锁文件只有 Poetry 自己认,换工具就得重来。 - uv
:用 Rust 写,解析和安装比 pip 快一个数量级,常见工程能省下几十秒到几分钟;天生带 uv.lock,解析、安装、建虚拟环境、管 Python 版本一把梭,还兼容大部分 pip 参数。
一句话:要可复现必须有锁文件;要又快又通用,uv 是当下的答案。如果你已经在用 Poetry,迁移成本也低:uv 能直接读现有的 pyproject.toml,跑一次 uv lock 就生成 uv.lock,几乎无痛;而且 uv 的命令刻意贴近 pip,新人上手几乎零门槛。当然,uv 也不是银弹:它迭代很快,个别命令仍带预览标记,团队可以先从稳定命令(uv add / uv sync / uv lock)起步,避开 --preview 的实验特性。
uv add 别绕开锁
pip 用户的肌肉记忆是 pip install xxx。但在 uv 工程里,请改口用 uv add xxx,差别就在一个"锁"字。
锁文件(lockfile)到底是什么?uv.lock 不是 requirements.txt 的翻版,它把整棵依赖树——包括每一个间接依赖、每一个被解析出的具体版本、每一份用于校验的哈希值——都钉成一张完整快照。你的 pyproject.toml 只负责声明"我要哪些顶层依赖",uv 在背后生成并维护 uv.lock,保证任何人、任何机器、任何时间,装出来的依赖集合完全一致。
# 正确:写进 pyproject,并自动更新 uv.lock
uv add requests
# 危险:直接 pip install,包装进环境却绕开了锁文件
# 下次别人 uv sync 时根本不知道这个包存在
pip install requests
有人会问:uv sync 和 pip install -r requirements.txt 到底差在哪?答案是 uv sync 严格照着 uv.lock 装,锁里没有的绝不装、锁里有的一个不少;而 pip 默认按名字去索引现找,今天和明天的"最新兼容版"可能不同。锁,就是把"兼容"变成"确定"。用 pip install 绕开 uv,等于在墙上凿了个洞:你本地能跑,CI 和同事的环境却缺了这一块,可复现性当场破功。如果必须临时装个调试工具,也尽量走 uv pip install,并随后用 uv lock --frozen 约束,别让锁文件在无人察觉时悄悄过期。
默认挡住混淆攻击
依赖混淆(dependency confusion)是近年高发的供应链攻击。原理很简单:你们公司有个内部私有包,比如叫 internal-utils;攻击者猜到这个名字,就在公共 PyPI 上发布一个同名、但版本号更高的 internal-utils,里面塞满恶意代码。一旦构建系统在没有私有索引命中时跑去公网找包,就会因为"高版本优先"误装攻击者的包。
uv 的默认索引策略 first-index 恰好堵住这个洞:它按你配置的索引顺序查找,一旦在某个索引里找到该包,就只认这个索引,绝不再去后面的索引比版本。只要把私有索引排在 PyPI 之前,internal-utils 在私有源就被"认领",公网那个同名高版本根本没机会登场。想确认自己的私有源确实排在前,用 uv tree 或 uv pip list 看解析来源即可。
# 默认即是 first-index,通常无需额外配置
uv sync --index-strategy first-index
# 千万别这样——会跨索引挑"最新",等于敞开混淆攻击
uv sync --index-strategy unsafe-best-match
默认配置就是最安全的配置,这正是 uv 在供应链上比"随手 pip"强的地方。中小团队尤其容易中招:他们常没有完善的私有源鉴权,构建脚本又默认信任公网,等于把门虚掩着。uv 的默认值先帮你把这扇门合上,再谈别的优化。
锁文件进 CI 即停
把 uv.lock 提交进仓库,是复现性的核心。但光提交还不够,得让 CI 替你盯着它。关键就是 --locked:它要求"锁文件必须和 pyproject 完全一致,否则直接失败",而不是偷偷帮你改锁。
# 锁不对齐就报错退出,CI 立刻红灯
uv sync --locked
# 老式 requirements 流同样支持
uv pip install --locked -r requirements.txt
没有 --locked,CI 可能默默用旧锁或重算新锁,把"依赖漂移"藏到运行时才爆。加上它,任何改了 pyproject 却忘更新锁的提交,都会在合并前被拦下。你也可以用 uv lock --check 单独校验,只查对齐、不装包。建议把锁的更新也纳入 PR 流程:谁改了依赖,谁就顺手跑 uv lock 并提交新锁,reviewer 一眼就能看出依赖树变了什么。失败即停的价值不只是拦错,更是把"依赖清单"变成团队可审计的资产:每次锁变更都有 diff、有评审、有回滚点。
audit 与冷却窗口
锁住版本不等于锁住安全。已锁的依赖里也可能藏着后来被曝出的漏洞,uv 内置了供应链扫描(预览功能),能直接对照漏洞库检查:
# 预览版命令,扫描已知漏洞
uv audit --preview
另一个容易被忽略的技巧是 exclude-newer——给依赖升级加一道"冷却窗口"。它只允许解析该时间之前发布的包,等于告诉 uv:"别去拉发布才几小时的新版本"。这能挡住一类隐蔽攻击:攻击者刚把一个恶意版本推上 PyPI,CI 当晚就无脑拉走了。
# 只接受 2026-01-01 之前发布的包,给新版本留观察期
uv sync --locked --exclude-newer 2026-01-01T00:00:00Z
把 exclude-newer 写进 CI,相当于给依赖装上"时差防火墙"。本地想复现 CI 行为也很简单:直接 uv sync --locked 即可,和 CI 用同一把锁,杜绝"CI 过了本地炸"。需要提醒,uv audit 仍处于预览阶段,生产关键链路建议同时保留专业 SCA 工具做交叉验证,别把鸡蛋放进同一个篮子。
Docker 缓存与锁
容器里一样要锁,而且能顺手用上 BuildKit 的缓存挂载,让 uv sync 在重建镜像时秒回,不再每次都重新下载整座依赖山:
FROM python:3.15-slim
COPY--from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
# 先拷锁文件,利用缓存挂载
COPY pyproject.toml uv.lock ./
RUN--mount=type=cache,target=/root/.cache/uv \
uvsync--locked--no-dev--no-install-project
# 再拷源码,独立分层
COPY . .
RUN--mount=type=cache,target=/root/.cache/uv \
uvsync--locked--no-dev
CMD ["uv", "run", "python", "app.py"]
--no-dev 让生产镜像不装测试、lint 等开发依赖,镜像更小更安全;缓存挂载把 ~/.cache/uv 留在构建机,省下重复下载。这里用了官方 uv 镜像,省去自己装 uv 的步骤。若采用多阶段构建,把 uv sync 放在 builder 阶段、再把虚拟环境拷进运行时镜像,能进一步瘦身;生产环境记得设 UV_LINK_MODE=copy,避免软链接在跨层拷贝时断裂。顺带一提,基础镜像也建议钉版本(如 python:3.15-slim 可进一步锁 digest),与 uv.lock 形成双层确定性。
模板直接拿走
下面是可直接落地的 GitHub Actions 模板(GitLab CI 思路一致:镜像里装 uv,跑 uv sync --locked 与 uv audit):
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.15"
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Sync (fail onlock drift)
run: uvsync--locked
- name: Audit (preview)
run: uvaudit--preview
- name: Test
run: uv run pytest
上线前还可在 CI 里固定 uv 版本(如 UV_VERSION=0.13.0),避免 uv 自身升级带来行为差异;本地用同一份锁和同一版本,做到"本地即 CI"。
组合拳总结:uv add 写依赖 → 提交 uv.lock → CI 用 uv sync --locked 失败即停 → uv audit 扫漏洞 → exclude-newer 设冷却窗口 → Docker 里 --locked --no-dev 加缓存挂载。从今天起,让你的 Python 依赖不再靠运气。


