asdf 是什么？一个工具管理所有语言的运行时版本
asdf 用统一接口管理 Ruby、Node.js、Python 等几乎所有语言的运行时版本，替代 rbenv、nvm、pyenv 一堆工具。本文讲解 asdf 的安装、插件机制与 .tool-versions 的用法。
asdf 是一个通用运行时版本管理器：通过插件机制，用同一套命令安装、切换 Ruby、Node.js、Python、Go 甚至 Terraform 等工具的版本，项目级版本锁定统一写在 .tool-versions 文件里，从此不用再为每种语言维护单独的版本管理器。
为什么需要 asdf
项目一多，版本管理就失控：Rails 应用要 Ruby 3.2，前端微服务要 Node 18，数据管道要 Python 3.11。传统做法是给每种语言装一个管理器——rbenv、nvm、pyenv……每套工具的安装方式、配置文件、命令格式都不一样，新同事配环境常常要花一整天。
asdf 把这些收敛成一个工具、一套命令、一个配置文件。团队成员装上 asdf、所需插件和系统构建依赖后，进入项目目录执行 asdf install，才会安装 .tool-versions 声明的运行时。
安装 asdf
在 Linux 或 macOS 上，最简单的方式是通过 Homebrew：
brew install asdf
然后按 Shell 类型把初始化命令写进 ~/.zshrc 或 ~/.bashrc：
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
重开终端后 asdf --version 有输出即安装成功。asdf 0.16+ 为 Go 实现；其他平台应使用对应发行包或官方安装方式，不沿用旧版 source asdf.sh 的初始化方法。
插件机制：按需扩展语言
asdf 本身不认识任何语言，一切通过插件接入。常用插件：
asdf plugin add ruby
asdf plugin add nodejs
asdf plugin add python
asdf plugin list all 可以查看社区维护的几百个插件，涵盖 Erlang、Elixir、Java、kubectl、Terraform 等。插件本质是一组 Shell 脚本，负责下载、编译、安装对应工具。
安装与切换版本
装完插件即可安装任意版本：
asdf install ruby 3.3.0
asdf install nodejs 20.11.0
asdf install ruby latest # 安装最新稳定版
设置版本有三个层级：
asdf set -u ruby 3.3.0 # 全局默认，写入 ~/.tool-versions
asdf set ruby 3.2.2 # 当前目录，写入 ./.tool-versions
export ASDF_RUBY_VERSION=3.1.4 # 仅当前终端会话
asdf set 只选择版本，不负责安装；上例中的 3.2.2 与 3.1.4 也需先安装。进入项目目录后，shims 才能让 ruby -v 使用 .tool-versions 里已安装的版本。把这个文件提交到 Git 仓库，整个团队的运行时就对齐了。
兼容传统版本文件
很多老项目里已经存在 .ruby-version、.nvmrc 这类文件。在 ~/.asdfrc 中加一行配置，可启用对应插件实现的旧版本文件支持；具体文件与版本格式仍取决于插件，并非所有插件都支持：
legacy_version_file = yes
常见问题（FAQ）
Q：asdf 和 Docker 冲突吗？
不冲突，两者解决不同问题。asdf 管理开发机上的工具版本，Docker 封装运行环境。常见做法是本地开发用 asdf，生产部署用容器镜像。
Q：安装 Ruby 时报编译错误怎么办？
通常是缺少编译依赖。macOS 上先装 brew install openssl@3 readline libyaml gmp，Ubuntu 上装 build-essential libssl-dev libreadline-dev libyaml-dev，再重试 asdf install。
Q：如何升级 asdf 本身和插件？
Homebrew 安装的用 brew upgrade asdf；插件升级用 asdf plugin update --all，语言新版本发布后无需升级 asdf 本体即可安装。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
