Python 依赖锁定与可复现构建:从 requirements 到 lock

举报
yd_299686804 发表于 2026/11/09 15:03:52 2026/11/09
【摘要】 把一个项目从开发机搬到构建机,最常见的失败是「代码没变、环境变了」。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)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。