pixi task add 命令深度指南：为工作区添加可复用任务的完整实战

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

pixi task add是 Pixi 工作区中用于向pixi.toml声明式添加任务的命令行工具，它把一条或多条跨平台 shell 命令、依赖关系、环境变量与工作目录等属性自动写入 manifest 的[tasks]表。通过本文，你将掌握pixi task add的全部参数语义、任务类型自动判定的底层逻辑、--platform/--feature/--environment的作用域规则，以及它如何与pixi run配合构建可复用的任务流水线。

命令概览：一条命令，写入一个任务

pixi task add的作用是在当前工作区中注册一个新任务：它把任务名与要执行的命令组合，序列化为 TOML 并写入pixi.toml的[tasks]表（或对应的 feature / target 表中）。命令的标准格式为：

pixi task add [OPTIONS] <NAME> <COMMAND>...

其中<NAME>是任务名，<COMMAND>是一个或多个要实际执行的命令。在 CLI 中该子命令还提供了可见别名a（pixi task a与pixi task add等价），见 crates/pixi_cli/src/task.rs 中Operation::Add的定义。

添加成功后会收到类似Added task \build`: ninja -C .build的成功提示；该提示由 [crates/pixi_api/src/workspace/task/mod.rs](https://link.gitcode.com/i/038002085cd837dbf4241d5a113e81a8) 中的add_task` 函数生成，并在保存 manifest 之后输出。

参数速查表

上述参数与 crates/pixi_cli/src/task.rs 中AddArgs结构体的 clap 定义一一对应，是该命令所有受支持的输入。

快速上手：从简单命令到完整流水线

最简单的用法是添加一条普通命令：

# 在默认 feature、所有平台生效 pixi task add lint pylint

执行后pixi.toml中会出现：

[tasks] lint = "pylint"

任务之间可以通过--depends-on串联成流水线，这正是官方 高级任务文档 中cpp_sdl示例的推荐做法：

pixi task add configure "cmake -G Ninja -S . -B .build" pixi task add build "ninja -C .build" --depends-on configure pixi task add start ".build/bin/sdl_example" --depends-on build

对应生成的 manifest 内容：

[tasks] # Configures CMake configure = "cmake -G Ninja -S . -B .build" # Build the executable but make sure CMake is configured first. build = { cmd = "ninja -C .build", depends-on = ["configure"] } # Start the built executable start = { cmd = ".build/bin/sdl_example", depends-on = ["build"] }

任务会按依赖顺序依次执行：先configure（无依赖），再build（依赖configure），最后start（依赖build）。任一命令以非零退出码失败，后续任务都不会继续执行。之后只需pixi run start即可一键完成从配置到启动的全流程。

pixi task add还可以同时声明多个命令，例如：

pixi task add build "cmake --build .build" "ctest --test-dir .build"

多个命令会被拼接为一条命令字符串（拼接规则见下文“任务类型自动判定”一节）。若要并行执行多个命令，应使用多个--depends-on而非多个命令参数。

任务类型自动判定：Plain、Execute 还是 Alias

pixi task add并不是把输入原样塞进 manifest，而是依据输入组合自动选择任务的 TOML 表示形式。该逻辑实现在 crates/pixi_cli/src/task.rs 的From<AddArgs> for Task中：

• Alias（纯别名）：当命令部分为空（或全为空白）但--depends-on非空时，生成Alias类型。例如不写命令、只写依赖：

  pixi task add style fmt lint

  这在官方文档中被称为“shorthand syntax”，最终style只依赖fmt与lint两个任务，运行时按顺序执行二者。等价于显式别名命令pixi task alias style fmt lint。

• Plain（普通任务）：当depends_on为空，且cwd、env、default_environment、description、args全部未指定时，任务以字符串形式存储，例如lint = "pylint"。这是最紧凑的表示。
• Execute（复杂任务）：一旦使用了上述任一附加选项（--depends-on、--cwd、--env、--default-environment、--description、--arg、--clean-env中任意一个），任务就以内联表形式存储，例如build = { cmd = "ninja -C .build", depends-on = ["configure"] }。

命令部分的序列化规则是：如果只提供一个命令，直接使用该字符串；如果提供多个命令，则对每个参数调用quote()（定义于 crates/pixi_manifest/src/task.rs）——该函数会对包含空格、[、]、制表符、换行等特殊字符的参数加引号并转义其中的"与\，随后用空格连接，确保在跨平台 shell 中可正确执行。

Task枚举的三种变体（Plain、Execute、Alias，另有内部使用的Custom）定义在 crates/pixi_manifest/src/task.rs，Execute结构体的字段（cmd、inputs、outputs、depends_on、cwd、env、default_environment、description、clean_env、args）见同文件 L344-L379。

进阶选项逐项拆解

--depends-on：声明任务依赖

指定本任务运行前必须完成的其他任务，可多次使用。依赖任务按声明顺序依次执行；某一步失败则整条链路中断。注意--depends-on与命令同时给出时生成Execute任务，单独给出（不写命令）时则生成Alias任务。

--platform/-p：按平台区分任务

pixi task add支持把任务限定到某个平台，例如：

pixi task add build "make" --platform linux-64

生成：

[target.linux-64.tasks] build = "make"

平台名解析遵循与pixi add --platform相同的规则：先在[workspace].platforms中查找已声明的平台；若未声明但能解析为合法的 conda subdir（如osx-arm64），则自动将其添加到默认 feature 的platforms列表中，再写入任务。该“自动声明”逻辑在 crates/pixi_api/src/workspace/task/mod.rs 的declare_platform_and_add_task中实现，且对已声明的平台是幂等的。平台解析本身由resolve_task_platform（同文件 L27-L38）完成，它会基于[workspace].platforms使用resolve_platforms进行解析。

若要在多个平台配置不同的任务，可多次使用--platform分别添加（每次添加针对一个平台）。

--feature/-f与--environment/-e：任务的作用域

• --feature <FEATURE>：将任务写入指定 feature 的[feature.<name>.tasks]表。feature 是 manifest 中按需求组织依赖与任务的逻辑分组，可被多个环境引用。
• --environment <ENVIRONMENT>：将任务直接写入[environments.<name>].tasks（环境的内联任务表）。如果该环境尚不存在，会一并创建它。此选项与--feature互斥（conflicts_with = "feature"，见 crates/pixi_cli/src/task.rs）。

两标志的换算关系在 crates/pixi_cli/src/cli_config.rs 的feature_from_flags中定义：指定--environment时，目标 feature 是由该环境名合成出的FeatureName::environment(...)；否则使用--feature的值，缺省为默认 feature。pixi task add --environment dev serve "python serve.py"这类用法在 pixi_manifest 参考文档 中有专门说明——manifest 编辑类命令（pixi add、pixi remove、pixi task add/remove/alias等）统一支持用--environment替代--feature来定位内联内容。

默认情况下（两者均不指定），任务写入默认 feature 的顶层[tasks]表，对所有未设置no-default-feature的环境生效。

--cwd：设置任务工作目录

指定命令执行的相对目录（相对工作区根目录）。例如：

pixi task add build "npm run build" --cwd frontend

生成：

[tasks] build = { cmd = "npm run build", cwd = "frontend" }

--env：注入环境变量

以key=value形式设置任务运行时的环境变量，可多次传入。解析器要求值必须包含=，否则报错invalid KEY=value: no=found in ...，见 crates/pixi_cli/src/task.rs 的parse_key_val。

pixi task add run "python run.py" --env MODE=production --env DEBUG=0

生成：

[tasks] run = { cmd = "python run.py", env = { MODE = "production", DEBUG = "0" } }

环境变量值支持模板字符串（如{{ backend }}），在 pixi_manifest 参考文档 的任务示例中可以看到env={ BACKEND="{{ backend }}" }的用法。

--default-environment：指定任务的默认环境

当工作区有多个环境时，pixi run <task>默认在当前环境执行任务；通过--default-environment可以为任务固定运行环境：

pixi task add test "pytest" --default-environment test

生成：

[tasks] test = { cmd = "pytest", default-environment = "test" }

--description：添加任务描述

为任务添加描述文本，会在pixi task list的“Description”列中展示（列表输出实现见 crates/pixi_cli/src/task.rs 的print_tasks，其中描述会折叠为单行以保证表格对齐）。

pixi task add say-hello "echo hello world" --description "Greet the world."

--clean-env：隔离宿主环境

默认情况下任务会继承当前 shell 的环境变量；指定--clean-env后，任务只在 pixi 环境提供的最小变量集下运行，隔离宿主机环境污染。注意该行为存在平台差异（官方任务示例中标注了“Only on Unix!”），在 docs/workspace/advanced_tasks.md 与 pixi_manifest 参考文档 中均有体现。

--arg：声明任务参数

声明任务可接收的参数，供pixi run <task> -- <arg>传值使用，可多次提供。每个--arg可附带name=value的默认值与choices候选值；这些参数通过TaskArg结构体（crates/pixi_manifest/src/task.rs）建模，其中参数名禁止包含-字符。例如：

pixi task add backend "pytest" --arg backend=numpy --arg backend=torch

对应的 manifest 形式为：

[tasks] backend = { cmd = "pytest", args = [ { arg = "backend", default = "numpy", choices = ["numpy", "torch"] }, ] }

更完整的模板字符串与参数组合示例可见 pixi_manifest 参考文档 中的backend任务。

从 CLI 到磁盘：一次添加的完整调用链

pixi task add的执行并非只在内存中修改，而是经过一条完整的“CLI → API → manifest 编辑 → 落盘”链路：

1. CLI 解析：crates/pixi_cli/src/task.rs 中的add_task把AddArgs通过From<AddArgs> for Task转换为Task，将--environment/--feature换算为FeatureName，然后调用WorkspaceContext::add_task。
2. API 层：crates/pixi_api/src/workspace/task/mod.rs 中的add_task首先调用declare_platform_and_add_task完成平台自动声明与任务写入，随后workspace.save()将修改持久化到磁盘，最后通过 interface 输出成功信息。
3. Manifest 编辑：crates/pixi_manifest/src/manifests/workspace.rs 中的add_task会先检查同名任务是否已存在——若存在直接报错task <name> already exists（这也是重复添加同名任务时会遇到的错误），再通过ensure_inline_environment确保目标位置存在，并分别更新内存中的 workspace 结构与磁盘上的 TOML 文档。
4. TOML 序列化：crates/pixi_manifest/src/manifests/document.rs 中的add_task根据平台与 feature 定位目标表（[tasks]、[target.<platform>.tasks]、[feature.<name>.tasks]等），按任务类型写入字符串值或内联表；复杂字段（args、depends-on、env、cwd、default-environment、description）的逐项序列化逻辑见 crates/pixi_manifest/src/task.rs 的From<Task> for Item。

这一链路保证了pixi task add与pixi task alias、pixi task remove等命令使用完全一致的平台解析与写入规则，避免同一定义在不同命令下产生歧义。

任务表与最佳实践

[tasks]表的结构

pixi task add写入的目标表在 pixi_manifest 参考文档 中有完整说明：任务是工作区中自动化自定义命令的方式（如lint、format），本质上是跨平台的 shell 命令，统一语法在不同平台运行；任务最终由pixi run在 pixi 环境中执行，运行器为deno_task_shell。支持的任务形态包括字符串简写、{ cmd = ... }显式形式、带depends-on的依赖任务、纯depends-on别名、outputs/inputs文件追踪、cwd、env模板字符串、args参数、default-environment、clean-env等，全部可以在 pixi_manifest 参考文档 的任务示例中找到对应写法。

隐藏任务

如果不想让任务出现在pixi task list或pixi info中，可用_前缀命名，例如把depending改为_depending。这条规则在 pixi_manifest 参考文档 中有明确说明，且与pixi task add直接相关——添加任务时选择以_开头的名称即可实现隐藏。

不同平台的不同任务

若需为不同平台提供不同的命令实现，结合--platform分别添加，或直接在 manifest 中使用[target.<platform>.tasks]表（见 pixi_manifest 参考文档 的提示）。

与pixi run配合

添加完成后，任务通过pixi run <task>执行；带参数的任务可追加pixi run <task> -- <args>。任务列表可使用pixi task list（别名ls）查看，删除用pixi task remove（别名rm），纯依赖别名用pixi task alias（别名@），它们与add共用同一套平台/feature 解析机制，全部定义在 crates/pixi_cli/src/task.rs。

小结

pixi task add是 Pixi 工作区任务系统的入口命令，其价值在于把“任务定义”这一原本需要手写 TOML 的工作转化为可校验、可自动化的 CLI 操作：任务类型自动判定减少了手写复杂度，--platform/--feature/--environment让任务可以精准定位到平台与作用域，而底层与pixi task alias、pixi task remove保持一致的解析规则确保了工作区任务管理整体的一致性。掌握它，你就掌握了 Pixi 自动化流水线的第一块拼图。

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