很早之前我就已经开始使用 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/asdf@v0.16.0

更新配置文件

需要修改 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。