企业官网建设流程全解析

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 个步骤展开：

1. 安装依赖
2. 下载 asdf 核心
3. 安装 asdf（配置 Shell）
4. 为每个需要管理的工具/运行时安装插件
5. 安装工具/运行时的特定版本
6. 通过.tool-versions配置文件设置全局或项目版本

下面逐一展开。

1. 安装依赖

asdf 的运行主要依赖git和curl。下表是针对你所使用的包管理器执行的命令示例（部分工具会在后续步骤中被自动安装）：

提示：根据系统配置，命令前可能需要加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 为准。

社区支持的下载方式

除非有特殊原因，否则强烈建议使用git官方方式。

3. 安装 asdf（按 Shell 配置）

你的 Shell、操作系统与安装方式组合不同，配置方法也不同，请展开与你系统最匹配的方案。macOS 用户务必阅读本节末尾关于path_helper的警告。

Bash & Git

在~/.bashrc中追加：

. "$HOME/.asdf/asdf.sh"

如需命令补全，在.bashrc中追加：

. "$HOME/.asdf/completions/asdf.bash"

Bash & Git（macOS）

macOS Catalina 及更新版本的默认 Shell 已是ZSH。除非你改回 Bash，否则请参考 ZSH 的配置。

在~/.bash_profile中追加：

. "$HOME/.asdf/asdf.sh"

如需命令补全，在.bash_profile中追加：

. "$HOME/.asdf/completions/asdf.bash"

Bash & Homebrew

用以下命令把asdf.sh追加到~/.bashrc：

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bashrc

补全需要按 Homebrew 的说明配置，或执行：

echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bashrc

Bash & Homebrew（macOS）

macOS Catalina 及更新版本的默认 Shell 已是ZSH。除非你改回 Bash，否则请参考 ZSH 的配置。

把asdf.sh追加到~/.bash_profile：

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bash_profile

补全需要按 Homebrew 的说明配置，或执行：

echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile

Bash & 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/completions

Fish & Homebrew

把asdf.fish追加到~/.config/fish/config.fish：

echo -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.elv：

mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

补全自动配置。

Elvish & Homebrew

mkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

补全自动配置。

Elvish & Pacman

mkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv echo "\n"'set 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 ZSH's compinit autoload -Uz compinit && compinit

• 如果你自定义了compinit，请确保compinit位于 sourceasdf.sh之后；
• 如果你用 ZSH 框架自定义了compinit，请确保compinit位于 source 框架之后。

ZSH & Homebrew

把asdf.sh追加到~/.zshrc：

echo -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.ps1"

PowerShell Core & Homebrew

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell/profile.ps1

PowerShell Core & Pacman

. /opt/asdf-vm/asdf.ps1

Nushell & 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.sh"

POSIX Shell & Homebrew

echo -e "\nexport ASDF_DIR=\"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile

POSIX Shell & Pacman

export 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的依赖如下：

由于部分插件在安装后有 post-install 钩子，请先安装这些依赖。

安装插件

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

从源码实现看（internal/plugins/plugins.go），asdf 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 file）

asdf支持从其他版本管理器生成的既有版本文件迁移（例如rbenv的.ruby-version文件）。该支持按插件逐一提供。

asdf-nodejs同时支持.nvmrc与.node-version两种文件。要启用该功能，请在 asdf 配置文件中（$HOME/.asdfrc）追加：

legacy_version_file = yes

从源码看（internal/config/config.go），boolOverride会把.asdfrc（INI 格式）中的yes/no解析为布尔值；而插件侧通过list-legacy-filenames回调声明支持的旧文件名（见 internal/plugins/plugins.go），并通过parse-legacy-file回调解析旧文件内容（internal/plugins/plugins.go）。仓库默认配置见 defaults，legacy_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