概述
你是不是也经历过这种场面：Python 用 pyenv，Node.js 用 nvm，Ruby 用 rbenv，Go 用 gvm……每个语言一个版本管理器，配置文件散落各处，换台机器就得重新配一遍。
asdf 是近年冒出来的版本管理器，一个工具管所有语言。它的插件生态很丰富，Python、Node.js、Go、Rust、Elixir、Erlang、Java、PHP、Ruby、Deno、Bun、Terraform、Kubectl 等都有官方插件。装好 asdf 之后，所有语言版本的切换、安装、删除都在同一个命令体系下。
这篇教程带你从零装好 asdf，配上国内镜像，跑通第一个项目。
准备工作
- 一台能正常联网的 Linux VPS 或本地 Linux 机器
- Ubuntu 22.04+ / Debian 12+ 推荐，CentOS 8+ 也行
- root 权限或 sudo 权限
- 磁盘剩余空间 200MB 以上
- Git 已安装（asdf 依赖 Git 来拉取插件）
步骤
第一步：安装依赖和 Asdf
先装 asdf 需要的系统依赖：
sudo apt update
sudo apt install -y curl git wget tar ca-certificates xz-utils
然后用官方脚本安装 asdf：
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1
装完之后把 asdf 加入 shell 配置。打开 ~/.bashrc：
echo '. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo '. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc
如果你用 zsh，把上面两行加到 ~/.zshrc。
让配置立即生效：
source ~/.bashrc
第二步：验证安装
asdf version
正常输出类似 0.14.1-4d9f3ac。如果提示 command not found，确认 .bashrc 里的两行配置已经生效。
第三步：安装第一个语言插件
以 Python 为例，先加插件：
asdf plugin add python
查看 available 的 Python 版本：
asdf list-all python
选一个版本安装，比如最新稳定版 3.12.7：
asdf install python 3.12.7
安装完成后设置全局默认版本：
asdf global python 3.12.7
验证：
python --version
# 输出 Python 3.12.7
第四步：安装其他语言插件
asdf 的插件都统一用 asdf plugin add 安装。常见语言：
# Node.js
asdf plugin add nodejs
asdf list-all nodejs | tail -5
asdf install nodejs 22.11.0
asdf global nodejs 22.11.0
# Go
asdf plugin add golang
asdf install golang 1.23.2
asdf global golang 1.23.2
# Rust
asdf plugin add rust
asdf install rust 1.82.0
asdf global rust 1.82.0
# Deno
asdf plugin add deno
asdf install deno 2.1.3
asdf global deno 2.1.3
# Bun
asdf plugin add bun
asdf install bun 1.2.15
asdf global bun 1.2.15
每个插件安装完都记得用 asdf global <语言> <版本> 设置全局默认。
第五步：项目级版本管理
asdf 最厉害的地方是项目级版本控制。在项目根目录放一个 .tool-versions 文件：
python 3.12.7
nodejs 22.11.0
golang 1.23.2
以后 cd 进这个目录，asdf 会自动切换成对应的版本。不用手动切换，不怕搞混。
第六步：国内镜像加速（重要）
很多语言版本的源码下载在海外，国内直接装会很慢。需要配镜像。
Python：在 ~/.asdf/pyenv/plugins/python-build/share/python-build 所在目录，或者提前下载好 Python 源码包放 ~/.asdf/downloads/python/ 下。更简单的方式是用镜像源安装：
# 用清华源下载 Python 源码包
mkdir -p ~/.asdf/downloads/python/
cd ~/.asdf/downloads/python/
wget https://mirrors.tuna.tsinghua.edu.cn/python/3.12.7/Python-3.12.7.tgz
# 然后 asdf 会从缓存目录读取，不走网络
asdf install python 3.12.7
Node.js：用 nvm 的淘宝镜像方式，在 asdf 的 Node.js 插件里配：
export NODE_BUILD_DOWNLOAD_TOKEN=$(echo YWRtaW46 | base64)
# 或者直接用镜像 URL
export NODEJS_VERSION_URL=https://registry.npmmirror.com/-/binary/node
asdf install nodejs 22.11.0
更简单的方式是在 .bashrc 里加：
export NVM_NODEJS_ORG_MIRROR=https://npm.taobao.org/mirrors/node
Go：
export GOPROXY=https://goproxy.cn,direct
export GONOSUMCHECK=*
export GONOSUMDB=*
export GOFLAGS=-insecure
Rust：
export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
把这些 export 加到 ~/.bashrc 里，每次登录自动生效。
验证
全部装好后跑这几个检查：
# 1. asdf 版本
asdf version
# 2. 所有已安装的语言
asdf list
# 3. 各语言版本
python --version
node --version
go version
rustc --version
deno --version
# 4. 查看当前项目版本文件
cat .tool-versions 2>/dev/null || echo "当前目录没有 .tool-versions 文件"
四项都通过，asdf 环境就配好了。
常用命令速查
# 添加插件
asdf plugin add <语言>
# 查看可用版本
asdf list-all <语言>
# 安装版本
asdf install <语言> <版本>
# 设为全局默认
asdf global <语言> <版本>
# 设为当前目录默认（写到 .tool-versions）
asdf local <语言> <版本>
# 查看已安装版本
asdf list <语言>
# 卸载版本
asdf uninstall <语言> <版本>
# 删除插件
asdf plugin remove <语言>
# 更新 asdf 本身
asdf update
# 更新所有插件到最新版本
asdf plugin update --all
# 查看所有已安装插件
asdf plugin list
常见问题
安装 Python 时报"download failed"？
源码下载地址在海外。手动下载源码包放到缓存目录：
mkdir -p ~/.asdf/downloads/python/
cd ~/.asdf/downloads/python/
wget https://www.python.org/ftp/python/3.12.7/Python-3.12.7.tgz
# 再跑安装，asdf 会优先用缓存
asdf install python 3.12.7
asdf: command not found？
shell 配置没生效。确认 .bashrc 里有这两行：
echo '. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo '. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc
source ~/.bashrc
新开一个终端窗口后asdf命令才能生效。
切换版本后 python 还是旧版？
可能装了多个 Python。用 which 确认：
which python
# 应该输出 ~/.asdf/shims/python
如果不是 shims 路径，说明 asdf 没正确接管。检查 PATH 顺序，asdf 的 shims 目录要在最前面：
export PATH="$HOME/.asdf/shims:$PATH"
插件找不到或者安装失败？
有些插件不在 asdf 官方仓库里，需要用完整 URL：
asdf plugin add <语言> https://github.com/<作者>/asdf-<语言>.git
去 asdf-plugins 搜索插件地址。
换机器后要重装吗？
不需要。把 .tool-versions 文件和 asdf 配置一起备份到新机器，然后：
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1
# 加入 .bashrc
# 然后批量安装所有语言
asdf plugin add python && asdf install python $(awk '$1=="python"{print $2}' .tool-versions)
asdf plugin add nodejs && asdf install nodejs $(awk '$1=="nodejs"{print $2}' .tool-versions)
一行搞定，不用逐个配。
asdf 和 nvm/pyenv 能共存吗？
能，但不推荐。两个管理器会互相抢 PATH，版本切换容易乱。建议统一用 asdf，把 nvm/pyenv 卸掉：
# 卸载 nvm
rm -rf ~/.nvm
# 卸载 pyenv
rm -rf ~/.pyenv
然后把对应的语言切换到 asdf 管理即可。