KnowledgeDocs

主题

ASDF 版本管理器使用手册 ​

概述 ​

什么是 ASDF？ ​

ASDF 是一个多语言版本管理器，一站式管理 Node.js、Python、Ruby、Go、Elixir 等多种语言版本。通过插件机制扩展支持，简化开发环境配置，统一切换管理，适合多语言项目开发者。

工作原理 ​

一旦 asdf 核心在 Shell 配置中设置好之后，你可以安装插件来管理特定的工具。当通过插件安装工具时，安装的可执行程序会为每个可执行程序创建 垫片。当你尝试运行其中一个可执行程序时，将运行垫片，从而允许 asdf 识别 .tool-versions 文件中设置的工具版本并执行该版本。

安装 ​

MacOS ​

  1. 安装核心组件
bash
brew install coreutils curl git
  1. 安装 asdf
bash
brew install asdf
  1. 环境变量配置
bash
echo -e '\n. "$(brew --prefix asdf)/libexec/asdf.sh"' >> ~/.zshrc
source ~/.zshrc
  1. 验证
bash
asdf --version

windows（WSL） ​

  1. 安装核心组件
bash
sudo apt update && sudo apt install -y curl git automake autoconf libreadline-dev \
  libncurses-dev libssl-dev libyaml-dev libxslt-dev libffi-dev libtool \
  unixodbc-dev unzip
  1. 安装 asdf
bash
git clone https://github.com/asdf-vm/asdf.git ~/.asdf
  1. 环境变量配置
bash
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.zshrc
source ~/.zshrc
  1. 验证
bash
asdf --version

使用 ​

1. 插件管理 ​

在使用任何语言之前，必须先安装对应的插件。常用插件地址：

  1. golang：https://github.com/asdf-community/asdf-golang.git
  2. node.js：https://github.com/asdf-vm/asdf-nodejs.git
  3. rust：https://github.com/asdf-community/asdf-rust.git
  4. 更多插件：https://github.com/orgs/asdf-community/repositories

添加插件 ​

bash
# 语法：asdf plugin add <name> [<git-url>]
asdf plugin add java
asdf plugin add nodejs [https://github.com/asdf-vm/asdf-nodejs.git](https://github.com/asdf-vm/asdf-nodejs.git)

查看已安装插件 ​

bash
# 列出名称
asdf plugin list

# 列出名称及仓库地址
asdf plugin list --urls

更新/移除插件 ​

bash
# 更新所有插件
asdf plugin update --all

# 移除插件（会同时删除该插件安装的所有版本）
asdf plugin remove java

2. 安装与卸载 ​

查询版本 ​

bash
# 列出该插件所有可安装的版本
asdf list all java

# 筛选特定版本（例如只看 openjdk）
asdf list all java openjdk

# 查看最新的稳定版
asdf latest java

安装版本 ​

bash
# 安装指定版本
asdf install java openjdk-17

# 自动安装项目所需的版本（依据 .tool-versions 文件）
asdf install

卸载版本 ​

bash
asdf uninstall java openjdk-21.0.2

4. 设置生效版本 ​

设置当前目录版本 (Local) ​

这会在当前文件夹创建 .tool-versions 文件。

bash
# 语法：asdf set <name> <version>
asdf set java openjdk-21.0.2

设置全局版本 (Global/User) ​

这会修改用户主目录下的 .tool-versions 文件（相当于以前的 global）。

bash
# 语法：asdf set -u <name> <version>
asdf set -u java openjdk-21.0.2

查看当前状态 ​

bash
# 查看当前正在使用的版本及其来源
asdf current

# 查看特定工具的版本
asdf current java

5. 常用工具 ​

查找路径 ​

bash
# 显示当前版本可执行文件的实际路径
asdf where java

# 显示 shim（垫片）脚本的路径
asdf which java

刷新垫片 (Reshim) ​

如果你手动安装了某些包但命令找不到，或者刚安装完环境却无法识别，请执行此操作。

bash
asdf reshim java

环境调试 ​

bash
# 打印 OS、Shell 和 ASDF 调试信息
asdf info