pixi task list 命令详解：查看工作区任务的树形列表、JSON 输出与摘要模式

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

pixi task list是 pixi（用 Rust 编写的跨平台包管理器，构建于 Conda 生态之上）中用于列出工作区（workspace）内所有任务（task）的核心子命令。无论你是想快速确认某个环境可用哪些任务、以 JSON 格式将任务清单交给脚本或下游工具处理，还是想按机器可读格式为 shell 补全提供数据，本文将从用法、全部选项、输出格式到背后的源码实现逐一拆解，读完即可在日常开发中熟练运用。

命令概述与使用场景

pixi task list的作用一句话即可概括：List all tasks in the workspace（列出工作区中的所有任务）。它属于pixi task命令族，与 add（添加任务）、remove（移除任务）、alias（为任务创建别名）并列，用于任务的"读"侧操作，只查看不改动工作区配置。

典型使用场景包括：

• 开发时快速查看当前环境（或指定环境）下有哪些可执行任务；
• 在 CI 或脚本中调用--json获取结构化任务清单，用于后续自动化处理；
• 借助--summary一眼纵览"每个环境分别有哪些任务"；
• 为pixi run提供补全数据（隐藏的--machine-readable选项）。

基本用法

pixi task list [OPTIONS]

命令本身不需要任何位置参数，直接执行即可列出默认环境下的所有任务：

pixi task list

输出示例（任务较多时呈现为带描述的两列表格）：

Task Description build Compile the project in release mode test Run the test suite lint Run linters

当工作区中没有定义任何任务时，命令会向标准错误输出No tasks found并正常退出（返回码为 0），这在 crates/pixi_cli/src/task.rs 中有明确实现：

if tasks_per_env.is_empty() { eprintln!("No tasks found",); return Ok(()); }

选项详解

--summary/-s：按环境分组摘要

默认输出把所有环境中的任务去重后合并成一张表；而--summary则反过来，按环境分组、每个环境一行输出，并附带该环境在当前机器上的可运行性（runnability）标注：

Tasks per environment: default (by design): build, test, lint gpu (by accident): train, evaluate docs (no dependency): docs

可运行性后缀共有四种取值，定义见 crates/pixi_core/src/workspace/virtual_packages.rs，含义如下：

该标注由runnability_suffix函数渲染（crates/pixi_cli/src/task.rs），而"每个任务跨环境去重时保留最优判定"的逻辑则由runnability_rank的排序规则保证（crates/pixi_cli/src/task.rs）。

--environment <ENVIRONMENT>/-e：限定环境

默认情况下，pixi task list会列出工作区中所有环境（在非 summary 模式下合并去重展示）。使用-e可以只查看某一个环境：

pixi task list -e gpu pixi task list --environment gpu

如果指定的环境不存在，会报错unknown environment '<name>'。该错误来自 crates/pixi_api/src/workspace/task/mod.rs 中list_tasks的显式校验：

let explicit_environment = environment .map(|n| { workspace .environment(&n) .ok_or_else(|| miette::miette!("unknown environment '{n}'")) }) .transpose()?;

值得注意的是：--environment选项在--json模式下不会被读取——JSON 输出始终遍历工作区所有环境（见下文）。另外，-e同时还需要指定默认环境：当不指定该选项时，pixi 内部使用"默认环境"（即default环境）作为任务归属的查找起点。

--json：以 JSON 输出

--json会把任务清单序列化为结构化的 JSON 输出到标准输出，便于脚本解析。数据结构按"环境 → 环境内联任务 + 各 feature 的任务"组织，核心结构定义在 crates/pixi_cli/src/task.rs：

struct EnvTasks { environment: String, tasks: Vec<SerializableTask>, // 环境内联定义的任务 features: Vec<SerializableFeature>, // 各 feature 下的任务 } struct SerializableFeature { name: String, tasks: Vec<SerializableTask>, } struct SerializableTask { name: String, info: TaskInfo, // cmd / description / depends_on / args / cwd / env / ... }

输出形如：

[ { "environment": "default", "tasks": [], "features": [ { "name": "default", "tasks": [ { "name": "build", "cmd": "cargo build --release", "description": "Compile the project in release mode", "depends_on": [], "cwd": null, "env": null, "clean_env": false } ] } ] } ]

每条任务的info（TaskInfo）字段与 pixi.toml 中任务可配置的属性一一对应，包括：

• cmd：任务实际执行的命令；
• description：任务描述；
• depends_on：依赖的其他任务列表；
• args：可传递给任务的参数；
• cwd：工作目录（相对工作区根目录）；
• env：任务级环境变量；
• default_environment：默认环境；
• clean_env：是否隔离宿主 shell 环境；
• inputs/outputs：增量执行相关的输入输出声明。

print_tasks_json使用serde_json::to_string_pretty生成带缩进的 JSON（crates/pixi_cli/src/task.rs），而环境遍历顺序按环境名排序（sorted_by_key(|env| env.name().to_string())），保证输出稳定可预期。

输出行为与底层实现

树形/表格输出的合并去重规则

默认（非 summary、非 JSON）模式下，pixi task list会：

1. 汇总所有环境的任务，按任务名去重合并；
2. 若同一任务在多个环境出现，保留可运行性判定最优的那个；
3. 保留第一次出现的描述；
4. 用 tabwriter 对齐成Task Description两列，任务名按字典序排列；
5. 不可运行（Unsupported）环境中的任务行以暗色（dim）显示。

该逻辑位于 crates/pixi_cli/src/task.rs 的print_tasks函数，其中描述文本还会被折叠为单行（single_line），避免换行符破坏表格对齐。

机器可读模式（内部选项）

ListArgs中还定义了一个--machine-readable选项（crates/pixi_cli/src/task.rs），它在 CLI 帮助中默认隐藏（hide(true)），用于输出空格分隔的任务名列表，专供pixi run的命令补全使用：

let unformatted: String = tasks_per_env .values() .flat_map(|(_, tasks)| tasks.keys()) .sorted() .dedup() .map(|name| name.as_str()) .join(" ");

即输出如build docs lint test这样的单行内容。

底层数据来源：环境 → feature → 任务

list_tasks的完整数据流为（crates/pixi_api/src/workspace/task/mod.rs）：

1. 解析--environment参数，定位目标环境（若省略则取全部环境）；
2. 加载工作区 lock file（若存在），用于计算每个环境的可运行性；
3. 对每个环境调用get_filtered_tasks()拿到按当前平台过滤后的任务名集合；
4. 通过env.task(&task_name, best_declared_platform)取回任务对象并组装成最终映射；
5. 返回HashMap<EnvironmentName, (EnvironmentRunnability, HashMap<TaskName, Task>)>。

任务本身在 manifest 层被建模为Task枚举（crates/pixi_manifest/src/task.rs），共有四种形态：

pub enum Task { Plain(TemplateString), // 纯命令字符串 Execute(Box<Execute>), // 带 depends_on / cwd / env 等属性的执行任务 Alias(Alias), // 仅依赖其他任务的别名 Custom(Custom), // 自定义协议任务 }

pixi task list展示的任务名与描述即来源于这些被解析、过滤后的任务对象。

与pixi task其他子命令的配合

pixi task list通常与以下命令配合使用形成完整工作流：

• pixi task add：向工作区添加任务（支持--platform、--feature、--environment、--cwd、--env、--clean-env、--arg等丰富选项）；
• pixi task remove：按名称移除任务；
• pixi task alias：为已有任务创建别名；
• pixi run：实际执行列表中的任务。

例如，添加任务后立即验证：

pixi task add build "cargo build --release" --description "Compile in release mode" pixi task list --json | grep -A2 '"name": "build"'

此外，pixi task list与 pixi.toml 中的任务定义一一对应。任务既可定义在 feature 中（如[tasks.build]），也可内联定义在环境上（[environments.gpu.tasks]），两种来源都会出现在--json输出的features与tasks字段中。

小结

pixi task list虽是一个只读的"查询"命令，却是任务驱动开发中最常用的入口之一：默认表格视图适合人眼阅读，--summary适合快速对比各环境差异，--json适合脚本消费，隐藏的机器可读模式则为pixi run补全提供数据。理解其输出背后"环境 → feature → 任务"的解析链与可运行性判定逻辑，能帮助你在多环境、多平台工作区中准确判断"某个任务到底能不能在当前机器上跑"，从而更合理地组织任务与环境的对应关系。

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