Pixi 怎么按 feature 建隔离环境并运行同一个项目任务

如果一个项目既要用 Python 3.11 跑测试，又要用 Python 3.12 做兼容性检查，不必把依赖和任务复制两份。Pixi 的 feature 适合放可复用的依赖与任务，environment 才是实际安装、激活并运行任务的隔离环境。

官方地址：https://pixi.prefix.dev/latest/

官方文档：https://pixi.prefix.dev/latest/tutorials/multi_environment/

稳妥的配置方式是：先把 pytest 和 check 放进 qa feature，再让 py311、py312 两个 environment 复用这个 feature，运行时始终用 pixi run --environment 环境名 check 明确选择环境。

先分清 feature 和 environment

Pixi 中这两个概念很容易混在一起。feature 更像一组可以被组合的项目内容，里面可以放依赖、任务、平台和激活配置；environment 是这些内容的组合结果，Pixi 会为它安装依赖并提供运行任务的环境。

因此，看到“任务明明写在 feature 里，却不能直接运行”的提示时，通常不是任务内容错了，而是还没有把 feature 组合进某个 environment。

创建项目并找到配置入口

先为示例建立一个干净的 Pixi 项目。命令执行后，项目根目录中的 pixi.toml 是后续配置入口；如果项目已经存在，直接进入它的根目录即可。

1. 打开命令行，执行 pixi init feature-lab。
2. 进入项目目录：cd feature-lab。
3. 打开项目根目录的 pixi.toml，确认能看到 [project] 配置。

pixi init feature-lab
cd feature-lab
# 这两条命令只创建项目和进入目录，不会替你生成多个隔离环境
# 后续的 feature 与 environment 都应写在同一个 pixi.toml 中

这里的可见确认点是：文件树中有 pixi.toml，当前目录就是项目根目录。不要在项目的子目录另建一份配置，否则运行命令可能找不到预期的工作区。

把共享依赖和任务放进 qa feature

在 pixi.toml 中添加一个 qa feature。这个 feature 只负责“测试工具是什么”和“任务叫什么”，不负责决定 Python 版本；版本差异留给不同的 environment。

[feature.qa.dependencies]
pytest = "*"

[feature.qa.tasks]
check = "pytest -q"
# pytest 属于共享测试工具，check 是两个环境都要执行的同名任务
# 任务命令保持简短，具体 Python 版本由调用它的 environment 决定

如果更习惯使用 Pixi 命令添加内容，也可以在项目根目录依次执行下面两条命令；它们表达的仍然是“依赖和任务属于 qa feature”。

pixi add --feature qa pytest
pixi task add --feature qa check "pytest -q"
# --feature qa 把内容写入 qa，而不是默认 feature
# 不要把 qa 工具误加到默认依赖，否则所有环境都会携带它

保存后，在配置工作台中应能看到一个名为 qa 的 feature、一个 pytest 依赖和一个 check 任务。下面这张图是为了帮助定位这些配置区域的原创界面说明图，不是 Pixi 实际界面的截图。

建立两个复用同一任务的隔离环境

接下来定义两个 environment。它们都引入 qa，但各自直接声明 Python 版本。这样 check 的任务定义只有一份，依赖环境却能分别求解和安装。

[environments.py311]
features = ["qa"]
dependencies = { python = "3.11.*" }

[environments.py312]
features = ["qa"]
dependencies = { python = "3.12.*" }
# 两个 environment 共享 qa 的 pytest 和 check
# Python 版本写在各自 environment 中，形成可对照的隔离组合

如果项目还需要普通开发环境，可以继续保留默认环境；本例的重点是两个明确命名的环境。配置完成后，项目文件中应该同时出现 [feature.qa.*]、[environments.py311] 和 [environments.py312] 三组信息。

也可以用环境管理命令先创建组合，再回到配置文件补充版本约束：

pixi workspace environment add py311 --feature qa
pixi workspace environment add py312 --feature qa
# 这两个命令把 qa feature 组合进两个 environment
# 若要固定不同 Python 版本，仍应在对应 environment 中明确声明 dependencies

保存配置后，Pixi 会在需要时为每个 environment 准备自己的目录和锁定结果。不要把 .pixi/envs/py311 手工复制成 py312，隔离环境应该由配置和求解结果产生。

用同一个 check 任务分别运行

现在同名任务已经出现在两个 environment 中，运行时要把环境名写清楚。这样不会依赖当前 shell 的激活状态，也不会因为多个环境都有 check 而进入交互选择。

pixi run --environment py311 check
# -e 是 --environment 的短写；这里让 check 使用 Python 3.11 环境

pixi run -e py312 check
# 同一个 check 任务换到 Python 3.12 环境执行

在任务运行面板里，先选择环境字段 py312，再选择任务字段 check；如果切换到 py311，任务名称仍然保持 check。两次配置的区别应该只体现在 environment 和其对应的 Python 版本。

如果直接执行 pixi run check，而多个 environment 都提供了这个任务，Pixi 可能要求你选择环境。生产脚本、CI 配置和排错记录更适合显式写出 --environment，让命令的运行对象固定下来。

任务找不到或环境选错时怎么排查

软件设置类问题通常集中在三处：feature 没有加入 environment、任务写到了错误的表、调用时没有指定 environment。可以按下面的顺序处理。

1. 确认任务表：任务应该位于 [feature.qa.tasks]，名称是 check。
2. 确认组合表：两个 environment 的 features 都包含 qa。
3. 确认调用参数：使用 pixi run -e py311 check 或 pixi run -e py312 check，不要只看当前目录名称。
4. 确认依赖范围：Python 版本写在对应 environment，而不是误写到另一个 feature 中。

pixi list --environment py311
pixi list --environment py312
# 分别查看两个环境的依赖清单，重点确认 Python 与 pytest 是否落在预期环境
# 这里只查看配置结果，不把两个环境合并成一个默认环境

需要回退时只撤掉组合关系

如果临时兼容性测试结束，不要直接删除锁文件或手工清空 .pixi 目录。先从 pixi.toml 中移除对应的 environment，或者删掉它的 qa feature 关系；之后再按项目的正常锁定流程更新依赖。

[environments.py312]
# 回退时删除整个 py312 environment 配置块，保留 qa 供 py311 使用
# 如果 qa 也不再需要，再删除 feature.qa 的依赖与任务配置

这种回退方式保留了共享任务的单一来源，也不会把一次临时测试误变成默认开发环境。重新需要兼容性检查时，再新增 environment 并复用现有 feature 即可。

相关问题

feature 能不能直接当成运行环境？

不能把 feature 理解为独立环境。它主要用于复用依赖、任务和其他配置，必须被某个 environment 组合后，才能安装并运行其中的任务。

为什么同一个任务名会弹出环境选择？

因为多个 environment 都提供了这个任务，Pixi 无法替你判断目标版本。脚本和 CI 中直接使用 pixi run -e 环境名 任务名 就能消除歧义。

两个 environment 一定要共享 feature 吗？

不一定。只属于一个 environment 的依赖可以直接写在该 environment 中；当两个环境要复用同一组工具或任务时，放进 feature 更容易保持一致。

记住这条配置关系即可：feature 放共享内容，environment 负责隔离组合，pixi run 用环境名锁定任务执行对象。