介绍

asdf是一个工具版本管理器。所有的工具版本定义都包含在一个文件（.tool-versions）中，你可以将配置文件放在项目的 Git 存储库中以便于和团队其他成员共享，从而确保每个人都使用完全相同的工具版本。传统工作方式需要多个命令行版本管理器，而且每个管理器都有其不同的 API、配置文件和实现方式（比如，$PATH 操作、垫片、环境变量等等）。asdf 提供单个交互方式和配置文件来简化开发工作流程，并可通过简单的插件接口扩展到所有工具和运行环境。

安装

asdf 安装过程包括：

安装依赖
下载 asdf 核心
安装 asdf
为每一个你想要管理的工具/运行环境安装插件
安装工具/运行环境的一个版本
通过 .tool-versions 配置文件设置全局和项目版本

1. 安装依赖

asdf primarily requires git & curl. Here is a non-exhaustive list of commands to run for your package manager (some might automatically install these tools in later steps).

OS	Package Manager	Command
linux	Aptitude	`apt install curl git`
linux	DNF	`dnf install curl git`
linux	Pacman	`pacman -S curl git`
linux	Zypper	`zypper install curl git`
macOS	Homebrew	`brew install coreutils curl git`
macOS	Spack	`spack install coreutils curl git`

::: tip Note

sudo may be required depending on your system configuration.

:::

2. 下载 asdf

Official Download

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.11.3

Community Supported Download Methods

We highly recommend using the official git method.

Method	Command
Homebrew	`brew install asdf`
Pacman	`git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` or use your preferred AUR helper

3. 安装 asdf

根据 Shell 脚本、操作系统和安装方法的组合不同，相应的配置也会不同。展开以下与你的系统最匹配的选项：

::: details Bash & Git

在 ~/.bashrc 文件中加入以下内容：

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

补全功能必须在 .bashrc 文件中加入以下内容来配置完成：

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

:::

::: details Bash & Git (macOS)

如果你正在使用 macOS Catalina 或者更新的版本, 默认的 shell 已经被修改为 ZSH。除非修改回 Bash, 否则请遵循 ZSH 的说明。

在 ~/.bash_profile 文件中加入以下内容：

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

补全功能必须在 .bash_profile 文件中使用以下内容手动配置完成：

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

:::

::: details 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

:::

::: details 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

:::

::: details Bash & Pacman

在 ~/.bashrc 文件中加入以下内容：

. /opt/asdf-vm/asdf.sh

为了让补全功能正常工作需要安装 bash-completion 。 :::

::: details 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

:::

::: details Fish & Homebrew

使用以下命令将 asdf.fish 加入到 ~/.config/fish/config.fish 文件中：

echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish

Fish shell 的补全功能可以交给 Homebrew 处理. 很友好！ :::

::: details Fish & Pacman

在 ~/.config/fish/config.fish 文件中加入以下内容：

source /opt/asdf-vm/asdf.fish

补全功能将会在安装过程中由 AUR 包管理器自动配置完成。 :::

::: details 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

补全功能将会自动配置。

:::

::: details Elvish & Homebrew

使用以下命令将 asdf.elv 加入到 ~/.config/elvish/rc.elv 文件中：

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

补全功能将会自动配置。

:::

::: details Elvish & Pacman

使用以下命令将 asdf.elv 加入到 ~/.config/elvish/rc.elv 文件中：

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

补全功能将会自动配置。

:::

::: details ZSH & Git

在 ~/.zshrc 文件中加入以下内容：

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

或者使用 ZSH 框架插件，比如 asdf for oh-my-zsh 将会使脚本生效并安装补全功能。

补全功能会被 ZSH 框架 asdf 插件或者通过在 .zshrc 文件中加入以下内容自动配置：

# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit

如果你正在使用自定义的 compinit 配置，请确保 compinit 在 asdf.sh 生效位置的下方
如果你正在使用自定义的 compinit 配置和 ZSH 框架，请确保 compinit 在框架生效位置的下方

警告

如果你正在使用 ZSH 框架，有关的 asdf 插件或许需要更新才能通过 fpath 正确地使用最新的 ZSH 补全功能。Oh-My-ZSH asdf 插件还在更新中，请查看 ohmyzsh/ohmyzsh#8837 了解更多。 :::

::: details ZSH & Homebrew

使用以下命令将 asdf.sh 加入到 ~/.zshrc 文件中：

echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc

或者使用 ZSH 框架插件，比如 asdf for oh-my-zsh 将会使脚本生效并安装补全功能。

补全功能可以被 ZSH 框架 asdf 或者按照 Homebrew 的指引完成配置。如果你正在使用 ZSH 框架，有关的 asdf 插件或许需要更新才能通过 fpath 正确地使用最新的 ZSH 补全功能。Oh-My-ZSH asdf 插件还在更新中，请查看 ohmyzsh/ohmyzsh#8837 了解更多。 :::

::: details ZSH & Pacman

在 ~/.zshrc 文件中加入以下内容：

. /opt/asdf-vm/asdf.sh

补全功能会被放在一个对 ZSH 很友好的位置，但是 ZSH 必须使用自动补全完成配置。 :::

::: details PowerShell Core & Git

在 ~/.config/powershell/profile.ps1 文件中加入以下内容：

. "$HOME/.asdf/asdf.ps1"

:::

::: details PowerShell Core & Homebrew

使用以下命令将 asdf.ps1 加入到 ~/.config/powershell/profile.ps1 文件中：

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

:::

::: details PowerShell Core & Pacman

在 ~/.config/powershell/profile.ps1 文件中加入以下内容：

. /opt/asdf-vm/asdf.ps1

:::

::: details Nushell & Git

使用以下命令将 asdf.nu 加入到 ~/.config/nushell/config.nu 文件中：

"\nlet-env ASDF_NU_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path

补全功能将会自动配置。 :::

::: details Nushell & Homebrew

使用以下命令将 asdf.nu 加入到 ~/.config/nushell/config.nu 文件中:

"\nlet-env ASDF_NU_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " +  (brew --prefix asdf | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path

补全功能将会自动配置。 :::

::: details Nushell & Pacman

使用以下命令将 asdf.nu 加入到 ~/.config/nushell/config.nu 文件中:

"\nlet-env ASDF_NU_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path

补全功能将会自动配置。 :::

::: details POSIX Shell & Git

在 ~/.profile 文件中加入以下内容：

export ASDF_DIR="$HOME/.asdf"
. "$HOME/.asdf/asdf.sh"

:::

::: details POSIX Shell & Homebrew

使用以下命令将 asdf.sh 加入到 ~/.profile 文件中：

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

:::

::: details POSIX Shell & Pacman

在 ~/.profile 文件中加入以下内容：

export ASDF_DIR="/opt/asdf-vm"
. /opt/asdf-vm/asdf.sh

:::

asdf 脚本需要在设置好的 $PATH 之后和已经生效的框架（比如 oh-my-zsh 等等）之后的位置生效。

通常打开一个新的终端标签页来重启你的 shell 让 PATH 更改即时生效。

核心安装完成！

这样就完成了 asdf 核心的安装 🎉

asdf 仅在你安装插件、工具和管理它们的版本时才开始真正发挥作用。请继续阅读下面的指南来了解这些是如何做到的。

使用

1. 安装插件

出于演示目的，我们将通过 asdf-nodejs 插件来安装和设置 Node.js。

插件依赖

每个插件都有依赖，所以我们需要确认应该列举了这些依赖的插件源码。对于 asdf-nodejs 来说，它们是：

操作系统	安装依赖
Linux (Debian)	`apt-get install dirmngr gpg curl gawk`
macOS	`brew install gpg gawk`

我们应该提前安装这些依赖，因为有些插件有 post-install 钩子。

安装插件

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

2. 安装指定版本

现在我们已经有了 Node.js 插件，所以我们可以开始安装某个版本了。

我们通过 asdf list all nodejs 可以看到所有可用的版本或者通过 asdf list all nodejs 14 查看版本子集。

我们将只安装最新可用的 latest 版本：

asdf install nodejs latest

::: tip 注意 asdf 强制使用准确的版本。latest 是一个通过 asdf 来解析到执行时刻的实际版本号的辅助工具。 :::

3. 设置默认版本

asdf 在从当前工作目录一直到 $HOME 目录的所有 .tool-versions 文件中进行工具的版本查找。查找在执行 asdf 管理的工具时实时发生。

::: warning 警告如果没有为工具找到指定的版本，则会出现错误。asdf current 将显示当前目录中的工具和版本解析结果，或者不存在，以便你可以观察哪些工具将无法执行。 :::

全局

全局默认配置在 $HOME/.tool-versions 文件中进行管理。使用以下命令可以设置一个全局版本：

asdf global nodejs latest

$HOME/.tool-versions 文件内容将会如下所示：

nodejs 16.5.0

某些操作系统已经有一些由系统而非 asdf 安装和管理的工具了，python 就是一个常见的例子。你需要告诉 asdf 将管理权还给系统。版本参考部分将会引导你。

本地

本地版本被定义在 $PWD/.tool-versions 文件中（当前工作目录）。通常，这将会是一个项目的 Git 存储库。当在你想要的目录执行：

asdf local nodejs latest

$PWD/.tool-versions 文件内容将会如下所示：

nodejs 16.5.0

社区插件

asdf社区插件,可以前往查看支持的语言。

命令参考

管理插件

命令	描述	示例
`asdf plugin add <name> [<git-url>]`	从插件仓库中添加插件，或通过指定名称和仓库 URL 添加 Git 仓库作为插件	`asdf plugin add python`
`asdf plugin list [--urls] [--refs]`	列出已安装的插件。可选择显示 git URL 和 git-ref	`asdf plugin list --urls`
`asdf plugin list all`	列出在 asdf-plugins 仓库中注册的所有插件及其 URL	`asdf plugin list all`
`asdf plugin remove <name>`	移除插件及其软件包版本	`asdf plugin remove python`
`asdf plugin update <name> [<git-ref>]`	更新插件到默认分支的最新提交或指定的 git-ref	`asdf plugin update python`
`asdf plugin update --all`	将所有插件更新到默认分支的最新提交	`asdf plugin update --all`

管理软件包

命令	描述	示例
`asdf current`	显示所有软件包的当前设置或正在使用的版本	`asdf current`
`asdf current <name>`	显示指定软件包的当前设置或正在使用的版本	`asdf current python`
`asdf global <name> <version>`	设置软件包的全局版本	`asdf global python 3.9.5`
`asdf global <name> latest[:<version>]`	将软件包的全局版本设置为最新提供的版本	`asdf global python latest`
`asdf help <name> [<version>]`	输出插件和工具的文档	`asdf help python`
`asdf install`	安装在 `.tool-versions` 文件中列出的所有软件包版本	`asdf install`
`asdf install <name>`	安装 `.tool-versions` 文件中指定的工具的特定版本	`asdf install python`
`asdf install <name> <version>`	安装软件包的特定版本	`asdf install python 3.9.5`
`asdf install <name> latest[:<version>]`	安装软件包的最新稳定版本，可选择指定版本	`asdf install python latest`
`asdf latest <name> [<version>]`	显示软件包的最新稳定版本	`asdf latest python`
`asdf latest --all`	显示所有软件包的最新稳定版本以及是否已安装	`asdf latest --all`
`asdf list <name> [version]`	列出已安装的软件包版本，并可选择筛选版本	`asdf list python`
`asdf list all <name> [<version>]`	列出软件包的所有版本，并可选择筛选返回的版本	`asdf list all python`
`asdf local <name> <version>`	设置软件包的本地版本	`asdf local python 3.9.5`
`asdf local <name> latest[:<version>]`	将软件包的本地版本设置为最新提供的版本	`asdf local python latest`
`asdf shell <name> <version>`	在当前 shell 中设置软件包版本为 `ASDF_${LANG}_VERSION`	`asdf shell python 3.9.5`
`asdf uninstall <name> <version>`	移除软件包的特定版本	`asdf uninstall python 3.9.5`
`asdf where <name> [<version>]`	显示已安装或当前版本的安装路径	`asdf where python`
`asdf which <command>`	显示可执行文件的路径	`asdf which python`

实用工具

命令	描述	示例
`asdf exec <command> [args...]`	以当前版本执行命令 shim	`asdf exec python --version`
`asdf env <command> [util]`	在命令 shim 执行的环境中运行 util（默认为 env）	`asdf env python --version`
`asdf info`	打印操作系统、Shell 和 ASDF 的调试信息	`asdf info`
`asdf reshim <name> <version>`	重新创建软件包版本的 shims	`asdf reshim python 3.9.5`
`asdf shim-versions <command>`	列出提供某个命令的插件和版本	`asdf shim-versions python`
`asdf update`	更新 asdf 到最新的稳定版本	`asdf update`
`asdf update --head`	更新 asdf 到最新的主分支版本	`asdf update --head`

🌈 asdf：终极一站式解决多版本困扰，开发如行云流水！💫

介绍

安装

1. 安装依赖

2. 下载 asdf

Official Download

Community Supported Download Methods

3. 安装 asdf

核心安装完成！

使用

1. 安装插件

插件依赖

安装插件

2. 安装指定版本

3. 设置默认版本

全局

本地

社区插件

命令参考