如何基于asdf-vm使用.tool-versions.local实现项目本地工具管理？

很多asdf用户都在用.tool-versions.local的工作流来实现项目共享工具之外的本地自定义需求，具体实现步骤如下：

1. 配置Git忽略本地文件 #

先把.tool-versions.local加入项目的.gitignore，避免将个人自定义的工具版本提交到仓库：

# 忽略asdf本地自定义版本文件
.tool-versions.local

2. 添加本地自定义工具版本 #

有两种方式可以添加本地工具，且不会修改项目共享的.tool-versions：

• 手动编辑文件：直接创建或编辑.tool-versions.local，格式和.tool-versions完全一致，每行对应一个工具和版本，比如：

  myplugin latest
  python 3.11.4
  

• 用asdf命令指定文件写入：通过ASDF_TOOL_VERSIONS_FILE环境变量指定写入.tool-versions.local，替代默认的.tool-versions，执行命令：

  # 添加插件（如果还没安装）
  asdf plugin add myplugin
  # 安装指定版本
  asdf install myplugin latest
  # 将版本写入.local文件，不会修改主文件
  ASDF_TOOL_VERSIONS_FILE=.tool-versions.local asdf local myplugin latest
  

3. 自动加载本地工具版本 #

asdf默认会自动读取当前目录下的.tool-versions和.tool-versions.local（.local文件优先级更高），只要你在shell里配置了asdf的环境，进入项目目录后就会自动应用这两个文件里的工具版本。

如果结合direnv使用，可以在.envrc里添加asdf的hook，让工具版本切换更顺畅：

# 根据你的shell选择bash/zsh/fish
source $(asdf direnv hook bash)

这样进入项目目录时，direnv会自动触发asdf的环境切换，同时加载.tool-versions和.tool-versions.local的配置。

补充说明 #

• .tool-versions.local的优先级高于.tool-versions，如果同一个工具在两个文件里都有配置，会使用.local里的版本。
• 不需要在.envrc或.envrc.local里重复执行安装命令，首次使用时手动执行asdf install即可，它会自动读取两个文件里的所有工具版本，安装缺失的部分。

内容的提问来源于stack exchange，提问作者user140090