解决 asdf 错误：No plugin named completion

问题描述

许多用户在运行 source ~/.zshrc 时遇到以下错误信息：

Unknown command: `asdf completion zsh`
No plugin named completion

这个问题通常出现在使用 oh-my-zsh 和 asdf 版本管理器的环境中。用户可能在 .zshrc 文件中只配置了 plugins=(asdf)，期望通过 oh-my-zzh 的 asdf 插件自动加载 asdf 环境，但却遇到了这个错误。

根本原因

这个问题的根本原因是 asdf 版本过旧。错误信息表明当前安装的 asdf 版本（如 v0.15.0）与 oh-my-zsh 的最新版本不兼容。特别是 oh-my-zsh 在 2025年2月的更新 后，对 asdf 插件的行为发生了变化，需要更新的 asdf 版本支持。

解决方案

方案一：升级 asdf 到最新版本（推荐）

升级到 asdf v0.16.3 或更高版本可以解决此问题。

Homebrew

# 如果您使用 Homebrew 安装 asdf
brew upgrade asdf

官方脚本

# 从 GitHub 发布页面下载最新版本
# 下载地址：https://github.com/asdf-vm/asdf/releases

# 添加二进制文件到 PATH
export PATH="$HOME/.asdf/bin:$PATH"

# 设置 ASDF 数据目录
export ASDF_DATA_DIR="$HOME/.asdf"

# 重新生成 shims
asdf reshim

方案二：手动配置环境变量

如果升级后问题仍然存在，可以尝试手动配置环境变量：

# 在 ~/.zshrc 中添加以下配置
export ASDF_DATA_DIR="$HOME/.asdf"
export PATH="$ASDF_DATA_DIR/shims:$PATH"

然后运行：

source ~/.zshrc
asdf reshim

方案三：检查 oh-my-zsh 插件配置

确保您的 .zshrc 文件中正确配置了 asdf 插件：

# ~/.zshrc 中应包含
plugins=(asdf)

注意事项

• 如果之前使用较旧版本的 asdf（v0.15.x 或更早），升级到 v0.16.x 可能需要遵循官方的升级指南
• 某些情况下，简单的 asdf update 可能不足以解决问题，需要完全重新安装
• 确保 $HOME/.asdf 目录存在且具有适当的权限

验证解决方案

升级完成后，可以通过以下命令验证问题是否已解决：

# 检查 asdf 版本
asdf --version

# 重新加载 zsh 配置
source ~/.zshrc

# 测试 asdf 命令是否正常工作
asdf plugin list

总结

"Unknown command: asdf completion zsh - No plugin named completion" 错误通常是由于 asdf 版本过旧与 oh-my-zsh 最新版本不兼容导致的。通过升级 asdf 到 v0.16.3 或更高版本，并确保正确配置环境变量，可以解决这个问题。

提示

定期更新您的开发工具可以避免许多兼容性问题。建议设置定期检查更新的习惯，或者使用自动化工具来管理这些依赖项的版本。