asdf 入门指南Legacy从零安装到用.tool-versions管理 Node.js 等多语言运行时版本【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf本文基于仓库 docs/ja-jp/guide/getting-started-legacy.md以及英文版 docs/guide/getting-started-legacy.md编写。这是 asdf 早期版本的完整入门流程共分 6 步安装依赖 → 下载 asdf 核心 → 配置 Shell 完成安装 → 安装工具插件 → 安装工具特定版本 → 通过.tool-versions设置全局或项目级版本。读完本文你可以在 Linux 或 macOS 上从零搭建 asdf并以 Node.js 为例完成一个真实工具的多版本管理同时理解.tool-versions、legacy_version_file等机制的底层实现。asdf 是什么asdf 是一个可扩展的版本管理器Extendable version manager通过插件机制统一管理 Ruby、Node.js、Elixir、Erlang 等多种语言运行时。与nvm、rbenv等每种语言一个版本管理器的方案不同asdf 的核心只负责一套统一的版本解析与切换机制具体的工具Tool支持全部由插件Plugin提供。整个入门流程围绕 6 个步骤展开安装依赖下载 asdf 核心安装 asdf配置 Shell为每个需要管理的工具/运行时安装插件安装工具/运行时的特定版本通过.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。2. 下载 asdf官方下载方式强烈推荐使用git官方方式这也是仓库内版本发布所同步的方式git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.15.0其中v0.15.0为当前仓库 version.txt 中记录的版本号该版本号由 release-please 在发布时自动替换实际使用时请以最新 release 为准。社区支持的下载方式方法命令Homebrewbrew install asdfPacmangit clone https://aur.archlinux.org/asdf-vm.git cd asdf-vm makepkg -si或使用你偏好的 AUR 助手除非有特殊原因否则强烈建议使用git官方方式。3. 安装 asdf按 Shell 配置你的 Shell、操作系统与安装方式组合不同配置方法也不同请展开与你系统最匹配的方案。macOS 用户务必阅读本节末尾关于path_helper的警告。Bash Git在~/.bashrc中追加. $HOME/.asdf/asdf.sh如需命令补全在.bashrc中追加. $HOME/.asdf/completions/asdf.bashBash GitmacOSmacOS Catalina 及更新版本的默认 Shell 已是ZSH。除非你改回 Bash否则请参考 ZSH 的配置。在~/.bash_profile中追加. $HOME/.asdf/asdf.sh如需命令补全在.bash_profile中追加. $HOME/.asdf/completions/asdf.bashBash Homebrew用以下命令把asdf.sh追加到~/.bashrcecho -e \n. \$(brew --prefix asdf)/libexec/asdf.sh\ ~/.bashrc补全需要按 Homebrew 的说明配置或执行echo -e \n. \$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\ ~/.bashrcBash HomebrewmacOSmacOS Catalina 及更新版本的默认 Shell 已是ZSH。除非你改回 Bash否则请参考 ZSH 的配置。把asdf.sh追加到~/.bash_profileecho -e \n. \$(brew --prefix asdf)/libexec/asdf.sh\ ~/.bash_profile补全需要按 Homebrew 的说明配置或执行echo -e \n. \$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\ ~/.bash_profileBash Pacman在~/.bashrc中追加. /opt/asdf-vm/asdf.sh补全需要安装bash-completion包。Fish Git在~/.config/fish/config.fish中追加source ~/.asdf/asdf.fish如需补全执行mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completionsFish Homebrew把asdf.fish追加到~/.config/fish/config.fishecho -e \nsource (brew --prefix asdf)/libexec/asdf.fish ~/.config/fish/config.fish补全由 Homebrew 针对 Fish shell 自动处理。Fish Pacman在~/.config/fish/config.fish中追加source /opt/asdf-vm/asdf.fish补全在 AUR 包安装时自动配置。Elvish Git把asdf.elv追加到~/.config/elvish/rc.elvmkdir -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.elv补全自动配置。Elvish 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.elv补全自动配置。Elvish 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补全自动配置。ZSH Git在~/.zshrc中追加. $HOME/.asdf/asdf.sh或者使用 ZSH 框架插件如 oh-my-zsh 的 asdf 插件来 source 该脚本并设置补全。补全既可由 ZSH 框架的asdf插件配置也可在~/.zshrc中追加# append completions to fpath fpath(${ASDF_DIR}/completions $fpath) # initialise completions with ZSHs compinit autoload -Uz compinit compinit如果你自定义了compinit请确保compinit位于 sourceasdf.sh之后如果你用 ZSH 框架自定义了compinit请确保compinit位于 source 框架之后。ZSH Homebrew把asdf.sh追加到~/.zshrcecho -e \n. $(brew --prefix asdf)/libexec/asdf.sh ${ZDOTDIR:-~}/.zshrc或者使用 ZSH 框架插件。补全由框架配置或按 Homebrew 说明配置若使用框架可能需要通过fpath更新 asdf 插件以正确使用新的 ZSH 补全。ZSH Pacman在~/.zshrc中追加. /opt/asdf-vm/asdf.sh补全会放在 ZSH 友好的位置但你需要将 ZSH 配置为启用自动补全。PowerShell 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.ps1Nushell Git把asdf.nu追加到~/.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-path补全自动配置。Nushell 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-path补全自动配置。Nushell Pacman\n$env.ASDF_DIR /opt/asdf-vm/\n source /opt/asdf-vm/asdf.nu | save --append $nu.config-path补全自动配置。POSIX 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脚本必须写在设置$PATH之后、source 完所用框架如 oh-my-zsh之后。警告macOS 上启动 Bash 或 ZSH 时会自动调用path_helper工具它可能重排PATH以及MANPATH中的条目顺序导致依赖特定顺序的工具行为不一致。为规避这一点macOS 上的 asdf 默认会强制把自己的PATH条目追加到最前面获得最高优先级可通过ASDF_FORCE_PREPEND环境变量控制该行为。修改PATH后请重启 Shell通常新开一个终端标签页即可使配置生效。核心安装完成至此 asdf 核心安装完毕。但 asdf 只有在安装插件、安装工具并管理版本之后才有实际价值请继续后面的指南。4. 安装插件下面以asdf-nodejs插件为例演示如何安装并配置 Node.js。插件的依赖每个插件都有自己的依赖需要查看插件仓库中列出的依赖清单。asdf-nodejs的依赖如下OS依赖安装命令Debianapt-get install dirmngr gpg curl gawkCentOS / Rocky Linux / AlmaLinuxyum install gnupg2 curl gawkmacOSbrew install gpg gawk由于部分插件在安装后有 post-install 钩子请先安装这些依赖。安装插件asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git从源码实现看internal/plugins/plugins.goasdf plugin add会校验插件名validatePluginName只允许小写字母、数字、_和-检查插件是否已存在然后通过git.NewRepo(...).Clone(plugin.URL, ref)把插件仓库克隆到数据目录最后执行post-plugin-add回调以及pre/post_asdf_plugin_add钩子。如果不带 Git URL例如asdf plugin add erlang则会从插件短名称仓库short-name repository解析出插件地址更多插件管理命令参见 插件管理参考。5. 安装特定版本装好 Node.js 插件后即可安装该工具的特定版本。可用asdf list all nodejs查看全部可安装版本或用asdf list all nodejs 14查看某个主版本如 14.x的子集。安装最新版asdf install nodejs latest提示asdf强制要求精确版本号。latest是 asdf 全程提供的一个辅助关键字会在执行时解析为当时的真实版本号。latest与版本解析的底层机制从源码看internal/toolversions/toolversions.go 中的ParseFromCliArg会把latest与latest:filter解析为Type: latest的版本结构internal/versions/versions.go 中定义的正则latestFilterRegex会过滤掉-dev、-src、-alpha、-beta、-rc、snapshot、master、main等不稳定版本从而选出真正的最新稳定版。.tool-versions文件支持的所有版本形式version、ref:、path:、system、latest都可以在 internal/toolversions/toolversions.go 的Version结构体中看到详细说明见 版本管理参考。6. 设置版本asdf会从当前工作目录向上直到$HOME目录查找沿途所有.tool-versions文件来解析工具的版本。该查找在你执行 asdf 管理的工具时**即时just-in-time**发生。警告如果某个工具没有配置版本执行该工具会报错。运行asdf current可以查看当前目录下各工具的版本解析结果或缺失情况从而判断哪些工具会执行失败。全局版本全局默认值由$HOME/.tool-versions管理。设置全局版本asdf global nodejs latest此时$HOME/.tool-versions内容如下nodejs 16.5.0注意部分操作系统已由系统而非 asdf安装了某些工具python是最常见的例子。若要使用系统版本需要告诉 asdf 把版本管理交还给系统方法是在.tool-versions中把版本指定为system详见 版本管理参考。本地版本本地版本定义在$PWD/.tool-versions文件当前工作目录中通常位于项目的 Git 仓库内。在目标目录执行asdf local nodejs latest此时$PWD/.tool-versions内容如下nodejs 16.5.0.tool-versions的读写实现internal/toolversions/toolversions.go 中的WriteToolVersionsToFile负责把工具与版本写回文件不存在则创建已存在则更新对应行保留文件中的注释与其他工具的配置parseLine见 internal/toolversions/toolversions.go支持以#开头的行内注释与整行注释。.tool-versions还支持一行内以空格分隔多个版本例如python 3.7.2 2.7.15 system实现按顺序回退文件格式的完整说明见 配置参考。使用其他工具已有的版本文件legacy version fileasdf支持从其他版本管理器生成的既有版本文件迁移例如rbenv的.ruby-version文件。该支持按插件逐一提供。asdf-nodejs同时支持.nvmrc与.node-version两种文件。要启用该功能请在 asdf 配置文件中$HOME/.asdfrc追加legacy_version_file yes从源码看internal/config/config.goboolOverride会把.asdfrcINI 格式中的yes/no解析为布尔值而插件侧通过list-legacy-filenames回调声明支持的旧文件名见 internal/plugins/plugins.go并通过parse-legacy-file回调解析旧文件内容internal/plugins/plugins.go。仓库默认配置见 defaultslegacy_version_file默认值为no。更多配置项说明见 配置参考。入门完成至此 asdf 入门流程全部结束你已经可以在项目中管理nodejs的版本了。项目中的每种工具都按同样流程操作即可。asdf 还有很多值得掌握的常用命令运行asdf --help或直接运行asdf即可查看全部命令说明。命令主要分为三大类asdf 核心命令如asdf exec、asdf env、asdf info、asdf reshim、asdf shimversions等插件命令如asdf plugin add/list/update/remove工具版本命令如asdf install/list/list all/latest/current/uninstall/set。此外仓库还提供英文版入门指南 docs/guide/getting-started-legacy.md以及面向新版本流程的 docs/ja-jp/guide/getting-started.md可供对照阅读。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考