Python 依赖锁定与可复现构建:从 requirements 到 lock
【摘要】 把一个项目从开发机搬到构建机,最常见的失败是「代码没变、环境变了」。requirements.txt 里写 flask==3.0.0 看起来已经锁定了,但它只锁了直接依赖,传递依赖仍然浮动: text flask==3.0.0 → werkzeug>=3.0 ← 没写,构建时可能拿到 3.0.1 也可能是 3.1.0 → jinja2>=3.1.2 传递依赖的小版本...
# Python 依赖锁定与可复现构建:从 requirements 到 lock
## 一、为什么「requirements.txt 加版本号」还不够
把一个项目从开发机搬到构建机,最常见的失败是「代码没变、环境变了」。`requirements.txt` 里写 `flask==3.0.0` 看起来已经锁定了,但它只锁了直接依赖,**传递依赖仍然浮动**:
```text
flask==3.0.0
→ werkzeug>=3.0 ← 没写,构建时可能拿到 3.0.1 也可能是 3.1.0
→ jinja2>=3.1.2
```
传递依赖的小版本升级就足以让 `markupsafe` 的 C 扩展编译失败,或者让 `pydantic v1/v2` 的导入路径改变。所以「可复现构建」的定义是:**同一份 lock 文件,在任何机器、任何时间,装出完全相同的包集合与版本**。
## 二、三种主流方案的取舍
| 方案 | lock 文件 | 优点 | 代价 |
|---|---|---|---|
| `pip` + `pip-compile`(pip-tools) | `requirements.txt`(完整锁定) | 生态最通用,CI 无需额外工具 | 需手动 `--generate-hashes` 才有完整性校验 |
| `uv` | `uv.lock` | 极快、内置锁定与哈希 | 较新,团队需统一工具链 |
| `poetry` | `poetry.lock` | 依赖分组、发布流程完整 | 解析慢,对旧包兼容偶有坑 |
中小项目建议:**pip-tools 打底,`uv` 提速**。两者产物都是标准 `requirements.txt`,CI 侧差别很小。
典型工作流(pip-tools):
```bash
# 1) 维护「意图」文件,只写直接依赖
cat requirements.in
# flask==3.0.*
# gunicorn==21.2.*
# psycopg[binary]==3.1.*
# 2) 生成完整锁定(含传递依赖与哈希)
pip-compile --generate-hashes --output-file=requirements.txt requirements.in
# 3) 安装只用锁定文件,且强制校验哈希
pip install --require-hashes -r requirements.txt
```
`--require-hashes` 是关键:它让「包被篡改或版本漂移」直接变成安装失败,而不是静默装上。
## 三、环境隔离:别在系统 Python 里装
三行纪律,能避免 80% 的「我这能跑你那不能跑」:
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
```
要检查某个包究竟来自哪里(虚拟环境 vs 系统),用:
```bash
python -c "import sys, site; print(sys.executable); print(site.getsitepackages())"
```
输出里出现 `/usr/lib/python3` 就说明没进虚拟环境。
## 四、验证可复现性:两台机器比对指纹
锁定是否真的生效,不能靠「装上了」。用一个可核对的指纹:
```bash
pip install --require-hashes -r requirements.txt
python - <<'PY'
import json, subprocess
out = subprocess.run(["pip","list","--format=json"], capture_output=True, text=True).stdout
pkgs = sorted((p["name"].lower(), p["version"]) for p in json.loads(out))
print("count:", len(pkgs))
print("digest:", __import__("hashlib").sha256(
"\n".join(f"{n}=={v}" for n, v in pkgs).encode()).hexdigest()[:16])
PY
```
构建机与开发机跑同一段脚本,`digest` 必须一致。不一致时先看 `pip list` 差集,再决定是补锁还是允许差异。
## 五、常见坑
| 现象 | 根因 | 处置 |
|---|---|---|
| 本地能跑,CI 报 `ModuleNotFoundError` | CI 未使用 `--require-hashes`,装到了不同版本 | 统一用 lock 文件安装 |
| `pip-compile` 后依赖突然变多 | 输入文件里混入了传递依赖 | `requirements.in` 只保留直接依赖 |
| 某包始终装不上 | 平台 wheel 缺失,触发源码编译且缺头文件 | 锁到有 wheel 的平台/版本,或改用 `[binary]` 额外项 |
| 升级一个包导致全量重解析 | 锁定粒度太粗 | 把「框架依赖」与「工具类依赖」拆成两个 lock 文件 |
## 六、代价与不适用
- **代价一:升级变成显式动作**。lock 生效后,安全补丁必须主动 `pip-compile -U ` 才能进入,需要定期跑一次依赖更新,否则会积累大量待升级项。
- **代价二:哈希校验会拖慢安装**。大项目首次安装多出数秒,换来的是可审计性。
- **代价三:多平台需多份 lock**。Linux 与 macOS 的 wheel 集合不同,跨平台项目要按平台分别锁定。
- **不适用**:一次性脚本、临时数据分析环境,不需要 lock;强行引入只会增加摩擦。
## 七、验收清单
1. `requirements.txt` 含全部传递依赖,且每行带 `--hash`;
2. CI 与开发机都用 `pip install --require-hashes` 安装;
3. 两台机器的包指纹 `digest` 一致;
4. 存在定期依赖更新机制(如每周一次 `pip-compile -U` 并跑测试);
5. 无任何一次安装发生在系统 Python 全局环境。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)