Pixi 锁文件（pixi.lock）完全指南：从解析原理到可复现环境的工程实践

• 开发工具
• CLI
• 包管理器
• 任务调度

A lock file is the protector of the environments, and Pixi is the key to unlock it.

导读

本文围绕 Pixi 工作区中的pixi.lock锁文件展开，系统讲解它与 manifest（pixi.toml）之间的职责分工、锁文件在解析流程中的生成与更新时机、--frozen/--locked/--no-install等精细化控制选项，以及锁文件内部结构（environments 与 packages 两段式）、版本兼容策略和可满足性（satisfiability）校验规则。读完本文，你将能够熟练地把锁文件纳入版本管理，在 CI 与本地开发之间实现完全可复现的环境，并能为库类项目设计基于锁文件的兼容性测试工作流。

什么是锁文件：manifest 与 lock file 的分工

要理解锁文件，首先要分清两个文件的角色差异：

• manifest（pixi.toml）：列出你项目中的直接依赖（direct dependencies）。它描述的是"我想要什么"。
• lock file（pixi.lock）：列出在解析（dependency resolution）过程中最终被选中的精确依赖——每个包的名称、版本，以及其他对包管理有用的元数据。它描述的是"实际锁定了什么"。

当你安装环境时，manifest 会进入依赖解析流程：系统找出你所请求依赖的全部传递依赖（依赖的依赖，一直向下展开），并在解析过程中确保所有被解析出的版本彼此兼容。

锁文件以相对较小的文件体量换来了可复现性：安装器可以不关心包内容本身的获取与校验，仅依据锁文件就能重建出完全相同的环境。同时锁文件为机器而生、为人可读——它适合被阅读和审计，但不适合手工编辑：

!!! Warning "不要手工编辑锁文件" 锁文件是为机器构建的，只是做到了人类可读以便检查。它不应当被手动修改。

Pixi 中的锁文件

与许多现代包管理器一样，Pixi 对锁文件提供原生支持，文件固定命名为pixi.lock。

在创建锁文件时，Pixi 会针对 manifest 中列出的所有环境（environments）与所有平台（platforms）一次性完成包解析。这意味着一个锁文件可以同时覆盖 Linux、macOS、Windows 以及不同 CPU 架构下的环境需求，从而显著提升项目的可复现性。正因如此，在很多场景下，分享一个锁文件可以替代分享一个 Docker 容器——在 CI 中重建本地开发环境变得非常容易。

Pixi 锁文件保持人类可读，因此无需任何额外工具就能查看其中列出了哪些包，也能轻松跟踪文件的变更（前提是你不去手动改它）。

仓库的pixi.lock本身就展示了当前版本的锁文件格式（version: 7），而tests/data/lock_files/目录下则保留着各类用于测试的历史锁文件，例如 archspec.lock 就是一个完整的version: 6示例。

锁文件的变化：何时生成、何时更新

许多 Pixi 命令在锁文件不存在时会创建它，在需要时更新它。以安装一个包为例，Pixi 会经历如下流程：

1. 用户请求安装某个包
2. 依赖解析（dependency resolution）
3. 生成并写入锁文件
4. 安装解析出的包

此外，Pixi 会确保锁文件始终与manifest以及已安装环境保持同步。一旦检测到不同步，就会自动重新生成锁文件（详见后文"锁文件的可满足性"一节）。

以下命令会检查并在需要时自动更新锁文件：

• pixi install
• pixi run
• pixi shell
• pixi shell-hook
• pixi tree
• pixi list
• pixi add
• pixi remove

如果想移除锁文件，直接删除即可——当上述任一命令再次运行时，会以最新的包版本重新生成它。

在源码层面，锁文件的读写与求解逻辑集中在 crates/pixi_core/src/lock_file/ 模块：mod.rs定义了锁文件加载结果（LockFileLoadResult），update.rs中的update_lock_file负责在需要时重算并落盘；CLI 侧的 crates/pixi_cli/src/lock.rs 提供了独立的pixi lock子命令，用于"只求解环境并更新锁文件而不安装环境"。

控制 manifest、锁文件与环境三者关系的选项

如果你希望对 manifest、锁文件与最终环境之间的互动拥有更多控制权，可以使用以下命令行选项（定义于 crates/pixi_cli/src/lib.rs 的LockFileUsageConfig与 crates/pixi_cli/src/cli_config.rs 的NoInstallConfig）：

• --frozen：按锁文件中定义的环境安装，不更新pixi.lock（即使它已与 manifest 不同步）。也可通过环境变量PIXI_FROZEN控制（例如PIXI_FROZEN=true）。
• --locked：仅当pixi.lock与 manifest 文件保持同步时才安装，否则中止。也可通过环境变量PIXI_LOCKED控制（例如PIXI_LOCKED=true）。与--frozen互斥。
• --no-install：不修改环境，只修改锁文件。也可通过环境变量PIXI_NO_INSTALL控制（例如PIXI_NO_INSTALL=true）。

在实现上，to_usage()对两个标志做了优先级处理：当locked为真时优先得到LockFileUsage::Locked，否则frozen为真时得到LockFileUsage::Frozen，默认才是LockFileUsage::Update——这与文档中"两者冲突"的说明一致，且PIXI_LOCKED=true与PIXI_FROZEN=true同时设置时由locked胜出（这一点在 crates/pixi_cli/src/lib.rs 的测试用例中有明确覆盖）。另外，shell、shell-hook、run等命令还支持--as-is简写，等价于--no-install与--frozen的组合（见LockAndInstallConfig）。

提交你的锁文件

可复现性在一系列项目中至关重要（例如部署软件服务、科研项目、数据分析）。环境可复现有助于结果可复现——它确保你的开发者和部署机器使用完全相同的包。

犹豫是否要提交锁文件？请考虑以下几点：

• 用于可复现环境的 Docker 镜像体积总是更大。
• Git 与 YAML 格式协作良好，便于 diff 与审查。
• 锁文件充当依赖解析的缓存，带来更快的安装与 CI。
• 你暂时不需要它……直到你需要的那一刻。在压力下重建锁文件，远不如提前删除或忽略它来得容易。

库类项目的额外考量

然而，有一类项目不适合简单地把锁文件提交进仓库——那就是开发库（library）的项目。

库具有不断演进的特性，需要针对覆盖广泛包版本范围的环境进行测试，以确保兼容性，其中也包括最新可用版本的环境。如果你决定在库项目中提交锁文件，还需要额外考虑以下两点：

• 锁文件的升级节奏：你希望多久升级一次供开发者使用的锁文件？这些升级是要进入主仓库历史，还是通过自动化机器人（如 Renovate Bot 的 pixi manager）或自定义 CI 任务来管理？
• 针对最新版本的 CI 工作流：你是否需要一个针对最新依赖版本进行测试的工作流？如果需要，可以在 cron 调度的 CI 工作流中执行如下步骤：
  1. 在运行setup-pixiaction 之前删除pixi.lock
  2. 运行你的测试
  3. 如果测试失败：
     • 使用pixi-diff与pixi-diff-to-markdown对比新生成的pixi.lock与main分支上的差异
     • 自动提交一个 issue，以便在项目仓库中跟踪该问题

这些考量已经在社区项目中得到探索（例如 SciPy 曾在其 issue 追踪中讨论相关方案）。如果你最终决定不提交锁文件、放弃其收益，也可以借助社区提供的锁文件缓存 action 来缓存生成的锁文件以加速 CI。

从源码看 diff 能力

Pixi 仓库内置了锁文件差异对比能力：pixi_diffcrate（crates/pixi_diff/src/lib.rs）提供LockFileDiff与LockFileJsonDiff，而pixi lock命令在更新后会打印新旧锁文件的 diff，并支持--json输出结构化差异、--check在锁文件发生变化时以非零码退出（适合 CI 校验），以及--dry-run只计算不落盘（见 crates/pixi_cli/src/lock.rs）。这与文档中提到的pixi-diff工具链一脉相承。

文件结构

Pixi 锁文件由两个部分构成。

第一部分：工作区中使用的环境

这部分列出工作区中使用的环境及其包含的包：

environments: default: channels: - url: https://conda.anaconda.org/conda-forge/ packages: linux-64: ... - conda: https://conda.anaconda.org/conda-forge/linux-64/python-3.12.2-hab00c5b_0_cpython.conda ... osx-64: ... - conda: https://conda.anaconda.org/conda-forge/osx-64/python-3.12.2-h9f0c242_0_cpython.conda ...

每个平台（linux-64、osx-64等）下都以conda:URL 的形式列出被锁定的包——URL 本身即包标识符。仓库测试数据 archspec.lock 是这一结构的最小化真实示例。

第二部分：包的定义

紧随其后是每个包自身的完整定义，包含版本、构建号、哈希、依赖约束等信息：

- kind: conda name: python version: 3.12.2 build: h9f0c242_0_cpython subdir: osx-64 url: https://conda.anaconda.org/conda-forge/osx-64/python-3.12.2-h9f0c242_0_cpython.conda sha256: 7647ac06c3798a182a4bcb1ff58864f1ef81eb3acea6971295304c23e43252fb md5: 0179b8007ba008cf5bec11f3b3853902 depends: - bzip2 >=1.0.8,<2.0a0 - libexpat >=2.5.0,<3.0a0 - libffi >=3.4,<4.0a0 - libsqlite >=3.45.1,<4.0a0 - libzlib >=1.2.13,<1.3.0a0 - ncurses >=6.4,<7.0a0 - openssl >=3.2.1,<4.0a0 - readline >=8.2,<9.0a0 - tk >=8.6.13,<8.7.0a0 - tzdata - xz >=5.2.6,<6.0a0 constrains: - python_abi 3.12.* *_cp312 license: Python-2.0 size: 14596811 timestamp: 1708118065292

值得关注的字段含义：

• sha256/md5：包的完整性校验哈希，安装时可据此验证下载内容。
• depends：该包的运行时依赖及其版本区间（即 matchspec）。
• constrains：对环境中其他包的约束（不构成依赖关系，但会限制共存版本）。
• timestamp：包的发布时间戳（毫秒级），在可满足性校验中甚至可以作为匹配依据（见下文）。

需要说明的是，不同包记录的字段并不完全相同：例如没有depends的包可以不出现该键，部分包还会携带build_number、license_family、purls等字段（pypi 相关的包会记录purls以建立与 conda 包的映射）。仓库根目录的 pixi.lock（当前为version: 7）以及 tests/data/lock_files/ 下的历史锁文件都是研究真实字段组合的好素材。

锁文件的版本

锁文件还带有一个版本号，用于确保锁文件与本地pixi版本兼容：

version: 6

Pixi 对锁文件向后兼容（backward compatible）但非向前兼容（not forward compatible）：也就是说，你可以用较新版本的pixi读取较旧版本的锁文件，但反过来不行——较新版本的锁文件无法被较旧版本的pixi读取。

在源码中，这一策略体现在LockFileLoadResult::VersionMismatch：当锁文件版本高于当前pixi支持的最高版本时，加载会直接返回版本不匹配错误（见 crates/pixi_core/src/lock_file/mod.rs 与 crates/pixi_core/src/lock_file/update.rs 的LockFileLoadResult定义，以及其中version: 9999的测试用例）。

锁文件的可满足性

锁文件是环境的描述，它应当始终是可满足的（satisfiable）。可满足意味着：给定的 manifest 文件与已创建的环境都同锁文件保持同步。如果锁文件不可满足，Pixi 会自动生成一个新的锁文件。

判断锁文件是否可满足的检查步骤包括：

• manifest 文件中的所有environments都在锁文件中
• manifest 文件中的所有channels都在锁文件中
• manifest 文件中的所有packages都在锁文件中，且锁文件中的版本与 manifest 中的要求兼容——对conda和pypi包均如此
  • Conda 包使用matchspec进行匹配，它可以匹配我们存储在锁文件中的全部信息，甚至包括timestamp、subdir和license
• 如果添加了pypi-dependencies，锁文件中所有属于 Python 包的conda包都必须带有purls字段
• 所有pypieditable 包的哈希都是正确的
• 锁文件中每个包都只有唯一一条记录

以上为简化描述，完整逻辑见 crates/pixi_core/src/lock_file/satisfiability/mod.rs 及其子模块。

源码级验证

可满足性校验在实现上分层进行：verify_environment_satisfiability负责验证单个环境（crates/pixi_core/src/lock_file/satisfiability/environment.rs），它会比对锁文件与当前配置中的通道列表（包括顺序，因为通道顺序会影响求解结果）、平台、虚拟包等；verify_platform_satisfiability处理平台级校验，另有pypi.rs、source_record.rs等模块分别处理 pypi 包、源码依赖等场景。

该模块还维护了大量失败场景的 snapshot 测试（位于 crates/pixi_core/src/lock_file/satisfiability/snapshots/），覆盖了诸如missing-dependency、removed-environment、mismatch-channel-priority、pypi-index-mismatch、changed-platform-subdir、wheels-with-wrong-tags、too-many-platforms等数十种不同步情形。这些 snapshot 名称本身就是一份"什么会导致锁文件不可满足"的清单，是排查"Pixi 为什么重新解析"问题的实用参考。

实践建议总结

1. 把pixi.lock提交进版本控制：对于应用、服务与科研项目，提交锁文件是获得可复现环境的最简路径，其收益（确定性、CI 缓存加速、可审计的变更历史）远大于成本。
2. 区分场景使用标志：CI 中追求确定性优先使用--locked（不同步即失败）；需要沿用旧锁文件快速部署用--frozen；只想刷新依赖信息用--no-install或pixi lock。
3. 库项目单独设计策略：不要简单地把锁文件当作"万能药"，而是结合自动化升级与"最新版本兼容性"CI 工作流来平衡可复现与兼容性测试的需求。
4. 遇到意外重解析时，对照可满足性清单排查：环境的增删、通道顺序变化、pypi 依赖引入、包哈希不匹配等都会触发锁文件重建。

• 开发工具
• CLI
• 包管理器
• 任务调度