asdf：一站式多运行时版本管理器 #

asdf 是什么？ #

asdf 是一款开源的命令行工具版本管理器（tool version manager），使用统一的 CLI 接口和配置文件来管理多个运行时和开发工具的版本。它通过插件系统支持 Node.js、Ruby、Python、Elixir、Erlang 等大量语言和工具，把原本需要 nvm、rbenv、pyenv 等多个管理器才能完成的工作，整合到一个 .tool-versions 文件中。团队成员只需共享这个文件，就能确保所有人使用完全相同的工具版本，大幅减少“在我机器上能跑”的问题。

asdf 有哪些亮点特色？ #

• 一个工具管理所有运行时：用单个 CLI 命令接口管理项目中每个运行时和工具的版本，告别多套版本管理器各自为政的混乱局面。
• 丰富的插件生态：官方和社区提供了大量现成插件，覆盖 Node.js、Ruby、Python、Elixir、Erlang 等主流语言与工具，并可通过简单 API 自行扩展。
• 向后兼容已有配置：原生支持读取 .nvmrc、.node-version、.ruby-version 等旧版管理器的版本文件，迁移到 asdf 无需重写现有项目配置。
• 单一共享配置文件：所有工具版本集中定义在 .tool-versions 中，可提交到 Git 仓库，确保团队每个成员使用完全一致的版本。
• 多 Shell 支持与补全：支持 Bash、ZSH、Fish、Elvish 等 Shell，并提供命令补全，适配不同开发者的终端习惯。
• GitHub Actions 集成：官方提供 GitHub Action，可在 CI/CD 工作流中自动安装并利用 .tool-versions 文件，保持本地与流水线环境一致。
• 灵活版本来源：除了下载官方二进制，还支持从 Git 的 tag/commit/branch 编译安装，或使用 path: 指定本地自定义编译版本。
• 开源免费：asdf 是开源项目，核心代码托管于 GitHub，持续活跃更新，最新版本为 v0.20.2。

免费下载 asdf #

以下为官方提供的各平台安装包，点击链接即可下载。

asdf 如何使用？ #

官方推荐的入门流程如下：

1. 安装并配置 asdf：安装 asdf 后，将 shims 目录加入 PATH。以 Bash 为例，在 ~/.bash_profile 中添加：

   export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
   

   如需自定义数据目录，可额外设置 ASDF_DATA_DIR。

2. 安装插件：为需要管理的工具安装对应插件，例如：

   asdf plugin add nodejs
   asdf plugin add ruby
   

   可用 asdf plugin list all 查看插件仓库中的全部插件。

3. 安装指定版本：使用插件安装某个版本的工具：

   asdf install nodejs 10.15.0
   

4. 设置项目版本：在项目目录下设置版本，asdf 会更新 .tool-versions 文件：

   asdf set nodejs 10.15.0
   

   也可以直接编辑 .tool-versions 文件，内容示例如下：

   ruby 2.5.3
   nodejs 10.15.0
   

5. 按文件安装全部工具：在包含 .tool-versions 的目录下运行 asdf install，即可一次性安装所有声明的版本。团队新成员克隆项目后执行这一条命令，就能快速对齐开发环境。

此外，asdf 还支持多种版本格式，例如 ref:v1.0.2-a、ref:39cb398vb39、path:~/src/elixir 和 system，分别对应 Git 标签/提交、本地路径自定义编译版本和系统自带版本。

asdf 的常见问题？ #

asdf 和 nvm、rbenv、pyenv 有什么区别？

nvm、rbenv 等通常是针对单一语言或工具的 Shell 脚本管理器，各自有独立的命令和配置文件。asdf 通过插件系统统一了接口，用一套命令和 .tool-versions 文件管理所有这些工具，适合需要同时处理多种运行时的项目。

asdf 是包管理器吗？

不是。asdf 明确定位为“工具版本管理器”，它不管理工具的上游依赖，也不替代 Homebrew、NixOS 等包管理器。它只负责切换同一工具的不同版本，系统依赖仍需用户自行安装。

asdf 支持哪些 Shell？

官方支持 Bash、ZSH、Fish、Elvish，同时提供 PowerShell Core 的配置说明和命令补全支持。不同 Shell 需要按文档配置 shims 路径和补全脚本。

如何兼容已有的 .nvmrc 或 .ruby-version 文件？

在 ~/.asdfrc 中将 legacy_version_file 设置为 yes，asdf 便会在缺少 .tool-versions 时读取插件支持的传统版本文件，方便从旧工具平滑迁移。

安装工具时下载的源码或二进制会被保留吗？

默认不会。always_keep_download 默认为 no，安装成功后 asdf 会删除下载的源码或二进制；如果希望保留，可将其设为 yes。

插件仓库多久同步一次？

由 plugin_repository_last_check_duration 控制，默认 60 分钟。可设为 0 表示每次触发都同步，或设为 never 关闭自动同步。

asdf 如何安装？ #

asdf 提供多种安装方式，可根据操作系统和习惯选择。

macOS #

方式一：Homebrew（推荐）

brew install asdf

Homebrew 会自动处理依赖和 PATH 配置。

方式二：下载预编译二进制

1. 从上方下载表格获取对应架构的 darwin-amd64 或 darwin-arm64 压缩包。
2. 解压后得到 asdf 二进制文件。
3. 将其移动到 $PATH 中的某个目录，例如 /usr/local/bin。
4. 运行 type -a asdf 确认命令可用。

方式三：从源码构建

git clone https://github.com/asdf-vm/asdf.git --branch v0.20.2
cd asdf
make

然后按文档将生成的二进制复制到 $PATH 中。

Linux #

方式一：包管理器

• openSUSE 用户可执行 zypper install asdf。

• Arch Linux 用户可通过 AUR 安装：

  git clone https://aur.archlinux.org/asdf-vm.git
  cd asdf-vm
  makepkg -si
  

方式二：下载预编译二进制

1. 根据系统架构选择 linux-386、linux-amd64 或 linux-arm64 压缩包。
2. 解压并将 asdf 二进制放入 $PATH 目录。
3. 执行 type -a asdf 验证。

方式三：go install

go install github.com/asdf-vm/asdf/cmd/asdf@v0.20.2

无论哪种方式，安装后都需要将 shims 目录