osdk

简体中文

English

简体中文

English

外观

运行时与生态工具 ​

本页覆盖 Node.js、Python、Java/JRE、Go、Rust，以及 Maven、Gradle、Kotlin。 JavaScript 包管理器另见专页，任意 GitHub Release 工具见 下载源与供应链安全。

通用命令形态 ​

text
osdk install TOOL[@VERSION]... [-o|--opt KEY=VALUE ...]
osdk lock [TOOL[@VERSION] ...] [-o|--opt KEY=VALUE ...]
osdk upgrade [TOOL[@VERSION] ...] [-o|--opt KEY=VALUE ...]
osdk use|u TOOL[@VERSION] [-g|--global] [-o|--opt KEY=VALUE ...]
osdk exec (-t|--tool TOOL[@VERSION])... -- COMMAND [ARG ...]
osdk list|ls [TOOL]
osdk list-remote|lsr TOOL [FILTER]
osdk current [TOOL]
osdk where TOOL[@VERSION]
osdk uninstall|rm TOOL@VERSION

-o/--opt 可重复，必须写成 KEY=VALUE。它会应用到本次调用中的每个工具； 一次命令混合不同 backend 时，不要传只适用于其中一个 backend 的选项。

已有结构化工具若被 when 排除在当前平台之外，osdk use TOOL@VERSION 只更新它的 version，并保留 when、lazy 与 backend 选项；它不会绕过平台条件执行安装，也不会 为当前平台生成该工具的 lock 条目。此时不能同时修改 -o/--opt，backend 选项应在匹配的 平台上更新并验证。

内联选项块写成 tool[key=value,...]@selector，选项块在 @ 之前。在 PowerShell 下要给 整个操作数加引号：它把参数内未加引号的逗号当数组分隔符，会把一个表达式拆成两个参数。

bash
osdk install 'npm:esbuild[installer=pnpm,allow_builds=true]@0.21'

选项值本身含逗号时再套一层引号：allow_builds="a,b"。不加引号被拆开时，osdk 会识别出 这种情况并给出加好引号的完整命令，而不是报括号没写完。

后端速览 ​

backend工具名别名生态版本文件专用安装选项
nodenodejs.nvmrc、.node-version、package.jsonarch、corepack
pythonpy、cpython.python-versionvariant、tag
javajdk、openjdk.java-version、.sdkmanrcdistribution、package-type
gogolanggo.mod、.go-version无
rustrustuprust-toolchain.toml、rust-toolchainprofile、components、targets
mavenmvn.mvn-version无
gradle—.gradle-version无
kotlinkotlinc.kotlin-version无
zig—.zig-version无

活动版本的完整来源优先级，以及无参数生命周期命令对生态文件的当前限制，见 项目版本发现。

Node.js ​

bash
osdk install node@20
osdk install node@20.19.0 -o corepack=true
osdk lock node@20 -o arch=arm64
选项值作用
archx64、arm64、x86、arm选择目标 Node artifact；默认 host 架构
corepack`true1

corepack 未显式传入时取 [settings.node].corepack，默认 false。启用失败会删除 本次安装，不留下完成标记。Node 的 shim 只负责 node 和 corepack；npm/npx 由 独立 npm backend 或相应 Node 安装的路由 shim 协调。执行环境还会在用户未设置时 提供共享 npm_config_cache。

arch 可用于生成其他架构的 lock 区段，但 osdk 没有只下载模式；实际安装会拒绝 不能在当前 host 执行的 Node artifact。

Node 版本列表会合并所有可达 source 的 index，并保留排序靠前来源对重复版本的 LTS 标记；因此一个响应正常但同步落后的镜像不会隐藏后续 source 已发布的版本。下载阶段再 按同一顺序逐个校验 SHASUMS256.txt 对应的归档。

Node 也提供全局包迁移：

text
osdk node migrate-packages --from VERSION --to VERSION [--apply]
bash
# 只生成计划
osdk node migrate-packages --from 20.19.0 --to 22.17.0

# 执行迁移
osdk node migrate-packages --from 20.19.0 --to 22.17.0 --apply

源、目标都必须是已安装且含 npm 的受管 Node。osdk 通过源版本的 npm ls -g --depth=0 --json --long 枚举，跳过 npm 自身、目标已存在的包，以及声明 hasInstallScript=true 或 gypfile=true 的原生/安装脚本包。--apply 按精确版本安装； 失败时恢复目标原有的全局包集合。

Python ​

python@3.14 是默认 CPython 的简写。完整请求为 python@IMPLEMENTATION-VERSION+VARIANT：

bash
osdk install python@3.14
osdk install python@cpython-3.14+freethreaded
osdk install python@cpython-3.14+debug
osdk install python@cpython-3.14+freethreaded+debug
osdk install python@pypy-3.11
osdk install python@graalpy-3.12
osdk install python@pyodide-3.14
实现支持的变体identity 示例
cpythondefault、freethreaded、debug、freethreaded+debug3.14.7、cpython-3.14.7+debug
pypydefaultpypy-3.11.x
graalpydefaultgraalpy-3.12.x
pyodidedefaultpyodide-3.14.x
选项值作用
variant上表中的变体与请求中的 +VARIANT 等价；显式选项优先
tagpython-build-standalone 发布日期，如 20240224为经典 CPython 下载固定历史 PBS release

实现、精确 Python 版本、变体和 catalog artifact 都会进入 lock，不同 identity 可 并存。普通 CPython 使用内置 python-build-standalone 版本索引；多实现、变体和预发布 使用内置的已校验 catalog。自定义 catalog 必须同时指定内容摘要：

toml
[settings.python]
catalog_url = "/approved/python-catalog.json"
catalog_sha256 = "0123456789abcdef..."

catalog_url 可为 HTTP(S) 或本地路径。只有 SHA-256、schema 与每个 artifact checksum 全部有效才更新 last-good；刷新失败会尝试 last-good，再回退内置 catalog。 预发布策略见预发布版本。

经典 CPython 的同一 release tag 会合并所有可达 source 的 SHA256SUMS，排序靠前来源 的同名条目优先；因此首个镜像缺少某个平台的归档时，后续来源仍可补齐并进入下载回退。

查找解释器：

text
osdk python find [REQUEST]
bash
osdk python find
osdk python find pypy-3.11
osdk python find 3.14+freethreaded

managed 结果按可选请求筛选；随后仍扫描 PATH 与系统候选并去重，按 managed、PATH、system 标记输出。完全找不到时返回错误。

Java JDK 与 JRE ​

bash
osdk install java@21
osdk install java@zulu-17.0.1
osdk install java@21 -o distribution=zulu -o package-type=jdk
osdk install java@21 -o package-type=jre
选项值默认值
distributionFoojay distribution ID，如 temurin、zulutemurin
package-typejdk 或 jrejdk

发行版也可写进版本请求，例如 java@temurin-21。Foojay 查询按发行版、操作系统、 架构、archive 类型、JDK/JRE 和 Linux libc 过滤。JRE identity 为 jre-<resolved-version>，可与相同版本的 JDK 共存；执行 JDK/JRE 时导出 JAVA_HOME。

Temurin 版本带 build 号（如 21.0.12+8），PSU 还会有第四段（如 21.0.12.1+1）。 版本请求可以省略 build 号：java@21.0.12 会匹配同一核心版本的 21.0.12+8；只有当 同一核心版本不存在时，才回退匹配四段式 PSU。

内置 Temurin LTS catalog 包含 8、11、17、21、25，可在空 metadata 缓存下解析； 已锁定的 artifact 在 Foojay 不可用时也可安装。可设置兼容 Foojay /packages 的 端点或静态镜像：

toml
[settings.java]
catalog_url = "https://mirror.example/disco/v3.0/packages"

未设置这个单一显式 catalog 时，Java 会按 source 排序逐个查询 Foojay-compatible endpoint；某个 endpoint 可访问但没有请求的 distribution/JDK/JRE 组合时继续后备源。 对应的 checksum detail 也按相同顺序回退，最终 vendor 归档仍由通用校验下载管线处理。

JVM 工具 ​

bash
osdk install maven@3.9.16
osdk install "gradle@=9.3.1"
osdk install kotlin@2.4.10

Gradle 按上游版本索引解析，因此任何历史版本都可安装：osdk list-remote gradle 列出全部正式发布（2026-09-14 实测 179 个），每个版本的下载地址与 SHA-256 都取自索引， 无需在 osdk 内逐版本硬编码。索引里的 nightly、-rc-N 与 -milestone-N 会被判为非 稳定，所以 latest 只会落到正式版；需要预览版请按名字显式指定。若某条记录没有校验和， 安装会被拒绝而不是降级为不校验。

Maven 与 Kotlin 的上游没有同类的可机读索引，仍是固定集合：Maven 仅 3.9.16 （SHA-512）、Kotlin 仅 2.4.10（SHA-256），请求其他版本会失败。三者都拥有独立安装 目录和 shim；Kotlin 的 GitHub 下载还提供代理候选。Maven/Kotlin 使用排序后的有效 source URL；Gradle 会逐源读取 index，并把 index 中的绝对 distribution URL 重映射到 每个排序 source，因此 index 可读但该源缺少目标 zip 时仍会回退。

与 Gradle Wrapper 的关系

项目里已有 gradle/wrapper/gradle-wrapper.properties 时，wrapper 仍是权威来源 —— 它的 distributionSha256Sum 是比版本 pin 更强的保障。osdk 的 gradle pin 适用于没有 wrapper 的场景（例如新建项目或直接用 gradle 命令）。两者的摘要同源：实测索引中 9.3.1 的 checksum 与 wrapper 声明的 distributionSha256Sum 逐字符一致。

Go ​

bash
osdk install go@1.22
osdk use -g golang@1.23

Go 没有 backend 专用 -o。osdk 从 go.dev JSON index 选择当前 OS/架构的 archive 并验证索引中的 SHA-256；下载候选包括 go.dev、Aliyun 和 golang.google.cn。执行时导出 GOROOT，并提供 go、gofmt。

Rust ​

Rust backend 委托给安装在 osdk 隔离目录中的 rustup：

bash
osdk install rust@stable
osdk install rust@nightly -o profile=minimal \
  -o components=clippy,rustfmt \
  -o targets=wasm32-unknown-unknown,x86_64-pc-windows-gnu
选项值默认值
profilerustup 接受的 profiledefault
components逗号分隔的 rustup component空
targets逗号分隔的 rustup target空

latest、lts 和 system 都映射为 stable；stable、beta、nightly 与精确 工具链基本原样交给隔离 rustup。rustup bootstrap 自身固定使用 minimal 且不装默认 toolchain。运行时导出 RUSTUP_HOME=<data>/rustup 和 CARGO_HOME=<data>/cargo。 Lock 也会原样保存这些浮动 channel，因此以后重装 stable、beta 或 nightly 可能 得到更新 toolchain；需要不可变结果时请写明确版本或带日期的 toolchain。

source probe 只用通用 stable manifest 排序，不代表镜像已经同步请求的精确 toolchain、 component 或 target。所有会下载的 rustup 操作都会按排序逐个运行完整命令；某个源返回 404、下载失败或 rustup 拒绝其内容时会继续下一个源，直到命令真正成功。

暴露的命令与 cargo install ​

安装和 osdk reshim 时，osdk 会为活动工具链 bin 与隔离 CARGO_HOME/bin 里的全部 可执行文件生成 shim，而不只是 rustc、cargo、rustup、rustfmt、clippy-driver 五个核心命令：rustdoc、rust-analyzer、cargo-miri 等 rustup 代理，以及之后用受管 cargo 安装的 CLI 都会被暴露。这些 shim 运行时同样注入隔离的 RUSTUP_HOME、CARGO_HOME， 不会误连到系统 rustup。

用受管 cargo install 安装的第三方工具进入 <data>/cargo/bin（而不是系统 ~/.cargo）， 装完执行一次 osdk reshim 即可让新命令在 shell 中直接可用；cargo <子命令> 形式 （如 cargo tauri）无需 reshim，cargo 会直接在隔离 CARGO_HOME/bin 找到对应程序。

与系统 rustup 的管理边界 ​

osdk 只驱动数据目录下的隔离 rustup，不接管已经安装在系统 PATH 上的 rustup：

  • 未执行过 osdk install rust 时，隔离 rustup 不存在，osdk rust * 会明确报错并 提示先安装；它不会转而调用系统 rustup。
  • osdk source pin rust <源> 与一次性的 --source <源> 只改变 osdk 驱动受管 rustup 时注入的 RUSTUP_DIST_SERVER，不会修改外部 rustup 的环境变量或配置；未安装 受管 Rust 时命令会额外打印这条作用域提示。要让系统 rustup 走镜像，请自行配置 RUSTUP_DIST_SERVER、RUSTUP_UPDATE_ROOT 等环境变量。
  • 会下载的受管操作（osdk install rust、osdk rust component add、 osdk rust target add）共用同一套源选择，因此固定的源对补装 component、target 同样生效；pin 只把该源排到第一位，目标在该源不可用时仍会回退。
  • 受管 rustup 始终使用 osdk 选定的源：shell 中已经导出的 RUSTUP_DIST_SERVER、 RUSTUP_UPDATE_ROOT 不会影响受管操作，避免外部镜像覆盖 osdk 的选择。若要临时改用 其他源，请使用 --source <源>，而不是导出环境变量。

Component 与 target ​

text
osdk rust component add NAME [--toolchain TOOLCHAIN]
osdk rust component remove NAME [--toolchain TOOLCHAIN]
osdk rust component list [--toolchain TOOLCHAIN]
osdk rust target add NAME [--toolchain TOOLCHAIN]
osdk rust target remove NAME [--toolchain TOOLCHAIN]
osdk rust target list [--toolchain TOOLCHAIN]

--toolchain 默认 stable，命令直接作用于隔离 rustup。

bash
osdk rust component add rustfmt --toolchain stable
osdk rust target add wasm32-unknown-unknown --toolchain stable

状态、override 与本地工具链 ​

text
osdk rust check [--repair]
osdk rust override import [PATH]
osdk rust override export [PATH]
osdk rust toolchain link NAME PATH
  • check 先执行隔离 rustup check；--repair 再按真实 toolchain 目录补建缺失 marker， 并移除没有对应 toolchain 的 marker。
  • override import 从可选目录（默认当前目录）的隔离 rustup override 读取 toolchain， 写入最近项目 osdk.toml。
  • override export 把该目录的活动 osdk Rust pin 写成隔离 rustup 的目录 override。
  • toolchain link 要求 PATH 可规范化且包含 bin/；NAME 不能有空白、斜杠， 也不能是 . 或 ..。

linked toolchain 可被 shim 和 shell 使用，但它是本机路径，osdk lock 会拒绝把它 写成可复现 artifact。

Zig ​

bash
osdk install zig@latest
osdk use zig@0.16
osdk exec --tool zig -- zig version

版本来自 ziglang.org/download/index.json，该索引把每个发布的归档 URL 与 SHA-256 放在一起，因此每次安装都经过校验、也可被锁定。Zig 的 GitHub release 只提供源码和 bootstrap 归档，所以通用 github: backend 无法安装它。index 中虽然写的是绝对 tarball URL，osdk 仍会按相对发布路径把它重映射到每个排序 source；镜像 index 正常但 目标归档缺失、损坏或无法解包时会继续后备源。

master 是滚动 nightly 而非发布版本，按预发布处理：zig@latest 只会选中带 tag 的 版本；需要 nightly 时在允许预发布的策略下显式执行 osdk install zig@master。

用 Zig 做 C / C++ 交叉编译 ​

zig cc 和 zig c++ 是自带 libc 的 Clang 驱动：musl、多个 glibc 版本、mingw-w64 和 wasi-libc 都已内置。因此装一份就能交叉编译到多个目标，不需要为每个目标准备 sysroot —— 这正是 Android NDK 在 Android 之外做不到的事。

bash
# 同一份源码，无需额外下载，也不用指定 sysroot。
osdk exec --tool zig -- zig cc -target aarch64-linux-musl -o hello hello.c
osdk exec --tool zig -- zig cc -target x86_64-windows-gnu -o hello.exe hello.c

在 Windows x86-64 主机上用包含 <stdio.h> 的源码实测，以下目标均产出了对应架构的 二进制：

-target产物
x86_64-linux-gnuELF，x86-64
aarch64-linux-gnuELF，aarch64
x86_64-linux-muslELF，x86-64，静态
aarch64-linux-muslELF，aarch64，静态
riscv64-linux-muslELF，riscv
x86_64-windows-gnuPE
wasm32-wasiwasm

把 CC 指向 zig 后，它也可以充当其他构建系统的 C 编译器，这对带 C 依赖的 Rust crate 很有用：

bash
osdk exec --tool zig -- cargo build   # 环境中设置 CC="zig cc"

ZIG_GLOBAL_CACHE_DIR 会指向 osdk 缓存内的目录，避免构建产物堆积在用户主目录； 若该变量已有值则不覆盖。

基于 MIT 许可发布

Copyright © 2026 osdk contributors