很早之前我就已经开始使用 asdf 作为我本地的编程语言多版本管理工具，这个工具非常实用，但是最近 asdf 升级到了 0.16.0 版本，这是一个不兼容的版本，作者将整个项目中 asdf 从 Bash 脚本重写为 Go 语言，这带来了一系列的问题，这里记录一下我在升级过程中遇到的问题以及解决方案。

这个版本带来了许多重要变化，本文将重点详细介绍 asdf 0.16.0 的主要变更，以及升级过程中可能遇到的问题和解决方案。

asdf 0.16.0 的主要变化

Go 语言重写

asdf 0.16.0 最显著的变化是将整个项目从 Bash 脚本重写为 Go 语言。优点：

  • 性能提升：所有操作比之前的版本快 2-7 倍。
  • 代码质量提升：修复了许多长期存在的 bug。
  • 更易于维护：代码库更容易被新贡献者理解和参与。

安装方式变更

新版本的安装方式发生了变化：

  • asdf 现在是一个单一的二进制文件，而不是一系列 Bash 脚本。
  • 安装过程简化为三个步骤：下载二进制文件、添加 shims 目录到 PATH、设置 ASDF_DATA_DIR（可选）。
  • 不再支持自升级功能，需要通过操作系统包管理器或手动安装来升级。

cli 命令变更

一些命令发生了变化或被移除：

  • 移除了带连字符的命令，如 asdf plugin-add 改为 asdf plugin add。
  • asdf global 和 asdf local 被 asdf set 替代。
  • 移除了 asdf update 和 asdf shell 命令。

输出格式变更

asdf current 命令的输出格式发生了变化，现在提供更详细的信息。

升级注意事项

备份数据

在升级之前，建议备份您的 asdf 数据目录。

阅读升级指南

asdf 官方提供了详细的升级指南，强烈建议在升级前仔细阅读。

根据官方的指导安装 asdf 二进制文件，或者利用 go 命令下载。

go install github.com/asdf-vm/asdf/cmd/[email protected]

更新配置文件

需要修改 shell 配置文件（如 .zshrc 或 .bashrc）中的 asdf 相关设置，因为我之前很多 zsh 的配置都在 .zshrc 中，所以找到对应 asdf 相关的配置删除。然后工具官方的升级指南配置成最新。

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

配置完成之后可以使用 type -a asdf 来检查 asdf 的路径是否正确。系统会根据 PATH 中的配置找到对应的 asdf 命令，如果配置正确，会输出 asdf 的路径。

$ type -a asdf
asdf is /Users/einverne/go/bin/asdf

重新生成 shims

升级后需要运行 asdf reshim 重新生成所有 shims。

常用命令记录

最新版本的 asdf 的常用命令记录

子命令 作用
plugin add python [<仓库>] 添加插件（如 asdf plugin add nodejs 或指定 Git 仓库地址）
plugin list [–urls] 列出当前已安装插件，可加 --urls 同时显示插件 Git 仓库地址
plugin list all 列出官方注册的所有插件及其仓库地址
plugin remove <名称> 删除插件及其所有已安装版本
plugin update [<名称>] --all 更新指定插件（不带名称则更新全部插件）
install <名称> [版本] 安装指定插件的版本；若不指定版本，则按 .tool-versions 或全局设置安装
install 按当前目录或全局的 .tool-versions 文件一次性安装所有列出的插件版本
set nodejs 16.5.0 设置版本
uninstall <名称> <版本> 卸载某插件的指定版本
list [<名称>] 列出已安装的某插件所有版本；不带名称列出所有插件及对应版本
list all <名称> 列出某插件可安装的所有远程版本
latest [<名称>] 显示某插件的最新稳定版；不带名称时显示所有插件最新版本
current [<名称>] 显示当前目录或全局正在使用的某插件版本；不带名称显示所有插件
global nodejs 22.17.0 设置全局默认版本（写入用户主目录的 .tool-versions）
local python 3.13.5 设置当前目录本地版本（写入或更新本项目目录的 .tool-versions）
exec <命令> [参数…] 在 asdf 管理的环境中执行指定命令（相当于走 shim）
env <命令> [实用工具] 打印或运行指定命令，加载 asdf 环境变量
where <名称> [版本] 显示已安装版本的安装路径
which <可执行名> 显示 shim 指向的可执行文件路径
reshim [<名称>] [版本] 重建指定插件及版本的 shims；不带参数时重建所有 shims
shim-versions <命令> 列出所有提供指定命令 shim 的插件及版本
info 输出操作系统、Shell、asdf 调试信息，便于问题排查
help [<子命令>] 查看 asdf 或指定子命令的帮助信息

比如一个常见的场景，安装 Python 3.12.3 ，然后设置项目使用该版本

asdf plugin add python
asdf install python 3.12.3
python -m venv .venv
source .venv/bin/activate