Pixi 怎么在 CI 中检查 pixi.lock 是否和项目配置同步

在 CI 中执行 pixi lock --check，让 Pixi 计算锁文件是否需要变化：需要变化时返回非零退出码，适合阻断过期的 pixi.lock。检查不会把新锁文件写回磁盘，因此应保留这个退出码，而不是在检查前先运行普通 pixi lock 自动修复。下面以 GitHub Actions 为例，把检查接入仓库工作流。

Pixi 官方地址：https://pixi.prefix.dev/latest/reference/cli/pixi/lock/

GitHub 官方地址：https://github.com/

1. 打开工作流文件并加入锁文件检查

先确认同一提交中已经包含 pixi.toml 和 pixi.lock，且具有修改仓库工作流的权限。打开仓库的 Code → .github → workflows → 现有工作流文件 → 铅笔编辑按钮；如果已有测试工作流，可把下面的独立 job 合并进去，避免覆盖原有测试。新建文件时使用 .github/workflows/pixi-lock.yml。

编辑区中加入下面的最小工作流。示例假设项目位于仓库根目录，Pixi 与 setup action 使用官方示例中可确认的固定版本组合，不表示必须为所有仓库选择相同版本。实际项目应与团队使用的 Pixi 版本对齐，避免本地与 CI 解释项目配置的能力不同。

name: Pixi lock sync

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  lock-sync:
    runs-on: ubuntu-latest
    steps:
      # 先取出同一提交中的项目配置与锁文件。
      - uses: actions/checkout@v4
      # 只安装Pixi工具，避免安装项目时提前处理锁文件。
      - uses: prefix-dev/setup-pixi@v0.11.2
        with:
          pixi-version: v0.66.0
          run-install: false
      # 非零退出码直接让步骤失败，不吞掉检查结果。
      - name: Check lockfile
        run: pixi lock --check

完成此步时，编辑区应能看到名为 Check lockfile 的步骤和 run-install: false。后者让 setup-pixi 只安装工具，不安装项目环境，避免真正的检查开始前就发生其他环境准备动作。这里不运行测试任务，也不把安装成功当成锁文件同步的证明。

普通 pixi lock 会求解并更新锁文件；--check 用于判断这种计算是否带来变化。它不是只比较两个文件的修改时间，也不是简单比较文件名。项目的依赖声明变化后，CI 应基于当前提交中的配置与锁文件判断，而不能依赖开发者是否记得手动说明“已更新锁”。

2. 提交工作流，保留检查命令的退出码

点击编辑器上方的 Preview 查看变更范围，再点击 Commit changes…。在 Commit message 字段填写说明；按仓库规则选择新分支，并通过 Propose changes 或 Commit changes 保存。受保护分支应沿用项目的分支与拉取请求流程。

保存后，仓库文件页或拉取请求的变更列表应出现该工作流文件，且提交内容中仍然保留 Check lockfile。示例监听 push 与 pull_request，后续对应事件会触发运行；是否允许 Actions 运行、是否需要维护者批准，仍服从仓库的实际设置。

不要给该步骤加 continue-on-error，也不要在命令后追加 || true。如果包装脚本在 pixi 失败后继续执行其他成功命令，最终返回码也可能被覆盖。最小写法直接运行检查命令，能让步骤状态明确对应检查结果。

如果项目在子目录，应为检查步骤设置正确的 working-directory，或使用 Pixi 的 --manifest-path 指向配置文件。setup action 的目录选项不应被误认为会自动改变所有后续 run 步骤的目录。配置路径错误时，应先修正目标目录，而不是把所有失败都解释为锁文件过期。

3. 在 Actions 查看结果并修复过期锁文件

进入仓库 Actions → Pixi lock sync → 对应提交的运行 → Jobs → lock-sync → Check lockfile。查看这一步的完成状态及错误说明；重点确认检查步骤实际执行，而不是只看到工作流文件已经保存或工具已经下载。

需要修复时，在维护者的项目环境执行下面的动作，再审阅版本与依赖变化。不要让只负责检查的 CI 悄悄生成新锁文件后继续通过，那会掩盖提交中缺少锁文件更新的问题。

# 在项目目录更新锁文件；这是维护者修复动作，不放进CI检查步骤。
pixi lock
# 修复后重新检查同步状态，并审阅pixi.lock差异再提交。
pixi lock --check

本文未执行工作流或命令，三张图均为原创界面说明图。读者的实际判定依据应是对应提交的检查状态。若希望失败检查阻止合并，还需由仓库维护者在现有分支保护或规则配置中要求该检查；单独有一个失败 job，并不自动改变所有分支的合并规则。

为什么安装阶段就失败了？先看失败步骤名称，工具下载或环境问题不等于锁文件不一致。本文通过关闭项目安装让检查职责更清楚。

可以使用 frozen 来代替同步检查吗？不要仅因它不更新锁文件就视为等价。本文需要的是明确判断锁文件是否需要变化的 --check 语义。

非零退出码一定说明 pixi.lock 过期吗？不一定，解析与执行错误也会失败，应结合错误信息分类处理。

参考：Pixi lock 参数；setup-pixi 配置；GitHub 编辑文件；GitHub 查看工作流日志。