在一台 Mac 上同时维护多个项目时，最麻烦的往往不是写代码，而是“版本对不上”。Node、Python 版本一变，依赖就可能装不上、CI 也会红。asdf 的思路是：用同一套命令与一个清单文件（.tool-versions）把运行时版本固定下来，团队协作也更一致。
asdf 官网：https://asdf-vm.com/
asdf-nodejs 插件：https://github.com/asdf-vm/asdf-nodejs
asdf-python 插件：https://github.com/danhper/asdf-python
1）同一台电脑要跑多个项目，每个项目的 Node/Python 版本不同。
2）你希望把“我电脑能跑”的环境写成文件，别人 git clone 后能快速复现。
3）不想为每个语言单独装一个版本管理器（比如 nvm + pyenv + ...）。
如果你用 Homebrew，执行：
brew install asdf
安装完成后，让终端加载 asdf。不同 Shell 的配置略有区别，这里以 zsh 为例：
echo ' . $(brew --prefix asdf)/libexec/asdf.sh' >> ~/.zshrc
然后重启终端或执行：
source ~/.zshrc
验证是否生效：
asdf --version
添加 Node.js 插件：
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
添加 Python 插件：
asdf plugin add python https://github.com/danhper/asdf-python.git
查看可用版本（示例）：
asdf list all nodejs
asdf list all python
安装你需要的版本（示例）：
asdf install nodejs 20.11.1
asdf install python 3.12.2
如果你想把它作为“默认版本”（全局）：
asdf global nodejs 20.11.1
asdf global python 3.12.2
更推荐的是：在项目目录里固定版本（项目级）。进入项目根目录，执行：
asdf local nodejs 20.11.1
asdf local python 3.12.2
这会生成/更新 .tool-versions，把版本写进文件。之后同事拉代码，只要安装好 asdf，就能根据这个文件对齐版本。
当你拿到一个已经包含 .tool-versions 的项目时，常用流程是：
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf plugin add python https://github.com/danhper/asdf-python.git
asdf install
asdf current
其中 asdf install 会读取 .tool-versions，把缺的版本装齐。
1）终端提示找不到 asdf 命令
大概率是 Shell 没加载 asdf 脚本。检查你的 ~/.zshrc 是否写入了加载行，并确认执行过 source ~/.zshrc。
2）切换版本后依然显示旧版本
尝试在项目目录执行 asdf current 查看当前生效版本；确认没有其它工具（如 nvm、pyenv）抢占 PATH。必要时重开一个终端窗口。
3）Python 构建依赖缺失导致安装失败
这通常是编译依赖问题。建议按照 asdf-python 的说明补齐依赖（参考上面的插件链接），再重新执行 asdf install python ...。
asdf 的关键价值是把“版本”变成代码库的一部分：项目里写清楚，机器上自动对齐。对多项目切换、团队协作、以及后续 CI/CD 一致性都很友好。
