企业官网建设流程全解析

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

导读

pixi workspace platform remove是 pixi 用于管理工作区（workspace）声明平台的命令族中的"删除"操作，其核心职责是从pixi.toml（或pyproject.toml）中移除一个或多个平台声明，并同步更新锁文件（pixi.lock）与已安装的环境。本文以 remove.md 为骨架，结合pixi_cli、pixi_api与pixi_manifest三个 crate 的源码实现，讲解该命令的完整用法、参数语义、底层调用链与典型实战场景。读完本文，你将能够精确控制"哪些平台从工作区消失、锁文件如何更新、环境是否重建"，并理解其与add、edit、move、list等兄弟命令的分工。

命令概览与定位

remove是pixi workspace platform子命令族（见 platform/index.md）中的一员，与add、edit、move、list并列，负责对工作区平台做"增删改查"中的删除。命令的一行式描述为：

Remove platform(s) from the workspace file and updates the lock file

即：从工作区文件中移除平台，并更新锁文件。这一描述点出了命令的两阶段性质：先改清单（manifest），再同步派生状态（锁文件）。

其完整用法为：

pixi workspace platform remove [OPTIONS] <PLATFORM>...

从源码 platform.rs 的RemoveArgs定义可以看到，remove还注册了可见别名rm（#[clap(visible_alias = "rm")]），因此以下两条命令等价：

pixi workspace platform remove linux-64 pixi workspace platform rm linux-64

与add（pixi workspace platform add [PLATFORM|NAME=PLATFORM|__NAME[=VERSION[=BUILD]]]...，见 add.md）不同，remove的位置参数只接受平台名称（PixiPlatformName），不支持name=subdir形式，也不接受虚拟包原始规格（__name=...）——删除操作只需要标识出"哪一个平台"即可。

位置参数<PLATFORM>...

pixi workspace platform remove <PLATFORM>...

• 含义：要移除的平台名称（the platform name(s) to remove）。
• 可重复：May be provided more than once，一条命令可以同时移除多个平台，例如pixi workspace platform remove linux-64 osx-arm64 win-64。
• 必填：required: true，不传平台名会直接报错退出。

在源码中，该参数定义为：

#[clap(required = true, num_args=1.., value_name = "PLATFORM")] pub platforms: Vec<PixiPlatformName>,

（见 platform.rs）。num_args=1..使其可以接收任意数量的位置参数。

名称校验与查找：execute_remove会先在当前工作区的已声明平台列表里按名称查找每个目标平台，找不到时给出明确错误"workspace does not define a platform named '...'"（见 platform.rs 的execute_remove实现）。也就是说，命令不会静默忽略不存在的平台名，而是直接拒绝执行，避免用户因拼写错误误以为平台已被移除。

选项详解

--no-install：只更新锁文件，不重建环境

--no-install

• 含义：Don't update the environment, only remove the platform(s) from the lock file —— 不移除/更新本地环境目录，仅把平台从锁文件中移除。
• 环境变量：PIXI_NO_INSTALL。该选项可以直接以环境变量形式注入，适合在 CI 中统一控制。

源码中该选项声明为#[clap(long, env = "PIXI_NO_INSTALL")]（见 platform.rs）。

为什么需要这个开关：移除平台后默认行为是更新锁文件并同步安装状态（对当前机器而言，被移除的平台如果正是本机平台，环境会被卸载重建）。当只希望修改清单、暂时不动本地.pixi/envs目录时（例如在 CI 批量调整、或准备提交后由其他机器安装），加--no-install可以显著减少 I/O 和耗时。其语义与add、edit、move中的同名选项完全一致，都是"改清单 + 刷新锁文件，但不触碰环境"。

--feature/-f <FEATURE>：从指定 feature 移除平台

--feature (-f) <FEATURE>

• 含义：The name of the feature to remove the platform from —— 指定从某个非默认 feature 的平台列表中移除平台。

pixi 的 manifest 中，平台声明可以出现在两个层面：

1. 工作区默认层面（[workspace]下的platforms），作用于默认 feature 与继承它的所有环境；
2. feature 层面（[feature.<name>]下的platforms），只作用于该 feature 及其派生的环境。

不带--feature时，remove移除的是工作区默认平台；带--feature cuda时，则从名为cuda的 feature 的平台列表里移除。在pixi_api层，FeatureName::is_default()决定走哪条移除路径（见 context.rs 与 platform.rs）。

--environment/-e <ENVIRONMENT>：从环境内联平台移除

--environment (-e) <ENVIRONMENT>

• 含义：The environment to remove the platform from. The platform is removed from the platforms defined inline on the environment —— 将平台从某个环境的内联声明（inline platforms）中移除。

当pixi.toml中环境以如下形式内联声明平台时：

[environments] gpu = { platforms = ["linux-64", "linux-aarch64"], features = ["cuda"] }

pixi workspace platform remove linux-aarch64 -e gpu会精确地只从gpu环境的内联平台列表里移除linux-aarch64，而不会动工作区默认平台或其他环境。

冲突关系：--environment与--feature互斥（源码中#[clap(long, short, conflicts_with = "feature")]，见 platform.rs），一次调用只能二选一。这与add命令的设计保持一致（add.md 中同样列出这两个互斥选项），背后的原因在于：内联环境平台在 manifest 内部被合成为该环境对应的 feature 平台，两种语义如果同时给出会造成歧义。

选项速查表

底层执行链路：一次 remove 命令的完整旅程

remove命令的实际执行分为四层，从仓库源码可以完整还原调用链：

第 1 层：CLI 参数解析与校验（pixi_cli）

入口在 platform.rs 的execute：先通过WorkspaceLocator::for_cli()定位工作区（支持--manifest-path、--workspace、--script等全局选项决定搜索起点），然后按子命令分发。execute_remove（platform.rs）负责任务：

1. 取出工作区当前声明的平台列表；
2. 对每个<PLATFORM>名称逐一查找，校验其确实存在；
3. 调用workspace_ctx.remove_platforms(...)，把--feature/--environment归一化为FeatureName（feature_from_flags帮助函数）；
4. 透传--no-install与锁文件使用策略LockFileUsage::Update。

第 2 层：API 门面（pixi_api）

WorkspaceContext::remove_platforms只是薄封装，把调用转发给pixi_api::workspace::workspace::platform::remove（见 context.rs）。

第 3 层：核心实现（pixi_api/src/workspace/workspace/platform.rs）

remove函数的实现（platform.rs）依次执行：

// 1. 从 manifest 中移除平台 workspace.manifest().remove_platforms(platforms.iter(), &feature_name)?; // 2. 更新锁文件（必要时安装环境） update_platform_lock_file_and_prefix(workspace.workspace(), ..., no_install, lock_file_usage).await?; // 3. 持久化修改后的 manifest workspace.save().await.into_diagnostic()?; // 4. 向用户报告 interface.success(&format!("Removed {platform} ...")).await;

注意步骤 2 中的update_platform_lock_file_and_prefix：它同时处理锁文件更新与环境同步，--no-install正是在这里起作用——true时跳过环境前缀（prefix）的安装/卸载，只做锁文件层面的刷新。步骤 4 的报告文案会根据目标是否为默认 feature 而变化：默认时输出Removed linux-64，非默认时输出Removed linux-64 from <feature>（feature.user_facing()）。

第 4 层：manifest 写入（pixi_manifest）

最底层是 workspace.rs 的remove_platforms，它按feature_name分派：

• 默认 feature →remove_workspace_platforms（workspace.rs）：从内存模型与 TOML 文档中同时移除。值得注意的工程细节是，TOML 侧的更新采用retain-and-filter（保留过滤）而非清空重建，因此文件中幸存的平台条目会保留用户原有的引号风格与排版格式（pixi_toml_edit::retain_array_elements）。数组元素既可以是普通字符串（"linux-64"），也可以是内联表（自定义命名平台的{ name = "gpu-linux", subdir = "linux-64" }），移除逻辑对两者都做了处理。
• 非默认 feature →remove_feature_platforms（workspace.rs）：会提前检查目标 feature 是否真的声明了该平台（对照 feature 自身的平台列表而非工作区默认列表，因为 feature 可以显式 opt-in 到工作区默认未包含的平台），未声明则直接报错，避免静默无操作。

平台移除的影响范围：谁在引用这个平台？

移除平台前值得先确认它的引用面。pixi workspace platform list命令在实现上专门实现了environments_and_features_using（见 platform.rs），它会遍历 manifest 中所有 feature 与环境，找出哪些引用了某个平台，供用户在删除前评估影响：

• feature 层面：[feature.<name>]中显式列出该平台的 feature 会被标记；
• 环境层面：[environments.<name>]中内联声明该平台的环境会被标记；
• 环境继承：通过 workspace 默认平台间接使用该平台的环境也会被列出。

这条路径在remove命令中虽不直接触发，但揭示了平台声明的"多级引用"结构：同一平台可能同时出现在工作区默认、多个 feature 和多个环境的内联声明中。因此：

• 若平台只出现在工作区默认层面，remove后所有继承默认平台的环境都会受影响；
• 若平台被某个 feature 显式列出，即便从工作区默认移除，该 feature 仍可能保留自己的声明（源码注释明确指出：feature 显式列出platforms = [...]是对精确集合的 opt-in，不是对工作区默认的推导），需要额外用-f <feature>单独移除。

这也解释了为什么remove需要--feature/--environment两个定向选项：它们让用户可以精准打击某一个引用源，而不是一刀切地影响所有引用方。

实战示例

场景一：移除单个默认平台并同步环境

# 查看当前工作区平台 pixi workspace platform list # 移除 linux-64（默认层面），同时更新锁文件并重建本机环境 pixi workspace platform remove linux-64 # 等价写法（rm 别名） pixi workspace platform rm linux-64

执行后pixi.toml中的platforms = ["linux-64", "osx-arm64"]会变成platforms = ["osx-arm64"]，pixi.lock同步刷新。

场景二：一次性移除多个平台

pixi workspace platform remove osx-64 win-32

<PLATFORM>...可重复传入，一条命令批量清理不再需要支持的平台。

场景三：只改清单，不动本地环境

# 适合 CI 或准备提交的场景：锁文件更新，但 .pixi/envs 目录保持不变 PIXI_NO_INSTALL=1 pixi workspace platform remove linux-aarch64 # 与命令行参数等价 pixi workspace platform remove linux-aarch64 --no-install

场景四：从特定 feature 移除

[feature.cuda] platforms = ["linux-64", "linux-aarch64"]

# 只移除 cuda feature 中的 linux-aarch64，工作区默认平台不受影响 pixi workspace platform remove linux-aarch64 -f cuda

成功后输出形如Removed linux-aarch64 from cuda。

场景五：从环境内联平台移除

[environments] gpu = { platforms = ["linux-64", "linux-aarch64"], features = ["cuda"] }

# 只移除 gpu 环境内联声明中的 linux-aarch64 pixi workspace platform remove linux-aarch64 -e gpu

与相关命令的配合

remove是平台生命周期管理的一半——另一半是add：

• add（add.md）：增加平台，支持--auto-detect探测本机、--cuda/--archspec/--glibc/--linux/--macos/--windows等虚拟包声明，以及<name>=<subdir>自定义平台命名；
• edit：修改已有平台的 subdir 或虚拟包；
• move：调整平台顺序（选择优先级）；
• list：查看全部平台与引用关系，删除前建议先跑一遍。

命令族统一挂在pixi workspace platform之下（index.md），并共享--no-config、--config-file、--manifest-path、--workspace、--script等全局/配置选项。

测试验证：仓库如何保证移除行为正确

仓库为remove的实现提供了直接的单测佐证（位于 platform.rs 的 tests 模块）：

• test_remove_host_platform_without_no_install：构造platforms = ["<当前平台>"]的工作区，在不带--no-install的情况下移除本机平台，断言成功（即"移除后更新环境"路径正常）；
• test_remove_sole_foreign_platform_without_no_install：构造仅含win-64的工作区，在 Linux/非 win 机器上移除该外部平台并更新锁文件，断言成功——覆盖"移除非本机平台"的场景。

两个用例分别验证了"移除本机平台（触发环境重建）"与"移除外部平台（仅锁文件变化）"两条分支，与--no-install选项的语义形成互补：默认行为更新环境，外部平台因为无法在本机安装，实际效果接近只更新锁文件。

小结

pixi workspace platform remove是一个设计收敛、行为可预期的清单管理命令：位置参数标识目标（可批量）、--feature/--environment定向到具体的声明层级（互斥）、--no-install控制是否触碰本机环境（支持PIXI_NO_INSTALL环境变量）。从 platform.rs 到 context.rs、再到 workspace.rs 与 manifests/workspace.rs 的四层调用链，完整覆盖了"解析 → 校验 → 移除 → 锁文件/环境同步 → 保存 → 报告"的全过程，并对不存在的平台名、feature 未声明平台等错误做了前置拦截。掌握本命令后，配合add/edit/move/list即可完成对工作区跨平台声明的全生命周期管理。

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