企业官网建设流程全解析

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

pixi add是 pixi 生态中最常用的依赖管理命令，负责把 conda 包、PyPI 包、Git 源码包乃至本地包以声明式的方式写入工作区清单（pixi.toml或pyproject.toml），并自动完成求解、锁定与安装。本文以官方 CLI 参考文档 docs/reference/cli/pixi/add.md 及其示例扩展（docs/reference/cli/pixi/add_extender）为主体骨架，结合源码实现（crates/pixi_cli/src/add.rs、crates/pixi_cli/src/cli_config.rs）与集成测试，系统讲解该命令的每个参数、版本选择策略、与pyproject.toml的原生集成以及背后的执行链路。读完本文，你将能够熟练地用一条命令管理 conda/PyPI/Git/本地路径四种来源的依赖，并理解其锁定与安装行为。

命令概览与基本语法

pixi add的作用是向当前工作区（workspace）添加依赖。它接受一个或多个依赖说明符（spec），每个说明符可以是：

• conda 包名或 MatchSpec（如python=3.9、"pytorch>=1.8"）；
• PyPI 依赖说明（配合--pypi使用，遵循 PEP 508 语法）；
• 本地.conda或.tar.bz2包文件的绝对路径；
• 本地源码包目录、recipe.yaml/recipe.yml/package.xml文件（配合--path使用）。

pixi add [OPTIONS] <SPEC>...

其中<SPEC>是必填位置参数，可以重复提供多次，实现一次性添加多个依赖。当没有提供任何 spec 时，命令会直接打印帮助信息（源码中通过arg_required_else_help = true实现，见 crates/pixi_cli/src/add.rs）。

基本用法：

pixi add numpy # 添加 numpy，自动选择求解环境中可用的最新版本 pixi add python pytest # 一次添加多个包，它们会被一起求解 pixi add "numpy>=1.22,<1.24" # 带版本约束

如果未指定具体版本，pixi 会自动选择与工作区兼容的最新版本，或使用*作为通配：

• pixi add python=3.9：选择满足3.9.*的最新 minor 版本，即 3.9.0、3.9.1、3.9.2……中的最新一个；
• pixi add python：无版本约束时直接选最新版。

核心选项：定位依赖的“落点”

pixi add的依赖默认写入默认 feature 的[dependencies]表，但通过以下选项可以精确控制依赖写入的位置与类型。

--pypi：添加 PyPI 依赖

--pypi将依赖声明为 PyPI 依赖（写入pypi-dependencies），并且不能与 conda 依赖混用，同时与--host、--build互斥（见 crates/pixi_cli/src/cli_config.rs 中conflicts_with_all = ["host", "build"]的定义）：

pixi add --pypi boto3 pixi add --pypi "boto3==version" pixi add --pypi requests[security] # 带 extra pixi add --pypi Django==5.1rc1 # 预发布版本

--platform (-p) <PLATFORM>：按平台添加

--platform指定依赖只针对某个平台生效，必须是工作区中已定义的平台名称，可以重复指定多次：

pixi add python --platform linux-64 --platform osx-arm64 pixi add --platform osx-64 clang

上例将为linux-64与osx-arm64两个平台分别添加最新版 python；clang则只添加到osx-64平台。平台限定会写入[target.<platform>.dependencies]之类的平台目标表。--platform与--build/--host可以混用。

--feature (-f) <FEATURE>：按 feature 添加

默认值为default。指定 feature 后，依赖写入对应 feature 的依赖表：

pixi add numpy --feature featurex pixi add --pypi "boltons>=24.0.0" --feature lint

--environment (-e) <ENVIRONMENT>：按环境添加（可自动创建）

--environment把依赖写入环境内联定义的内容中，如果该环境不存在则会自动创建：

pixi add --environment dev numpy

从源码看（crates/pixi_cli/src/cli_config.rs），--environment与--feature、--host、--build互斥，且当传入--environment时，内部会把该环境合成一个同名 feature 再写入清单（见feature_name()与feature_from_flags的实现，crates/pixi_cli/src/cli_config.rs）。

--path <PATH>与--editable：本地路径依赖

--path用于添加本地路径依赖，路径从当前目录解析，并相对工作区清单存储，因此绝对输入路径不会变成机器相关的清单数据（这是可移植性的关键设计）：

pixi add mylib --path ../mylib pixi add mylib --path /absolute/path/to/mylib pixi add recipe-package --path ../recipe/recipe.yaml pixi add --pypi mylib --path ../mylib pixi add --pypi mylib --path ../mylib --editable

关键行为与限制（见 crates/pixi_cli/src/add.rs 与resolve_dependency_path实现，crates/pixi_cli/src/add.rs）：

• --path与--git互斥，且一次只能搭配一个包名（--path requires exactly one package name）；
• 路径指向目录时：conda 场景要求目录内含pixi.toml或pyproject.toml；PyPI 场景要求目录内含pyproject.toml；
• 路径指向文件时：conda 场景支持pixi.toml、pyproject.toml、recipe.yaml、recipe.yml、package.xml；PyPI 场景仅支持pyproject.toml；
• conda 路径依赖（源码包）需要启用pixi-buildpreview 功能。若未启用，pixi 会交互式询问是否开启，或在非交互终端提示运行pixi workspace preview add pixi-build（见ensure_pixi_build_preview_enabled，crates/pixi_cli/src/add.rs）；
• 路径最终通过pathdiff::diff_paths转换为相对工作区清单的路径后写入清单。

--editable表示以可编辑（editable）模式安装 PyPI 依赖，仅当同时使用--pypi时有效（requires = "pypi"，crates/pixi_cli/src/add.rs）。

--index <INDEX>：指定 PyPI 索引

--index为本次添加的 PyPI 依赖指定索引 URL，仅适用于 PyPI 依赖，且与--git、--path互斥。从实现看（map_pypi_requirements_with_index，crates/pixi_cli/src/add.rs），该索引只会应用到 source 为 Registry（普通索引源）的依赖上；对于 Git、Path 等非 Registry 来源的依赖，索引不会生效。

Git 依赖选项：从仓库直接添加源码包

pixi add支持直接以 Git 仓库作为依赖来源，结合以下选项（统一定义在GitRev与DependencyConfig中，见 crates/pixi_cli/src/cli_config.rs）：

示例：

pixi add --git https://github.com/wolfv/pixi-build-examples boost-check pixi add --git https://github.com/wolfv/pixi-build-examples --branch main --subdirectory boost-check boost-check pixi add --git https://github.com/wolfv/pixi-build-examples --tag v0.1.0 boost-check pixi add --git https://github.com/wolfv/pixi-build-examples --rev e50d4a1 boost-check

当 Git 依赖与--pypi组合时，pixi 会把参数构造成 PEP 508 的 VCS 直接引用语法（build_vcs_requirement，crates/pixi_cli/src/cli_config.rs），格式为name @ git+url@rev?rev_type=type#subdirectory=subdir，其中rev_type用于区分 branch/tag/rev 三种引用类型（普通 PEP 508 语法会丢失这一信息）：

pixi add --git https://github.com/mahmoud/boltons.git boltons --pypi pixi add --git https://github.com/mahmoud/boltons.git boltons --branch main --pypi pixi add --git https://github.com/mahmoud/boltons.git boltons --rev e50d4a1 --pypi pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi --subdirectory boltons

更新与安装行为：--no-install/--frozen/--locked

pixi add默认会更新清单、更新锁文件并安装环境，以下三个选项用于控制这一流程（见 crates/pixi_cli/src/cli_config.rs）：

pixi add --no-install numpy # 写入清单和锁文件，但不安装 pixi add --no-lockfile-update numpy # 已弃用，请改用 --frozen / --no-install

源码层面，LockFileUpdateConfig明确拒绝了已弃用的--no-lockfile-update标志，并提示改用--frozen与--no-install（crates/pixi_cli/src/cli_config.rs）。此外，--no-install与--frozen的组合有一个便捷简写--as-is（等价于两者同时生效），它会把锁文件使用策略置为Frozen并禁止安装。

配置类选项：网络、认证、链接与 TLS

pixi add继承了 pixi 全局配置选项，用于控制求解与安装的底层行为：

• --auth-file <AUTH_FILE>：认证令牌文件的路径；
• --concurrent-downloads <CONCURRENT_DOWNLOADS>：最大并发网络请求数，默认50；
• --concurrent-solves <CONCURRENT_SOLVES>：最大并发求解数，默认等于 CPU 核数；
• --pypi-keyring-provider <PYPI_KEYRING_PROVIDER>：是否使用系统 keyring 查找 PyPI 凭据，可选disabled、subprocess；
• --run-post-link-scripts：运行 post-link 脚本（不安全，慎用）；
• --no-symbolic-links：安装时禁止符号链接（环境变量PIXI_NO_SYMBOLIC_LINKS）；
• --no-hard-links：安装时禁止硬链接（环境变量PIXI_NO_HARD_LINKS）；
• --no-ref-links：安装时禁止 ref links（写时复制，环境变量PIXI_NO_REF_LINKS）；
• --tls-no-verify：不校验服务器 TLS 证书；
• --offline=<OFFLINE>：完全离线运行，仅使用缓存数据，缓存缺失即报错。可通过--offline=false覆盖配置文件中的offline设置。接受的值包括y、yes、t、true、on、1、n、no、f、false、off、0，环境变量PIXI_OFFLINE；
• --tls-root-certs <TLS_ROOT_CERTS>：选择 TLS 根证书来源，webpki（内置 Mozilla 根证书）或system（系统证书库），环境变量PIXI_TLS_ROOT_CERTS；
• --use-environment-activation-cache：使用环境激活缓存（实验性）；
• --no-config：不读取系统级与用户级配置文件，但项目级<project>/.pixi/config.toml仍会加载（环境变量PIXI_NO_CONFIG，默认false）；
• --config-file <PATH>：从指定文件加载配置，替代系统级与用户级路径的搜索；项目级<project>/.pixi/config.toml仍会叠加在其上（环境变量PIXI_CONFIG_FILE）。

其中--offline相关行为在集成测试中有覆盖，例如pixi add --offline会基于缓存版本记录约束、而求解失败时不会写入新版本（见 tests/integration_python/test_offline_commands.py）。

全局选项：定位目标工作区

pixi add还支持三个全局工作区定位选项（定义于ScriptWorkspaceConfig与WorkspaceConfig，见 crates/pixi_cli/src/cli_config.rs）：

pixi add --manifest-path ~/myworkspace/pixi.toml numpy

注意：--script场景下依赖写入脚本内嵌清单的隐式默认运行环境中，因此不支持--feature、--environment、--host、--build（见validate_script_options，crates/pixi_cli/src/add.rs）。另外，若脚本尚无相邻的锁文件，pixi add会以 DryRun（仅求解、不落盘）方式处理（add_lock_file_usage，crates/pixi_cli/src/add.rs）。

版本选择与 Pinning 策略

pixi add自动为依赖选择版本并写入清单，采用基于 semver 的 pinning 策略，也可通过配置覆盖：

• 默认策略semver：把依赖固定到最新大版本（对v0版本则固定到 minor 版本）；
• 可选策略：semver、minor、major、latest-up、exact-version、no-pin。

通过 pixi 配置修改全局 pinning 策略：

pixi config set pinning-strategy no-pin --global

配置项说明详见 docs/reference/pixi_configuration.md。

例外规则：有一批不遵循 semver 版本规范的包默认改用minor策略，它们是：Python、Rust、Julia、GCC、GXX、GFortran、NodeJS、Deno、R、R-Base、Perl。例如pixi add python会固定到3.11.x之类的 minor 版本线，而不是3.x大版本线，以避免这类工具的大版本升级破坏环境。

实战示例大全

以下是官方示例扩展（docs/reference/cli/pixi/add_extender）中的完整用例，覆盖 conda、PyPI、Git 与本地路径四种依赖来源：

# conda 依赖 pixi add numpy # (1) 添加求解环境可用的最新 numpy pixi add numpy pandas "pytorch>=1.8" # (2) 多个包一起求解 pixi add "numpy>=1.22,<1.24" # (3) 带版本约束 pixi add --manifest-path ~/myworkspace/pixi.toml numpy # (4) 操作指定清单 pixi add --host "python>=3.9.0" # (5) 作为 host 依赖（当前与 run 行为一致） pixi add --build cmake # (6) 作为 build 依赖（当前与 run 行为一致） pixi add --platform osx-64 clang # (7) 仅对 osx-64 平台添加 pixi add --no-install numpy # (8) 只改清单和锁文件，不安装 pixi add --no-lockfile-update numpy # (9) 只改清单，不更新锁文件（已弃用） pixi add --feature featurex numpy # (10) 添加到 featurex feature pixi add --environment dev numpy # (28) 添加到 dev 环境的内联依赖（不存在则创建） pixi add /absolute/path/to/package-1.0-hb0f4dca_0.conda # (11) 直接安装本地预编译 .conda/.tar.bz2 包 # Git 源码依赖（conda 场景） pixi add --git https://github.com/wolfv/pixi-build-examples boost-check # (12) pixi add --git https://github.com/wolfv/pixi-build-examples --branch main --subdirectory boost-check boost-check # (13) pixi add --git https://github.com/wolfv/pixi-build-examples --tag v0.1.0 boost-check # (14) pixi add --git https://github.com/wolfv/pixi-build-examples --rev e50d4a1 boost-check # (15) # PyPI 依赖 pixi add --pypi requests[security] # (16) 带 extra pixi add --pypi Django==5.1rc1 # (17) 预发布版本 pixi add --pypi "boltons>=24.0.0" --feature lint # (18) 写入 lint feature pixi add --pypi "boltons @ https://files.pythonhosted.org/.../boltons-24.0.0-py3-none-any.whl" # (19) 直接引用 wheel URL pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib" # (20) Git URL 作为 PyPI 依赖 pixi add --pypi "project @ file:///absolute/path/to/project" # (21) file URL pixi add --pypi "project@file:///absolute/path/to/project" --editable # (22) 可编辑安装 # Git + PyPI 组合 pixi add --git https://github.com/mahmoud/boltons.git boltons --pypi # (23) pixi add --git https://github.com/mahmoud/boltons.git boltons --branch main --pypi # (24) pixi add --git https://github.com/mahmoud/boltons.git boltons --rev e50d4a1 --pypi # (25) pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi # (26) pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi --subdirectory boltons # (27) # 本地路径依赖 pixi add my-package --path ../my-package # (29) 本地 pixi-build 包目录（需 pixi-build preview） pixi add my-package --path /absolute/path/to/my-package # (30) 绝对路径，存储时转为相对清单路径 pixi add recipe-package --path ../recipe/recipe.yaml # (31) 直接指向 recipe.yaml（recipe.yml/package.xml 亦可） pixi add --pypi python-package --path ../python-package # (32) Python 项目目录（须含 pyproject.toml） pixi add --pypi python-package --path ../python-package --editable # (33) 可编辑安装

补充说明：

• 用例 (5)(6)：--host与--build目前与默认的 run 依赖行为没有差异，但依赖会分别写入[host-dependencies]/[build-dependencies]表；
• 用例 (11)：本地.conda/.tar.bz2包名从归档文件名中解析，无需指定版本；
• 用例 (29)-(31)：conda 场景的本地路径依赖属于源码包，需要先启用pixi-buildpreview（交互式确认或pixi workspace preview add pixi-build）；
• 用例 (32)-(33)：PyPI 路径依赖要求目标目录包含pyproject.toml。

指定构建字符串或硬件相关包

需要精确指定 build string 时，支持两种等价语法（详见 docs/concepts/package_specifications.md）：

# 等号语法（紧凑） pixi add "pytorch=*=*cuda*" pixi add "numpy=*=py311*" # 括号语法（显式） pixi add "pytorch [build='*cuda*']" pixi add "numpy [build='py311*']"

与 pyproject.toml 的原生集成

当工作区清单是pyproject.toml时，添加 PyPI 依赖会写入原生的 pyproject 结构，而非 pixi 私有表：

• pixi add --pypi boto3→ 写入project.dependencies数组；
• pixi add --pypi boto3 --feature aws→ 写入原生dependency-groups.aws数组；
• pixi add --pypi --editable 'boto3 @ file://absolute/path/to/boto3'→ 本地可编辑依赖写入pypi-dependencies数组。

需要特别注意的是：一旦指定了--platform或--editable，依赖会改写到tool.pixi.pypi-dependencies表，因为原生数组不支持平台限定或可编辑依赖。无论写入哪个位置，pixi 都会像读取pypi-dependencies表（默认 feature 或指定 feature）一样消费这些依赖。

底层执行链路与提示信息

pixi add的执行入口在 crates/pixi_cli/src/add.rs 的execute函数（L408-L627），核心流程为：

1. 校验--script相关限制（不支持--feature/--environment/--host/--build）；
2. 通过WorkspaceLocator::for_cli()定位工作区（支持--manifest-path/--workspace/--script三种定位方式）；
3. 若指定--path，调用resolve_dependency_path校验并规范化路径；conda 源码路径依赖还会检查pixi-buildpreview 是否启用；
4. 按DependencyType分发：conda 走add_conda_deps，PyPI 走add_pypi_deps（二者定义于 crates/pixi_api/src/context.rs，实际实现在crates/pixi_api/src/workspace/add/模块），依赖选项统一封装为DependencyOptions与GitOptions（crates/pixi_api/src/workspace/add/options.rs）；
5. 输出结果：成功添加的包打印✔ Added <pkg>，并注明隐式约束（如 semver pin）；已存在的依赖走“already a dependency”分支。

两个值得了解的运行时提示（均可在 crates/pixi_cli/src/add.rs 源码中看到）：

• 依赖已存在时：输出✔ <name> is already a dependency，并提示用pixi upgrade <name>获取最新兼容版本；若该包继承自[workspace.dependencies]，则提示更新工作区依赖表，或用显式 spec（如pixi add "<name>==1.0"）覆盖继承。
• feature 未被任何环境使用：添加的依赖不会被求解与 pin，pixi 会警告并提示先用pixi workspace environment add <environment> --feature <feature>把 feature 挂到环境上，再运行pixi upgrade --feature <feature> <names>完成解析与固定。

总结

pixi add是 pixi 工作区依赖管理的统一入口：一条命令同时覆盖 conda MatchSpec、PyPI PEP 508 依赖、Git 源码包与本地路径包四种来源；通过--platform/--feature/--environment精确控制依赖落点；通过--no-install/--frozen/--locked控制锁文件与安装行为；在与pyproject.toml协作时还能直接写入原生project.dependencies与dependency-groups。理解其 semver pinning 策略（以及对 Python、Rust、Julia 等非 semver 包自动降级到 minor 策略）与路径相对化存储逻辑，能帮助你在多平台、多 feature 的复杂工作区中稳定地管理依赖。

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