asdf 使用指南：用单一 CLI 与插件系统管理多语言运行时版本

asdf 使用指南用单一 CLI 与插件系统管理多语言运行时版本【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf导读asdf 是一款可扩展的extendable版本管理器通过统一的 CLI 命令、单一全局配置$HOME/.tool-versions与逐项目的.tool-versions文件即可管理 Ruby、Node.js、Elixir、Erlang 等众多语言的运行时版本。本文以仓库 README.md 为核心骨架结合 docs 下的官方文档与 internal 目录中的 Go 源码实现系统讲解 asdf 的安装、Shell 集成、插件安装、版本安装与设置、配置项及底层原理。读完后你将掌握从零搭建一套一个工具管所有语言的本地开发环境并理解 shim、版本解析与插件机制的工作方式。为什么使用 asdfasdf 的设计哲学是像gvm、nvm、rbenv、pyenv的集合体——只需安装语言对应的插件即可用同一套命令管理所有语言。README 中列出的核心优势包括单一 CLI 管理多语言不必为每种语言分别学习和记忆nvm、rbenv、pyenv各自的命令。一致的命令集install、list、set、uninstall等操作对所有语言完全一致。单一全局配置文件默认值集中保存在一个全局.tool-versions文件中。逐项目配置每个项目只需一个.tool-versions文件即可声明所需工具版本。平滑迁移支持读取.node-version、.nvmrc、.ruby-version等既有版本文件需插件支持见后文legacy_version_file。自动切换在目录树中移动时自动切换运行时版本版本查找是即时just-in-time的执行被管理的工具时才解析。简单的插件系统任何人都可以为自己的语言编写插件详见 docs/plugins/create.md。Shell 补全为 Bash、Zsh、Fish、Elvish 等常见 Shell 提供补全补全脚本位于 internal/completions如asdf.bash、asdf.zsh、asdf.fish、asdf.elvish。注意README 提到支持 Ruby, Node.js, Elixir, Erlang more这依赖插件生态asdf 核心本身并不内置任何语言的安装逻辑。一、安装 asdfasdf 提供多种安装方式官方推荐使用包管理器。当前仓库version.txt记录的版本为0.15.0以下命令中的版本号请以发布页实际版本为准。1. 包管理器安装推荐包管理器命令Homebrewbrew install asdfZypperzypper install asdfPacman (AUR)git clone https://aur.archlinux.org/asdf-vm.git cd asdf-vm makepkg -si或使用你偏好的 AUR helper2. 下载预编译二进制简便访问 asdf 的 Releases 页面下载与你操作系统/架构匹配的压缩包。将压缩包中的asdf二进制解压到$PATH中的某个目录。运行type -a asdf验证asdf所在的目录应出现在输出第一行否则说明第 2 步未正确完成。3. 通过go install安装需要先安装 Go然后执行go install github.com/asdf-vm/asdf/cmd/asdfv0.20.0仓库中的 cmd/cli/cli.go 即为 CLI 入口实现go install会直接编译出asdf可执行文件。4. 从源码构建git clone https://github.com/asdf-vm/asdf.git --branch v0.20.0 make然后将生成的asdf二进制复制到$PATH中的目录同样用type -a asdf验证。构建流程定义在仓库根目录的 Makefile编译依赖 Go 环境相关依赖声明在 go.mod 与 tools.go。二、配置 Shell 环境安装核心后还需要把 asdf 的 shims 目录加入$PATH并根据 Shell 配置补全。shims 目录加入 PATH 是必需的——被管理工具的入口都来自这里。添加 shims 目录到 PATH不同 Shell 的配置位置与写法不同各 Shell 的补全脚本位于 internal/completionsBash / ZSH / POSIX Shell在~/.bash_profileZSH 为~/.zshrcPOSIX 为~/.profile中加入export PATH${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATHFish~/.config/fish/config.fish# ASDF configuration code if test -z $ASDF_DATA_DIR set _asdf_shims $HOME/.asdf/shims else set _asdf_shims $ASDF_DATA_DIR/shims end # Do not use fish_add_path (added in Fish 3.2) because it # potentially changes the order of items in PATH if not contains $_asdf_shims $PATH set -gx --prepend PATH $_asdf_shims end set --erase _asdf_shimsElvish~/.config/elvish/rc.elvvar asdf_data_dir ~/.asdf if (and (has-env ASDF_DATA_DIR) (!s $E:ASDF_DATA_DIR )) { set asdf_data_dir $E:ASDF_DATA_DIR } if (not (has-value $paths $asdf_data_dir/shims)) { set paths [$path $paths] }PowerShell Core~/.config/powershell/profile.ps1# Determine the location of the shims directory if ($null -eq $ASDF_DATA_DIR -or $ASDF_DATA_DIR -eq ) { $_asdf_shims ${env:HOME}/.asdf/shims } else { $_asdf_shims $ASDF_DATA_DIR/shims } # Then add it to path $env:PATH ${_asdf_shims}:${env:PATH}Nushell~/.config/nushell/config.nuconst asdf_data_dir ~/.asdf | path expand # or wherever you like const asdf_shims [$asdf_data_dir shims] | path join $env.PATH $env.PATH | where {$in ! $asdf_shims} | prepend $asdf_shims自定义数据目录可选大多数用户无需修改 asdf 写入插件、安装版本与 shim 的默认位置$HOME/.asdf。如需修改在各 Shell 配置中先于上述 PATH 设置导出ASDF_DATA_DIRexport ASDF_DATA_DIR/your/custom/data/dirNushell 的写法为当$asdf_data_dir ! ~/.asdf时必需$env.ASDF_DATA_DIR $asdf_data_dir配置 Shell 补全可选Bash在~/.bashrc中加入. (asdf completion bash)Fishasdf completion fish ~/.config/fish/completions/asdf.fishElvishasdf completion elvish ~/.config/elvish/rc.elv再追加一行注册 arg-completerZSH$ mkdir -p ${ASDF_DATA_DIR:-$HOME/.asdf}/completions $ asdf completion zsh ${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf然后在~/.zshrc中fpath(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath) autoload -Uz compinit compinitNushell在~/.config/nushell/config.nu中加入const asdf_cmp [$asdf_data_dir completions nushell.nu] | path join mkdir ($asdf_cmp | path dirname) asdf completion nushell | save -f $asdf_cmp source $asdf_cmpPowerShell官方不提供补全。注意asdf的集成脚本应在$PATH设置完成、且 Shell 框架如 oh-my-zsh加载之后再被 source修改后需重启 Shell 或新开终端标签页使PATH生效。三、安装插件asdf 通过插件来了解如何安装与管理特定工具Node.js、Ruby、Elixir 等。以 Node.js 为例1. 检查插件依赖每个插件都有其依赖通常列在插件仓库 README 中。asdf-nodejs的依赖如下OS依赖安装命令Debianapt-get install dirmngr gpg curl gawkCentOS / Rocky Linux / AlmaLinuxyum install gnupg2 curl gawkmacOSbrew install gpg gawk应先安装依赖因为部分插件存在 post-install 钩子。2. 添加插件推荐使用带 Git URL 的完整写法不依赖 short-name 仓库asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git也可以只用短名从 asdf 维护的插件短名仓库解析 URLasdf plugin add nodejs插件的增删改查命令完整列表见 docs/manage/plugins.mdasdf plugin list # 列出已安装插件 asdf plugin list --urls # 附带显示 git url asdf plugin list all # 列出短名仓库中注册的全部插件 asdf plugin update --all # 更新所有插件到默认分支最新提交 asdf plugin update name # 更新单个插件 asdf plugin remove name # 移除插件会一并删除其安装的所有工具版本3. 插件短名仓库的同步机制asdf plugin add name与asdf plugin list all会触发对插件短名仓库的同步同步条件与节奏由.asdfrc中的disable_plugin_short_name_repository与plugin_repository_last_check_duration控制详见下文配置节。而asdf plugin add name git-url不会触发同步。四、安装工具版本有了插件即可安装工具版本asdf list all nodejs # 查看全部可用版本 asdf list all nodejs 14 # 查看以 14 开头的版本 asdf install nodejs latest # 安装最新稳定版asdf 强制使用精确版本号latest是贯穿全 CLI 的辅助关键字会在执行时解析为实际版本号。版本管理相关的完整命令见 docs/manage/versions.mdasdf install name version # 安装指定版本如 asdf install erlang 17.3 asdf install name latest # 安装最新稳定版 asdf install name latest:version # 安装以给定字符串开头的最新稳定版如 latest:17 asdf list name # 列出已安装版本 asdf list all name # 列出所有可用版本 asdf latest name # 显示最新稳定版 asdf uninstall name version # 卸载指定版本 asdf where name [version] # 显示已安装/当前版本的安装路径 asdf which command # 显示可执行文件路径如果插件支持从源码下载并编译还可以用ref:前缀指定分支、标签或提交asdf install name ref:foo # foo 为 branch/tag/commit卸载时需使用相同的名称与引用。五、设置版本版本查找机制asdf 会从当前工作目录开始逐级向上直到$HOME查找所有.tool-versions文件查找发生在执行被管理的工具的那一刻just-in-time。若某工具没有对应的版本声明执行该工具会报错——可用asdf current查看当前目录下各工具的版本解析结果。在$HOME/.tool-versions中设置的版本对所有家目录下的目录生效全局默认asdf set -u nodejs 16.5.0在项目目录中设置局部版本优先于全局asdf set nodejs 16.5.0执行后$PWD/.tool-versions内容为nodejs 16.5.0asdf set -p则写入当前目录最近的父级已存在的.tool-versions文件。s e t命令还可搭配latest/latest:version使用如asdf set elixir latest。在源码层面internal/toolversions/toolversions.go 的FindToolVersions负责从指定文件中解析某工具的版本列表Parse/ParseSlice/Format等函数实现了对版本字符串的解析与格式化WriteToolVersionsToFile则实现asdf set的写盘逻辑。使用既有版本文件迁移部分插件支持读取其他版本管理器的版本文件如rbenv的.ruby-version。asdf-nodejs支持.nvmrc与.node-version。启用方式是在 asdf 配置文件$HOME/.asdfrc中加入legacy_version_file yes通过环境变量临时覆盖版本设置形如ASDF_${TOOL}_VERSION的环境变量可以覆盖任何.tool-versions中的版本仅对当前 Shell 会话生效export ASDF_ELIXIR_VERSION1.18.1 # 或一次性执行 ASDF_ELIXIR_VERSION1.4.0 mix test回退到系统版本将工具的版本设为关键字systemasdf 就会把管理权交还给系统自带版本asdf set python system当某个工具如python已被系统包管理器安装时这一功能尤为实用。六、配置文件与配置项asdf 的配置分为两类可共享的.tool-versions项目级与机器相关的.asdfrc用户级加环境变量。完整说明见 docs/manage/configuration.md。.tool-versions格式只要某个目录中存在.tool-versions其中声明的版本就会作用于该目录及其所有子目录。示例ruby 2.5.3 nodejs 10.15.0支持注释#后为注释版本格式支持以下四种格式含义10.15.0实际版本号。支持二进制下载的插件会直接下载二进制ref:v1.0.2-a/ref:39cb398vb39从 GitHub 拉取对应 tag/commit/branch 并编译path:~/src/elixir使用自定义编译好的工具路径适合语言开发者system透传给系统上非 asdf 管理的同名工具同一工具可用空格分隔设置多个版本按顺序回退python 3.7.2 2.7.15 system在含.tool-versions的目录中直接运行asdf install不带参数可安装文件中声明的全部工具asdf install name只安装单个工具按文件中的版本。编辑文件可用任何编辑器或用asdf set自动更新。.asdfrc默认配置${HOME}/.asdfrc为默认位置可通过环境变量ASDF_CONFIG_FILE修改。仓库 defaults 文件给出了全部默认值legacy_version_file no use_release_candidates no always_keep_download no plugin_repository_last_check_duration 60 disable_plugin_short_name_repository no concurrency auto各配置项说明legacy_version_file是否允许插件回退读取其他版本管理器的版本文件如.ruby-version。no默认只用.tool-versionsyes则在可用时使用插件的 legacy 版本文件。always_keep_downloadasdf install安装成功后是否保留下载的源码/二进制。no默认删除yes保留。plugin_repository_last_check_duration插件仓库两次同步之间允许的间隔分钟。取值为1~999999999的整数默认60、0每次触发事件都同步或never从不同步。注意设为never并不能阻止首次同步如需完全禁止请用disable_plugin_short_name_repository。同步触发事件为asdf plugin add name与asdf plugin list all。disable_plugin_short_name_repository是否禁用插件短名仓库的同步。no默认在同步事件时克隆/更新该仓库yes则禁用。已同步的仓库不会自动删除可用rm --recursive --trash $ASDF_DATA_DIR/repository手动清理已安装的插件也不受影响可用asdf plugin remove name移除会一并删除该工具的所有已安装版本。concurrency源码编译时使用的默认核数。可取整数或auto默认依次尝试nproc、sysctl hw.ncpu、/proc/cpuinfo都不可用则取1。环境变量ASDF_CONCURRENCY优先级更高。环境变量环境变量应在 sourceasdf.sh/asdf.fish等脚本之前设置Elvish 中在use asdf之前。核心变量如下变量含义未设置时的默认值ASDF_CONFIG_FILE.asdfrc路径必须绝对路径$HOME/.asdfrcASDF_TOOL_VERSIONS_FILENAME工具版本文件名.tool-versionsASDF_DIRasdf 核心脚本位置必须绝对路径bin/asdf可执行文件的父目录ASDF_DATA_DIR插件、shim 与工具版本的安装位置$HOME/.asdf若存在否则为ASDF_DIRASDF_CONCURRENCY编译核数优先于concurrency配置使用.asdfrc的concurrency一个典型配置的解析结果假设Bash Shell、安装位置$HOME/.asdf、通过 Git 安装、未设置任何环境变量、无自定义.asdfrc则结果如下配置项值计算方式配置文件位置$HOME/.asdfrcASDF_CONFIG_FILE为空用$HOME/.asdfrc默认工具版本文件名.tool-versionsASDF_TOOL_VERSIONS_FILENAME为空asdf 目录$HOME/.asdfASDF_DIR为空用bin/asdf的父目录数据目录$HOME/.asdfASDF_DATA_DIR为空且$HOME存在concurrencyauto无ASDF_CONCURRENCY回退 defaultslegacy_version_file 等no无自定义.asdfrc使用 defaults插件钩子Plugin Hooks.asdfrc支持在插件生命周期事件前后执行自定义代码插件安装、reshim、更新、卸载前后以及插件命令执行前后。例如插件foo提供可执行文件bar可写pre_foo_bar echo Executing with args: $支持的钩子模式pre_plugin_name_commandpre_asdf_download_plugin_name{pre,post}_asdf_{install,reshim,uninstall}_plugin_name$1为完整版本号{pre,post}_asdf_plugin_{add,update,remove,reshim}$1为插件名{pre,post}_asdf_plugin_{add,update,remove}_plugin_name具体钩子的执行顺序细节见 docs/plugins/create.md。七、核心命令与底层原理asdf的全部命令文本位于 internal/help/help.txtasdf help即输出该文件内容docs/manage/commands.md 亦引用同一来源。核心命令可归为三类管理插件plugin add/plugin list/plugin list all/plugin remove/plugin update管理工具current/help/install/latest/list/list all/set/uninstall/where/which工具类exec/env/info/version/reshim/shimversionsshim 机制与exec/env/which/where安装工具时asdf 会在$ASDF_DATA_DIR/shims默认~/.asdf/shims中为包内每个可执行程序创建 shim。shim 是极简包装器它exec辅助程序asdf exec并把插件名与包内可执行文件路径传给它asdf exec再解析出应使用的版本来自.tool-versions或环境变量、包安装目录中的最终可执行路径可被插件的exec-path回调修改以及运行环境由插件exec-env脚本提供最后真正执行。从源码看internal/exec/exec.go 中的Exec函数直接调用syscall.Exec完成进程替换这正是shim 包装 exec 替换高效切换版本的底层实现internal/shims 与 internal/execute 则分别负责 shim 的生成与管理、命令的最终执行。由于这套机制基于exec调用需要被 Shell source 而非直接执行的脚本如包内的环境脚本应绕过 shim直接用asdf which/asdf where获取真实路径后访问# 返回当前版本主可执行文件路径 source $(asdf which ${PLUGIN})/../script.sh # 返回包安装目录路径 source $(asdf where ${PLUGIN})/bin/script.sh核心工具命令asdf exec command [args...] # 以当前版本执行 shim 命令 asdf env node # 打印 node 运行时的环境 asdf env node which npm # 在该环境内执行 which 验证 npm 解析位置 asdf info # 输出 OS、Shell 与 asdf 调试信息报 bug 时请附上 asdf shimversions node # 列出提供 node 命令的插件与版本asdf env的command必须是 shim 化的二进制名如node、python、ruby而不是任意 Shell 命令它会解析出负责该 shim 的插件与版本并在同一环境中运行[util]默认env因此你可以在插件的PATH与ASDF_*变量已就绪的环境里检查或调用其他工具。reshim 的典型场景asdf reshim name version会为某版本的工具重建 shim。默认情况下 shim 在工具安装时由插件创建但像 npm CLI 这类支持全局安装可执行文件的工具例如通过npm install -g yarn安装 Yarn其可执行文件并非经由插件生命周期产生因而没有 shim。此时asdf reshim nodejs version会强制为该版本的nodejs重新计算 shim使yarn等新可执行文件立即可用。八、更新与卸载更新请使用与安装相同的方式更新 asdf包管理器装的用包管理器源码装的重新make等。卸载以 Bash Git 安装为例# 1. 从 ~/.bashrc 移除 source asdf.sh 与补全的行 # 2. 删除数据目录 rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} # 3. 删除配置文件 rm -rf $HOME/.tool-versions $HOME/.asdfrc针对 Fish/Elvish/ZSH 与 Homebrew/Pacman 的各种组合步骤详见 docs/manage/core.md 的 Uninstall 小节。九、动手实践从零管理一个 Node.js 项目把以上内容串成一条完整链路# 1. 安装 asdf任选一种方式并把 shims 加入 PATH # 2. 安装插件 asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git # 3. 安装版本 asdf install nodejs latest # 4. 在项目目录设置版本 cd ~/my-node-project asdf set nodejs 16.5.0 # 5. 验证 asdf current node --version # 6. 检查/查看 asdf where nodejs asdf which node asdf list nodejs之后每次进入该项目目录node都会被自动解析到.tool-versions中声明的版本——不同项目可各自声明不同版本无需再切换全局环境。若要了解更多命令与插件 API可继续阅读 docs/manage/commands.md命令全集、docs/manage/versions.md版本管理、docs/manage/plugins.md插件管理与 docs/plugins/create.md编写自己的插件。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考