asdf 快速上手指南从零安装到用.tool-versions统一管理 Ruby、Node.js、Elixir 等多运行时版本【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf本文以 asdf 官方入门指南为骨架结合仓库源码internal/toolversions/toolversions.go、internal/config/config.go、internal/cli/cli.go对安装流程、版本解析与配置机制进行源码级佐证。读完本文你将能够独立完成 asdf 的依赖安装、核心程序下载、shell 集成、插件安装、版本安装与全局/局部版本设定并用.tool-versions文件在同一台机器上管理任意数量的运行时。asdf 是一个可扩展的多运行时版本管理器Extendable version manager通过核心程序 插件plugin的架构用一套统一的命令来管理 Ruby、Node.js、Elixir、Erlang 等几乎所有主流运行时与工具链。核心程序本身不内置任何语言它只负责编排插件、解析版本并生成 shim每一种具体工具的能力如何列出可用版本、如何下载编译、如何注入环境变量全部由对应插件提供。整体安装流程分为六步安装系统依赖git、curl等下载并安装 asdf 核心程序将 asdf 集成进你的 shell并配置补全为每一种需要管理的工具安装插件通过插件安装指定版本的该工具在全局$HOME或项目$PWD级别通过.tool-versions文件定义要使用的版本1. 安装系统依赖asdf 核心的运行主要依赖git拉取插件仓库与curl下载工具包以下是各包管理器对应的非穷尽安装命令列表部分系统的包管理器可能在后继步骤中自动携带这些工具OS包管理器命令LinuxAptitudeapt install curl gitLinuxDNFdnf install curl gitLinuxPacmanpacman -S curl gitLinuxZypperzypper install curl gitmacOSHomebrewbrew install coreutils curl gitmacOSSpackspack install coreutils curl git注意根据你的系统权限配置上述命令可能需要添加sudo。在源码层面asdf 的核心命令实现如plugin add、install都依赖git完成插件克隆、依赖curl与系统下载器完成工具源码或二进制包的获取因此这两个工具属于硬性前置条件。2. 下载并安装 asdf 核心官方推荐git clone官方推荐直接使用git克隆指定版本分支将 asdf 安装到~/.asdf目录文档示例版本为v0.20.0git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.20.0克隆完成后~/.asdf目录下会包含核心命令如asdf.sh、asdf.fish、asdf.zsh、asdf.elv、asdf.ps1、asdf.nu等各 shell 的集成脚本以及completions/补全目录如asdf.bash、asdf.zsh、asdf.fish。这些脚本的作用是把$ASDF_DATA_DIR/shims目录前置到$PATH并注册 asdf 自身的命令与补全逻辑。社区支持的下载方式方式命令Homebrewbrew install asdfPacmangit clone https://aur.archlinux.org/asdf-vm.git cd asdf-vm makepkg -si或使用你偏好的 AUR helper官方高度推荐使用git方式安装因为它能保证脚本路径、补全位置与文档示例完全一致。3. 将 asdf 集成到你的 shellshell 与安装方式的组合非常多下面按Shell × 安装方式展开配置方法。核心要点是asdf 的集成脚本必须在$PATH设定完成之后、ZSH 框架如 oh-my-zsh加载之后被 source修改完配置后请重启 shell或新开一个终端窗口/标签页使PATH生效。BashBash Git在~/.bashrc中添加. $HOME/.asdf/asdf.sh补全需手动配置在.bashrc中追加. $HOME/.asdf/completions/asdf.bashBash GitmacOS如果你使用macOS Catalina 或更新版本默认 shell 已改为ZSH。除非你切回 bash否则请按 ZSH 章节配置。若坚持使用 bash在~/.bash_profile中添加. $HOME/.asdf/asdf.sh补全同样追加到~/.bash_profile. $HOME/.asdf/completions/asdf.bashBash Homebrew在~/.bashrc中追加echo -e \n. $(brew --prefix asdf)/asdf.sh ~/.bashrc补全可参照 Homebrew 官方说明或直接追加echo -e \n. \$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\ ~/.bashrcBash HomebrewmacOS同样在~/.bash_profile中操作echo -e \n. $(brew --prefix asdf)/asdf.sh ~/.bash_profile echo -e \n. \$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\ ~/.bash_profileBash Pacman在~/.bashrc中添加. /opt/asdf-vm/asdf.sh补全需要额外安装bash-completion包。FishFish Git在~/.config/fish/config.fish中添加source ~/.asdf/asdf.fish补全手动配置mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completionsFish Homebrewecho -e \nsource (brew --prefix asdf)/asdf.fish ~/.config/fish/config.fishfish 的补全由 Homebrew 自动配置。Fish Pacman在~/.config/fish/config.fish中添加source /opt/asdf-vm/asdf.fishAUR 包安装时会自动完成补全配置。ElvishElvish Git把asdf.elv链接到 Elvish 的 lib 目录并在~/.config/elvish/rc.elv中注册命令与补全器mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv echo \nuse asdf _asdf; var asdf~ $_asdf:asdf~ ~/.config/elvish/rc.elv echo \nset edit:completion:arg-completer[asdf] $_asdf:arg-completer~ ~/.config/elvish/rc.elvElvish Homebrewmkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv echo \nuse asdf _asdf; var asdf~ $_asdf:asdf~ ~/.config/elvish/rc.elv echo \nset edit:completion:arg-completer[asdf] $_asdf:arg-completer~ ~/.config/elvish/rc.elvElvish Pacmanmkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv echo \nuse asdf _asdf; var asdf~ $_asdf:asdf~ ~/.config/elvish/rc.elv echo \nset edit:completion:arg-completer[asdf] $_asdf:arg-completer~ ~/.config/elvish/rc.elv以上配置完成后补全会自动更新。ZSHZSH Git在~/.zshrc中添加. $HOME/.asdf/asdf.sh或者使用 ZSH 框架插件如 asdf 的 oh-my-zsh 插件它会同时加载脚本与补全。补全可以通过框架插件配置也可以手动在~/.zshrc中添加# 将补全目录追加到 fpath fpath(${ASDF_DIR}/completions $fpath) # 使用 ZSH 的 compinit 初始化补全 autoload -Uz compinit compinit如果你使用自定义compinit配置请确保compinit位于asdf.sh调用之后如果使用带 ZSH 框架的自定义compinit配置请确保compinit位于框架调用之后若使用 ZSH 框架可能需要更新框架中的 asdf 插件才能正确使用基于fpath的新补全机制。ZSH Homebrewecho -e \n. $(brew --prefix asdf)/asdf.sh ${ZDOTDIR:-~}/.zshrc补全由框架或按 Homebrew 的 ZSH 补全说明配置。ZSH Pacman在~/.zshrc中添加. /opt/asdf-vm/asdf.sh补全会放置在 ZSH 熟悉的位置但 ZSH 需要被配置为能够使用这些补全。PowerShell CorePowerShell Core Git在~/.config/powershell/profile.ps1中添加. $HOME/.asdf/asdf.ps1PowerShell Core Homebrewecho -e \n. \$(brew --prefix asdf)/libexec/asdf.ps1\ ~/.config/powershell/profile.ps1PowerShell Core Pacman. /opt/asdf-vm/asdf.ps1NushellNushell Git在~/.config/nushell/config.nu中追加\n$env.ASDF_DIR ($env.HOME | path join .asdf)\n source ($env.HOME | path join .asdf/asdf.nu) | save --append $nu.config-pathNushell Homebrew\n$env.ASDF_DIR (brew --prefix asdf | str trim | into string | path join libexec)\n source (brew --prefix asdf | str trim | into string | path join libexec/asdf.nu) | save --append $nu.config-pathNushell Pacman\n$env.ASDF_DIR /opt/asdf-vm/\n source /opt/asdf-vm/asdf.nu | save --append $nu.config-path配置完成后补全会自动更新。POSIX ShellPOSIX Shell Git在~/.profile中添加export ASDF_DIR$HOME/.asdf . $HOME/.asdf/asdf.shPOSIX Shell Homebrewecho -e \nexport ASDF_DIR\$(brew --prefix asdf)/libexec/asdf.sh\ ~/.profile echo -e \n. \$(brew --prefix asdf)/libexec/asdf.sh\ ~/.profilePOSIX Shell Pacmanexport ASDF_DIR/opt/asdf-vm . /opt/asdf-vm/asdf.sh关于数据目录大多数用户不需要自定义 asdf 写入插件、安装与 shim 数据的目录。但如果$HOME/.asdf不是你想要的位置可以在 shell 的 RC 文件中导出ASDF_DATA_DIR变量来指定例如export ASDF_DATA_DIR/your/custom/data/dir。从源码看config.go 会在加载配置时优先读取ASDF_DATA_DIR环境变量并将其与ASDF_CONFIG_FILE、ASDF_TOOL_VERSIONS_FILENAME一起作为配置的输入来源。4. 安装插件核心程序安装完成后asdf 还不能管理任何工具。接下来以Node.js为例演示插件安装使用asdf-nodejs插件。插件依赖每个插件都有自己的依赖需要到插件仓库中查看。以asdf-nodejs为例操作系统依赖安装命令LinuxDebianapt-get install dirmngr gpg curl gawkmacOSbrew install gpg gawk必须先安装依赖因为部分插件在安装后会执行后置钩子post-install hooks。安装插件命令asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git该命令在源码中对应 cli.go 的pluginAddCommand它接收name [git-url]两个参数实际克隆工作交给plugins.Add完成。注意参数可选性如果省略 git-urlasdf 会从官方插件索引仓库config.go 中默认的asdf-vm/asdf-plugins仓库按短名称解析插件地址。5. 安装一个版本的 Node.js插件就绪后即可安装具体版本。首先查看有哪些可用版本# 列出 nodejs 插件支持的全部版本 asdf list all nodejs # 只列出以 14 开头的版本可用于查看某个大版本线 asdf list all nodejs 14安装最新可用版本使用latest占位符asdf install nodejs latest注意asdf强制使用精确版本号。latest只是 asdf 内置的辅助关键字会在执行时解析为当日的实际版本号并不会把latest写进任何配置文件。关于latest与版本字符串的源码细节从 toolversions.go 的ParseFromCliArg可以看到latest被解析为Type: latest并且支持latest:filter形式例如latest:17表示以 17 开头的最新版本。而.tool-versions文件与命令行参数最终统一通过Parse解析为五类版本类型toolversions.go版本类型写法示例含义version16.5.0普通精确版本号安装后写入安装目录refref:foo分支/tag/commit 引用插件需支持从源码编译下载pathpath:/foo/bar指向本地已编译源码目录直接使用其中的二进制systemsystem回退到系统自带的工具不被 asdf 管理latestlatest/latest:17安装时解析为当时最新的具体版本号仅命令行可用其中ref:foo适用于支持源码下载与编译的插件如 Erlang卸载时也必须使用相同的名称与引用path:则适合语言开发者在本地已有编译产物时直接复用。6. 设置版本版本查找机制asdf会在执行被管理的工具时即时just-in-time执行版本查找从当前工作目录开始逐级向上直到$HOME查找所有.tool-versions文件。具体而言asdf 优先查找当前目录的.tool-versions未找到则继续向父目录爬升直到找到一个文件为止如果整个路径上都不存在.tool-versions版本解析会失败并打印错误。警告如果某个工具没有在任何.tool-versions中被指定版本执行它时会直接报错。asdf current可以从当前目录展示每个工具解析到的版本或缺失情况帮助你判断哪些工具执行时会失败。该机制在源码层面对应 toolversions.gogetAllToolsAndVersionsInContent逐行解析.tool-versions按空格切分工具名 版本1 版本2 ...的结构#起始的注释会被忽略并为每个工具保留多个版本可用于需要多版本共存、以冒号分隔的场景。写入时WriteToolVersionsToFiletoolversions.go会创建或更新文件并保留文件中原有的其他工具条目与注释。全局版本$HOME/.tool-versions全局默认版本存放在$HOME/.tool-versions它对你主目录下的所有目录生效除非某个目录单独设置了覆盖版本。在旧版 CLI 中通过以下命令设置asdf global nodejs latest设置后$HOME/.tool-versions内容形如nodejs 16.5.0版本目录说明也可以使用新版统一命令asdf set -u nodejs 16.5.0-u/--home表示写入家目录效果等价。局部版本$PWD/.tool-versions项目级版本写入当前目录的$PWD/.tool-versions通常位于某个源码仓库根目录。进入目标目录后执行asdf local nodejs latest设置后$PWD/.tool-versions内容形如nodejs 16.5.0在命令实现层面cli.go 中set子命令提供了-u/--home与-p/--parent两个标志-u写入家目录-p写入最近存在的父目录.tool-versions不带标志时写入当前目录。其本质只是把工具名 版本写入对应文件相当于手动执行echo tool version .tool-versions。回退到系统版本部分操作系统自带了一些 asdf 也会管理的工具python是最常见的例子。此时可以显式把版本设为system让 asdf 把管理权交还给系统asdf local python system # 或 asdf global python system从源码看system是Parse中的特殊分支toolversions.go解析后不会触发任何安装目录查找而是直接回退。更完整的版本命令参考见 docs/manage/versions.md。复用其他版本管理器的版本文件asdf支持迁移其他版本管理器生成的版本文件例如rbenv的.ruby-version该能力按插件逐个提供。asdf-nodejs同时支持.nvmrc与.node-version文件。要启用该功能在 asdf 配置文件$HOME/.asdfrc中添加legacy_version_file yes从 config.go 的实现看asdfrc按 INI 格式解析legacy_version_file键的值取yes/no来开启/关闭旧版版本文件支持默认关闭。该文件的更多配置项如always_keep_download、concurrency、disable_plugin_short_name_repository等详见 docs/manage/configuration.md。7. 验证与常用管理命令核心安装与版本设定完成后你还需要掌握以下日常操作命令均在 internal/cli/cli.go 中有对应实现命令作用asdf current显示当前目录下所有工具解析到的版本及其来源文件asdf current name显示指定工具当前解析的版本asdf list name列出已安装的版本可追加前缀过滤如asdf list erlang 17asdf list all name列出插件支持的全部可用版本可追加前缀过滤asdf latest name显示最新稳定版本可追加前缀过滤如asdf latest erlang 17asdf uninstall name version卸载指定版本ref:安装的需使用相同引用asdf reshim name version重新生成 shim工具未出现在 PATH 中时可尝试asdf which command返回当前版本主可执行文件的路径asdf where name version返回工具安装目录路径asdf --help或asdf查看全部命令帮助关于 shim 的补充说明asdf 安装一个包时会为该包中的每一个可执行程序在$ASDF_DATA_DIR/shims默认~/.asdf/shims目录下创建 shim。该目录通过asdf.sh、asdf.fish等脚本被前置到$PATH这正是安装的程序能在环境中被调用的原因。shim 本身是极简的包装器它exec一个辅助程序asdf exec向其传递插件名与包内可执行文件的路径。asdf exec会确定要使用的版本来自.tool-versions文件或ASDF_${TOOL}_VERSION环境变量、最终可执行文件路径插件可通过exec-path回调修改以及执行环境由插件提供的exec-env脚本设置最后真正执行该程序。注意由于这套机制使用exec调用需要在 shell 中 source 而非直接执行的包内脚本必须绕过 shim 直接访问。which与where两个命令可帮助你拿到安装包的路径# 返回当前版本主可执行文件的路径 source $(asdf which ${PLUGIN})/../script.sh # 返回包安装目录的路径 source $(asdf where ${PLUGIN})/bin/script.sh如果你希望绕过 asdf 的 shim或在进入项目目录时自动设置环境变量社区有 asdf-direnv 插件可以协助详见其 README。8. 安装完成与后续扩展到这里asdf 的核心安装、Node.js 插件安装与版本设定已全部完成。你已经可以为自己的项目管理 Node.js 版本对项目中的每一种工具重复安装插件 → 安装版本 → 设置版本即可统一管理。asdf 的全部命令可归结为三大类深入学习请阅读对应参考文档核心 asdf见 docs/manage/core.md插件管理见 docs/manage/plugins.md工具版本管理见 docs/manage/versions.md此外配置文件$HOME/.asdfrc与环境变量ASDF_DATA_DIR、ASDF_CONFIG_FILE、ASDF_TOOL_VERSIONS_FILENAME、ASDF_${TOOL}_VERSION的完整说明可参考 docs/manage/configuration.md。至此你可以用 asdf 在任意目录自由切换不同运行时的精确版本让项目级版本隔离变得简单可控。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 asdf 快速上手指南：从零安装到用 `.tool-versions` 统一管理 Ruby、Node.js、Elixir 等多运行时版本
asdf 快速上手指南从零安装到用.tool-versions统一管理 Ruby、Node.js、Elixir 等多运行时版本【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf本文以 asdf 官方入门指南为骨架结合仓库源码internal/toolversions/toolversions.go、internal/config/config.go、internal/cli/cli.go对安装流程、版本解析与配置机制进行源码级佐证。读完本文你将能够独立完成 asdf 的依赖安装、核心程序下载、shell 集成、插件安装、版本安装与全局/局部版本设定并用.tool-versions文件在同一台机器上管理任意数量的运行时。asdf 是一个可扩展的多运行时版本管理器Extendable version manager通过核心程序 插件plugin的架构用一套统一的命令来管理 Ruby、Node.js、Elixir、Erlang 等几乎所有主流运行时与工具链。核心程序本身不内置任何语言它只负责编排插件、解析版本并生成 shim每一种具体工具的能力如何列出可用版本、如何下载编译、如何注入环境变量全部由对应插件提供。整体安装流程分为六步安装系统依赖git、curl等下载并安装 asdf 核心程序将 asdf 集成进你的 shell并配置补全为每一种需要管理的工具安装插件通过插件安装指定版本的该工具在全局$HOME或项目$PWD级别通过.tool-versions文件定义要使用的版本1. 安装系统依赖asdf 核心的运行主要依赖git拉取插件仓库与curl下载工具包以下是各包管理器对应的非穷尽安装命令列表部分系统的包管理器可能在后继步骤中自动携带这些工具OS包管理器命令LinuxAptitudeapt install curl gitLinuxDNFdnf install curl gitLinuxPacmanpacman -S curl gitLinuxZypperzypper install curl gitmacOSHomebrewbrew install coreutils curl gitmacOSSpackspack install coreutils curl git注意根据你的系统权限配置上述命令可能需要添加sudo。在源码层面asdf 的核心命令实现如plugin add、install都依赖git完成插件克隆、依赖curl与系统下载器完成工具源码或二进制包的获取因此这两个工具属于硬性前置条件。2. 下载并安装 asdf 核心官方推荐git clone官方推荐直接使用git克隆指定版本分支将 asdf 安装到~/.asdf目录文档示例版本为v0.20.0git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.20.0克隆完成后~/.asdf目录下会包含核心命令如asdf.sh、asdf.fish、asdf.zsh、asdf.elv、asdf.ps1、asdf.nu等各 shell 的集成脚本以及completions/补全目录如asdf.bash、asdf.zsh、asdf.fish。这些脚本的作用是把$ASDF_DATA_DIR/shims目录前置到$PATH并注册 asdf 自身的命令与补全逻辑。社区支持的下载方式方式命令Homebrewbrew install asdfPacmangit clone https://aur.archlinux.org/asdf-vm.git cd asdf-vm makepkg -si或使用你偏好的 AUR helper官方高度推荐使用git方式安装因为它能保证脚本路径、补全位置与文档示例完全一致。3. 将 asdf 集成到你的 shellshell 与安装方式的组合非常多下面按Shell × 安装方式展开配置方法。核心要点是asdf 的集成脚本必须在$PATH设定完成之后、ZSH 框架如 oh-my-zsh加载之后被 source修改完配置后请重启 shell或新开一个终端窗口/标签页使PATH生效。BashBash Git在~/.bashrc中添加. $HOME/.asdf/asdf.sh补全需手动配置在.bashrc中追加. $HOME/.asdf/completions/asdf.bashBash GitmacOS如果你使用macOS Catalina 或更新版本默认 shell 已改为ZSH。除非你切回 bash否则请按 ZSH 章节配置。若坚持使用 bash在~/.bash_profile中添加. $HOME/.asdf/asdf.sh补全同样追加到~/.bash_profile. $HOME/.asdf/completions/asdf.bashBash Homebrew在~/.bashrc中追加echo -e \n. $(brew --prefix asdf)/asdf.sh ~/.bashrc补全可参照 Homebrew 官方说明或直接追加echo -e \n. \$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\ ~/.bashrcBash HomebrewmacOS同样在~/.bash_profile中操作echo -e \n. $(brew --prefix asdf)/asdf.sh ~/.bash_profile echo -e \n. \$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\ ~/.bash_profileBash Pacman在~/.bashrc中添加. /opt/asdf-vm/asdf.sh补全需要额外安装bash-completion包。FishFish Git在~/.config/fish/config.fish中添加source ~/.asdf/asdf.fish补全手动配置mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completionsFish Homebrewecho -e \nsource (brew --prefix asdf)/asdf.fish ~/.config/fish/config.fishfish 的补全由 Homebrew 自动配置。Fish Pacman在~/.config/fish/config.fish中添加source /opt/asdf-vm/asdf.fishAUR 包安装时会自动完成补全配置。ElvishElvish Git把asdf.elv链接到 Elvish 的 lib 目录并在~/.config/elvish/rc.elv中注册命令与补全器mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv echo \nuse asdf _asdf; var asdf~ $_asdf:asdf~ ~/.config/elvish/rc.elv echo \nset edit:completion:arg-completer[asdf] $_asdf:arg-completer~ ~/.config/elvish/rc.elvElvish Homebrewmkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv echo \nuse asdf _asdf; var asdf~ $_asdf:asdf~ ~/.config/elvish/rc.elv echo \nset edit:completion:arg-completer[asdf] $_asdf:arg-completer~ ~/.config/elvish/rc.elvElvish Pacmanmkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv echo \nuse asdf _asdf; var asdf~ $_asdf:asdf~ ~/.config/elvish/rc.elv echo \nset edit:completion:arg-completer[asdf] $_asdf:arg-completer~ ~/.config/elvish/rc.elv以上配置完成后补全会自动更新。ZSHZSH Git在~/.zshrc中添加. $HOME/.asdf/asdf.sh或者使用 ZSH 框架插件如 asdf 的 oh-my-zsh 插件它会同时加载脚本与补全。补全可以通过框架插件配置也可以手动在~/.zshrc中添加# 将补全目录追加到 fpath fpath(${ASDF_DIR}/completions $fpath) # 使用 ZSH 的 compinit 初始化补全 autoload -Uz compinit compinit如果你使用自定义compinit配置请确保compinit位于asdf.sh调用之后如果使用带 ZSH 框架的自定义compinit配置请确保compinit位于框架调用之后若使用 ZSH 框架可能需要更新框架中的 asdf 插件才能正确使用基于fpath的新补全机制。ZSH Homebrewecho -e \n. $(brew --prefix asdf)/asdf.sh ${ZDOTDIR:-~}/.zshrc补全由框架或按 Homebrew 的 ZSH 补全说明配置。ZSH Pacman在~/.zshrc中添加. /opt/asdf-vm/asdf.sh补全会放置在 ZSH 熟悉的位置但 ZSH 需要被配置为能够使用这些补全。PowerShell CorePowerShell Core Git在~/.config/powershell/profile.ps1中添加. $HOME/.asdf/asdf.ps1PowerShell Core Homebrewecho -e \n. \$(brew --prefix asdf)/libexec/asdf.ps1\ ~/.config/powershell/profile.ps1PowerShell Core Pacman. /opt/asdf-vm/asdf.ps1NushellNushell Git在~/.config/nushell/config.nu中追加\n$env.ASDF_DIR ($env.HOME | path join .asdf)\n source ($env.HOME | path join .asdf/asdf.nu) | save --append $nu.config-pathNushell Homebrew\n$env.ASDF_DIR (brew --prefix asdf | str trim | into string | path join libexec)\n source (brew --prefix asdf | str trim | into string | path join libexec/asdf.nu) | save --append $nu.config-pathNushell Pacman\n$env.ASDF_DIR /opt/asdf-vm/\n source /opt/asdf-vm/asdf.nu | save --append $nu.config-path配置完成后补全会自动更新。POSIX ShellPOSIX Shell Git在~/.profile中添加export ASDF_DIR$HOME/.asdf . $HOME/.asdf/asdf.shPOSIX Shell Homebrewecho -e \nexport ASDF_DIR\$(brew --prefix asdf)/libexec/asdf.sh\ ~/.profile echo -e \n. \$(brew --prefix asdf)/libexec/asdf.sh\ ~/.profilePOSIX Shell Pacmanexport ASDF_DIR/opt/asdf-vm . /opt/asdf-vm/asdf.sh关于数据目录大多数用户不需要自定义 asdf 写入插件、安装与 shim 数据的目录。但如果$HOME/.asdf不是你想要的位置可以在 shell 的 RC 文件中导出ASDF_DATA_DIR变量来指定例如export ASDF_DATA_DIR/your/custom/data/dir。从源码看config.go 会在加载配置时优先读取ASDF_DATA_DIR环境变量并将其与ASDF_CONFIG_FILE、ASDF_TOOL_VERSIONS_FILENAME一起作为配置的输入来源。4. 安装插件核心程序安装完成后asdf 还不能管理任何工具。接下来以Node.js为例演示插件安装使用asdf-nodejs插件。插件依赖每个插件都有自己的依赖需要到插件仓库中查看。以asdf-nodejs为例操作系统依赖安装命令LinuxDebianapt-get install dirmngr gpg curl gawkmacOSbrew install gpg gawk必须先安装依赖因为部分插件在安装后会执行后置钩子post-install hooks。安装插件命令asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git该命令在源码中对应 cli.go 的pluginAddCommand它接收name [git-url]两个参数实际克隆工作交给plugins.Add完成。注意参数可选性如果省略 git-urlasdf 会从官方插件索引仓库config.go 中默认的asdf-vm/asdf-plugins仓库按短名称解析插件地址。5. 安装一个版本的 Node.js插件就绪后即可安装具体版本。首先查看有哪些可用版本# 列出 nodejs 插件支持的全部版本 asdf list all nodejs # 只列出以 14 开头的版本可用于查看某个大版本线 asdf list all nodejs 14安装最新可用版本使用latest占位符asdf install nodejs latest注意asdf强制使用精确版本号。latest只是 asdf 内置的辅助关键字会在执行时解析为当日的实际版本号并不会把latest写进任何配置文件。关于latest与版本字符串的源码细节从 toolversions.go 的ParseFromCliArg可以看到latest被解析为Type: latest并且支持latest:filter形式例如latest:17表示以 17 开头的最新版本。而.tool-versions文件与命令行参数最终统一通过Parse解析为五类版本类型toolversions.go版本类型写法示例含义version16.5.0普通精确版本号安装后写入安装目录refref:foo分支/tag/commit 引用插件需支持从源码编译下载pathpath:/foo/bar指向本地已编译源码目录直接使用其中的二进制systemsystem回退到系统自带的工具不被 asdf 管理latestlatest/latest:17安装时解析为当时最新的具体版本号仅命令行可用其中ref:foo适用于支持源码下载与编译的插件如 Erlang卸载时也必须使用相同的名称与引用path:则适合语言开发者在本地已有编译产物时直接复用。6. 设置版本版本查找机制asdf会在执行被管理的工具时即时just-in-time执行版本查找从当前工作目录开始逐级向上直到$HOME查找所有.tool-versions文件。具体而言asdf 优先查找当前目录的.tool-versions未找到则继续向父目录爬升直到找到一个文件为止如果整个路径上都不存在.tool-versions版本解析会失败并打印错误。警告如果某个工具没有在任何.tool-versions中被指定版本执行它时会直接报错。asdf current可以从当前目录展示每个工具解析到的版本或缺失情况帮助你判断哪些工具执行时会失败。该机制在源码层面对应 toolversions.gogetAllToolsAndVersionsInContent逐行解析.tool-versions按空格切分工具名 版本1 版本2 ...的结构#起始的注释会被忽略并为每个工具保留多个版本可用于需要多版本共存、以冒号分隔的场景。写入时WriteToolVersionsToFiletoolversions.go会创建或更新文件并保留文件中原有的其他工具条目与注释。全局版本$HOME/.tool-versions全局默认版本存放在$HOME/.tool-versions它对你主目录下的所有目录生效除非某个目录单独设置了覆盖版本。在旧版 CLI 中通过以下命令设置asdf global nodejs latest设置后$HOME/.tool-versions内容形如nodejs 16.5.0版本目录说明也可以使用新版统一命令asdf set -u nodejs 16.5.0-u/--home表示写入家目录效果等价。局部版本$PWD/.tool-versions项目级版本写入当前目录的$PWD/.tool-versions通常位于某个源码仓库根目录。进入目标目录后执行asdf local nodejs latest设置后$PWD/.tool-versions内容形如nodejs 16.5.0在命令实现层面cli.go 中set子命令提供了-u/--home与-p/--parent两个标志-u写入家目录-p写入最近存在的父目录.tool-versions不带标志时写入当前目录。其本质只是把工具名 版本写入对应文件相当于手动执行echo tool version .tool-versions。回退到系统版本部分操作系统自带了一些 asdf 也会管理的工具python是最常见的例子。此时可以显式把版本设为system让 asdf 把管理权交还给系统asdf local python system # 或 asdf global python system从源码看system是Parse中的特殊分支toolversions.go解析后不会触发任何安装目录查找而是直接回退。更完整的版本命令参考见 docs/manage/versions.md。复用其他版本管理器的版本文件asdf支持迁移其他版本管理器生成的版本文件例如rbenv的.ruby-version该能力按插件逐个提供。asdf-nodejs同时支持.nvmrc与.node-version文件。要启用该功能在 asdf 配置文件$HOME/.asdfrc中添加legacy_version_file yes从 config.go 的实现看asdfrc按 INI 格式解析legacy_version_file键的值取yes/no来开启/关闭旧版版本文件支持默认关闭。该文件的更多配置项如always_keep_download、concurrency、disable_plugin_short_name_repository等详见 docs/manage/configuration.md。7. 验证与常用管理命令核心安装与版本设定完成后你还需要掌握以下日常操作命令均在 internal/cli/cli.go 中有对应实现命令作用asdf current显示当前目录下所有工具解析到的版本及其来源文件asdf current name显示指定工具当前解析的版本asdf list name列出已安装的版本可追加前缀过滤如asdf list erlang 17asdf list all name列出插件支持的全部可用版本可追加前缀过滤asdf latest name显示最新稳定版本可追加前缀过滤如asdf latest erlang 17asdf uninstall name version卸载指定版本ref:安装的需使用相同引用asdf reshim name version重新生成 shim工具未出现在 PATH 中时可尝试asdf which command返回当前版本主可执行文件的路径asdf where name version返回工具安装目录路径asdf --help或asdf查看全部命令帮助关于 shim 的补充说明asdf 安装一个包时会为该包中的每一个可执行程序在$ASDF_DATA_DIR/shims默认~/.asdf/shims目录下创建 shim。该目录通过asdf.sh、asdf.fish等脚本被前置到$PATH这正是安装的程序能在环境中被调用的原因。shim 本身是极简的包装器它exec一个辅助程序asdf exec向其传递插件名与包内可执行文件的路径。asdf exec会确定要使用的版本来自.tool-versions文件或ASDF_${TOOL}_VERSION环境变量、最终可执行文件路径插件可通过exec-path回调修改以及执行环境由插件提供的exec-env脚本设置最后真正执行该程序。注意由于这套机制使用exec调用需要在 shell 中 source 而非直接执行的包内脚本必须绕过 shim 直接访问。which与where两个命令可帮助你拿到安装包的路径# 返回当前版本主可执行文件的路径 source $(asdf which ${PLUGIN})/../script.sh # 返回包安装目录的路径 source $(asdf where ${PLUGIN})/bin/script.sh如果你希望绕过 asdf 的 shim或在进入项目目录时自动设置环境变量社区有 asdf-direnv 插件可以协助详见其 README。8. 安装完成与后续扩展到这里asdf 的核心安装、Node.js 插件安装与版本设定已全部完成。你已经可以为自己的项目管理 Node.js 版本对项目中的每一种工具重复安装插件 → 安装版本 → 设置版本即可统一管理。asdf 的全部命令可归结为三大类深入学习请阅读对应参考文档核心 asdf见 docs/manage/core.md插件管理见 docs/manage/plugins.md工具版本管理见 docs/manage/versions.md此外配置文件$HOME/.asdfrc与环境变量ASDF_DATA_DIR、ASDF_CONFIG_FILE、ASDF_TOOL_VERSIONS_FILENAME、ASDF_${TOOL}_VERSION的完整说明可参考 docs/manage/configuration.md。至此你可以用 asdf 在任意目录自由切换不同运行时的精确版本让项目级版本隔离变得简单可控。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考