很早之前我就已经开始使用 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 文件一次性安装所有列出的插件版本 |
| 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