Python packaging 26.2 的 pylock.toml 怎么接入：锁文件选择、环境复现与旧 pip 边界

团队把 Python 服务从测试机搬到 CI 时，最先暴露的往往不是业务代码，而是依赖描述：同一份 requirements.txt 在不同时间解析出了不同的小版本，换一台平台又因为 wheel 不同而出现安装差异。packaging 26.1/26.2 的锁文件支持让这件事多了一个标准化方向，但 pylock.toml 不是“把整台机器冻结”的魔法文件。

接入 pylock.toml 时，先把它当成经过解析的依赖安装记录，再单独固定 Python 解释器、平台、索引来源和构建策略；pip 26.1 可以作为新入口验证，旧 pip 则应保留明确的回退文件。

pylock.toml 的边界：锁的是安装结果，不是所有机器状态

锁文件的价值在于把一次依赖解析结果留下来，方便下一次安装按同一组版本和环境条件复现。它描述的是项目依赖层，不会替你冻结 Python 补丁版本、系统库、CPU 指令集、编译器或 PyPI 索引中的全部内容。尤其是带原生扩展的包，同一个版本可能对应多个平台 wheel；锁文件记录了选择条件，安装时仍要检查当前环境是否满足。

可以先用这张边界表判断文件该放什么：

pip 26.1 如何选择锁文件：安装器、来源与回退路径

当前 PyPA 工具建议把项目声明、构建后分发包和安装锁定分开看。packaging 26.1/26.2 的官方公告提到扩展锁文件支持，pip 26.1 使用 `-r pylock.toml` 读取锁文件；这给新环境提供了更直接的验证入口。命令本身不是兼容性证明，第一行检查应当固定在隔离环境中：

python -m pip --version
python --version
python -m pip install -r pylock.toml

如果项目仍要支持旧 pip，不要把两种格式混在同一个入口里。可以让 CI 的新任务读取 pylock.toml，旧运行线继续读取已经审核过的 requirements.txt；两者都由同一份 pyproject.toml 提供项目声明，但不能把 pyproject.toml 当锁文件，也不要让脚本根据失败信息静默换文件。这样升级安装器时，差异才会落在可比较的记录上。

把 pylock.toml 接入项目：从检查文件到复现安装

实际接入可以按“文件—解释器—来源—结果”四项记录推进。先确认 pylock.toml 和 pyproject.toml 位于项目根目录，随后在全新的虚拟环境里执行安装。不要只看命令是否返回 0，还要保存 pip 版本、Python 标识、关键依赖版本和索引配置的摘要。若锁文件含有环境标记，至少在 CI 的主要 Python 与平台组合上各跑一次。

安装后重点看两类偏差：一类是当前解释器不满足锁文件条件，另一类是索引没有提供当前平台可用的构建产物。前者要调整运行矩阵或重建锁文件，后者要检查 wheel、源码构建和索引镜像的供应范围。不要用“把版本号放宽”来掩盖来源缺失，那会让下一次解析重新漂移。

python -m pip freeze > /tmp/installed.txt
python -m pip check

升级与回退怎么定：预发布能力的生产边界

packaging 26.2 和 pip 26.1 的组合适合先放到 CI 或预发布环境验证。生产切换前，把新旧安装入口、Python 版本、平台矩阵和锁文件校验结果放在同一份构建记录里。回退时只回退工具链和依赖描述入口，不要顺手修改业务依赖；否则即使服务恢复，也很难判断问题来自解析器还是代码。

一个实用判断是：如果失败信息说格式无法识别，先查 pip 版本；如果提示环境标记不匹配，查 Python 与平台；如果找不到候选分发包，查索引、wheel 和源码构建条件。三类故障的修复动作不同，统一改 requirements.txt 往往只会把根因藏起来。

常见问题

pylock.toml 能不能替代 pyproject.toml？

不能。pyproject.toml 继续承担项目声明和构建元数据，pylock.toml 用来记录解析后的安装约束，两者解决的问题不同。

旧 pip 读不了 pylock.toml 时怎么办？

保留经过审核的 requirements.txt 作为显式回退入口，同时在 CI 中记录安装器版本；不要让脚本在失败后静默切换文件。

有了锁文件还需要固定 Python 版本吗？

需要。Python 实现、版本、ABI、操作系统和原生扩展平台都会影响可用分发包，锁文件不能单独覆盖这些条件。

为什么同一锁文件在另一台机器上仍可能失败？

常见原因是平台环境标记不匹配、索引缺少对应 wheel，或项目依赖源码构建时缺少系统工具。先分类证据，再决定调整矩阵、来源还是构建环境。

把 pylock.toml 接入项目，关键不是多放一个文件，而是把“依赖解析结果”和“安装环境前提”分开记录。新 pip 入口可以逐步验证，旧 pip 回退可以明确演练；这两条边界清楚后，复现问题才有可比较的证据。