asdf

asdf — 一个帮你管理多种编程语言版本的命令行工具，彻底告别环境混乱。

作为一个经常在 Node.js、Python、Ruby、Java 等语言之间反复横跳的开发者，我受够了手动切换版本、清理残留、记不住安装路径的日常。直到遇见 asdf，我才发现原来版本管理可以这么清爽。

这工具到底是干嘛的？

简单说，asdf 是一个统一的版本管理器。你不需要分别装 nvm（Node.js）、pyenv（Python）、rbenv（Ruby）、jenv（Java）……它用一个命令搞定所有语言版本。核心痛点就是：你的项目可能需要 Node 18 + Python 3.10，另一个项目要 Node 14 + Python 3.8，手动切来切去不仅麻烦，还容易记错全局版本，导致项目跑不起来。

asdf 的核心思路是：每个项目目录放一个 .tool-versions 文件，里面写着这个项目需要哪些语言、什么版本。你 cd 进这个目录，asdf 自动给你切换到对应版本；离开目录，全局版本恢复。完全无感。

下载与安装

官网：asdf

我推荐你直接走 Git 安装，因为更新方便：

# macOS 用户（Homebrew）
brew install asdf

# Linux / macOS 通用（Git 克隆）
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

安装后需要把 asdf 加到 shell 配置文件里，否则终端不认识这个命令。

配置 Shell

根据你用的 shell 不同，在 ~/.bashrc、~/.zshrc 或 ~/.config/fish/config.fish 里加一行（以 zsh 为例）：

# 在 ~/.zshrc 末尾添加
source "$HOME/.asdf/asdf.sh"
# 以及自动补全（可选）
source "$HOME/.asdf/completions/asdf.bash"

然后 source ~/.zshrc 或新开终端窗口。

验证安装：

asdf --version
# 输出类似 v0.14.0 就对了

基础使用教程

1. 安装插件

asdf 本身不管理语言，它通过插件来支持各种工具。比如你要管理 Node.js，先装插件：

asdf plugin add nodejs

常用的插件列表（全部在 asdf-plugins 可查）：

• nodejs — Node.js
• python — Python
• ruby — Ruby
• java — Java（OpenJDK）
• golang — Go
• rust — Rust

2. 安装语言版本

装完插件就可以安装具体版本了：

# 列出 nodejs 所有可安装版本
asdf list-all nodejs

# 安装指定版本（比如 18.20.2）
asdf install nodejs 18.20.2

# 安装最新版
asdf install nodejs latest

3. 设置版本

三种模式：

全局版本（默认用这个）：

asdf global nodejs 18.20.2

当前 shell 临时版本（重启终端失效）：

asdf shell nodejs 20.11.0

项目本地版本（最常用！）：

cd your-project
asdf local nodejs 16.20.0
# 这会自动生成 .tool-versions 文件

.tool-versions 文件内容长这样：

nodejs 16.20.0
python 3.10.12
ruby 3.2.2

当你 cd 进这个目录，asdf 自动切换版本；离开后，版本回退到全局设置。

4. 查看当前版本

asdf current
# 输出当前目录下所有工具的版本
# 或者单独看某个工具
asdf current nodejs

进阶技巧

1. 多版本共存与别名

你可以同时装多个版本，然后按需切换。如果觉得版本号记不住，可以设别名：

asdf global nodejs 18.20.2
asdf alias nodejs stable 18.20.2
# 之后可以用 stable 代替版本号
asdf global nodejs stable

2. 自动切换版本（配合 direnv）

如果你觉得 cd 进目录自动切换还不够快，可以结合 direnv 实现更细粒度的控制。安装 direnv 后，在项目根目录创建 .envrc 文件：

# .envrc
use asdf

这样 cd 进目录时，direnv 会自动加载 asdf 的环境，连 node --version 都变成立刻生效。

3. 批量安装所有插件

如果你在新电脑上需要恢复所有开发环境，可以这样：

# 先备份旧电脑的插件列表
asdf plugin list --urls > ~/asdf-plugins.txt

# 新电脑上批量安装
xargs -I {} asdf plugin add {} < ~/asdf-plugins.txt

# 然后安装所有版本（假设你备份了 .tool-versions）
asdf install

asdf install 不加参数，会读取当前目录 .tool-versions 里列出的所有工具版本，自动下载安装。省去一个个手动安装的麻烦。

4. 清理未使用的版本

时间久了，系统里会堆积很多旧版本。用这个命令清理：

asdf list nodejs  # 列出所有已安装版本
asdf uninstall nodejs 14.17.0  # 删除指定版本

或者用 asdf prune 清理所有不在 .tool-versions 里用到的版本（谨慎使用）。

5. 支持非语言工具

asdf 的插件生态不止语言，还能管理一些 CLI 工具，比如：

• kubectl（Kubernetes 客户端）
• terraform（基础设施即代码）
• helm（K8s 包管理）
• hugo（静态博客生成器）

asdf plugin add kubectl
asdf install kubectl 1.28.0
asdf global kubectl 1.28.0

这样你连 brew 或 apt 安装这些工具都省了，版本统一由 asdf 管理。

避坑指南

1. 不要和 nvm、pyenv 混用：asdf 接管了 PATH，如果你还装了其他版本管理器，可能导致冲突。建议彻底卸载它们。
2. Windows 用户注意：asdf 原生不支持 Windows，但可以在 WSL2 里完美运行。如果你坚持用 Windows 原生环境，试试 asdf 的 Windows 分支（但不够稳定）。
3. 插件更新：有时候插件本身需要更新才能安装新版本，用 asdf plugin update nodejs 更新单个插件，或 asdf plugin update --all 更新所有插件。

总结

asdf 最打动我的地方是一致性：不管你在什么系统（macOS/Linux/WSL），不管管理多少种语言，都是一个命令、一个配置文件。它把“版本管理”这个经常被忽略但极其烦人的事，变成了一个可以随手搞定的例行公事。如果你也受够了在多个版本管理器之间切换，不妨给它一个周末试试，大概率会回不去的。