asdf 多运行时版本管理器用单一工具与.tool-versions统一管理 Ruby、Node.js、Elixir 等所有运行时版本【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdfasdf 是一个可扩展的运行时版本管理器其官方首页本仓库 docs/pt-br/index.md 为葡萄牙语翻译版将自身定位为多运行时版本管理器O Gerenciador de Múltiplas Versões de Tempo de Execução核心理念是用一款 CLI 工具统一管理项目中所有运行时与工具的版本。本文以该首页为骨架结合仓库中的入门指南、命令参考与 Go 源码系统讲解 asdf 的核心特性、shim 工作原理、插件/版本/配置管理方式读完后你可以独立完成 asdf 的安装配置、插件接入、多版本切换与 CI/CD 集成。首页速览asdf 是什么官方首页通过 hero 区一句话概括了项目定位名称asdf定位多运行时版本管理器The Multiple Runtime Version Manager宣传语用一个工具管理你所有的运行时版本Manage all your runtime versions with one tool主行动按钮开始使用指向 docs/pt-br/guide/getting-started.md、了解 asdf 是什么指向 docs/pt-br/guide/introduction.md在 docs/pt-br/guide/introduction.md 中这一概念被进一步明确所有工具版本定义都集中在一个文件.tool-versions中你可以把它提交到项目 Git 仓库与团队共享确保每个人使用完全相同的工具版本。在 asdf 出现之前团队往往需要同时维护多个 CLI 版本管理器如 nvm、n、rbenv每个管理器都有自己独立的 API、配置文件和实现机制$PATH操纵、shims、环境变量等。asdf 通过统一的命令接口 统一的配置文件 简单的插件接口来简化开发工作流并可将支持范围扩展到几乎所有工具与运行时。::: tip 定位澄清 asdf 是工具版本管理器不是系统包管理器。首页与引言文档都强调它可以为任意工具创建插件并管理其版本但这并不意味着对每个工具都适合这样做上游依赖的管理责任仍在用户身上。 :::六大核心特性首页 features 区列出了 asdf 的六项核心卖点本节逐条展开并结合仓库内容深入讲解。1. 单一工具一个 CLI 管所有运行时Gerencie cada um dos runtimes e ferramentas dos seus projetos com uma única ferramenta de CLI 用一款 CLI 工具管理你项目中每一个运行时与工具传统方式下Node.js 用 nvm、Ruby 用 rbenv、Elixir 用 kiex……每个工具一个管理器命令各不相同仓库里散落着.nvmrc、.ruby-version、.node-version等各类版本文件。asdf 用一套命令覆盖所有场景核心命令分为三类详见 docs/pt-br/manage/core.md、docs/pt-br/manage/plugins.md、docs/pt-br/manage/versions.md。全部命令列表可在 docs/pt-br/manage/commands.md 查看其正文直接引用自仓库 internal/help/help.txt。2. 插件生态简单 API 扩展新工具Grande ecossistema de runtimes e ferramentas existentes. API simples para adicionar suporte para novas ferramentas conforme necessário! 庞大的既有运行时与工具生态简单的 API 可按需为新工具添加支持插件是 asdf 认识并处理具体工具Node.js、Ruby、Elixir 等的途径。插件 API 的完整说明见 docs/pt-br/plugins/create.md这里展示最常用的插件管理命令# 通过 Git URL 添加插件推荐不依赖短名仓库 asdf plugin add name git-url # 例asdf plugin add elm https://github.com/vic/asdf-elm # 通过短名仓库添加插件 asdf plugin add name # 例asdf plugin add erlang # 列出已安装插件 asdf plugin list # asdf plugin list --urls 同时显示插件 Git 地址 # 列出短名仓库中的全部插件 asdf plugin list all # 更新插件全部或指定 asdf plugin update --all asdf plugin update name # 移除插件同时移除该插件安装的所有工具版本 asdf plugin remove name官方文档建议优先使用asdf plugin add name git-url的长形式因为它不依赖短名仓库的同步状态。短名仓库的同步逻辑如下asdf plugin add name与asdf plugin list all会触发同步事件若.asdfrc中disable_plugin_short_name_repository yes同步会提前中止同步间隔默认 60 分钟可由plugin_repository_last_check_duration配置。插件管理的底层实现在 internal/plugins/plugins.go。3. 向后兼容平滑迁移旧配置文件Suporte para arquivos de configuração existentes .nvmrc, .node-version, .ruby-version para uma migração tranquila! 支持 .nvmrc、.node-version、.ruby-version 等既有配置文件实现平滑迁移asdf 支持按插件粒度读取其他版本管理器的版本文件。例如asdf-nodejs插件支持.nvmrc与.node-version文件rbenv场景下的.ruby-version也可由支持它的插件读取。启用方式是在 asdf 配置文件$HOME/.asdfrc中设置legacy_version_file yes默认值为no只读取.tool-versions开启后插件会在.tool-versions缺失对应工具时回退到传统版本文件。4. 单一配置文件.tool-versions.tool-versions para gerenciar todas as suas ferramentas, runtimes e suas versões em um único arquivo 用 .tool-versions 在单一文件里管理所有工具、运行时及其版本这是 asdf 使用体验的核心。.tool-versions文件存在于某个目录时其声明的版本将作用于该目录及所有子目录ruby 2.5.3 nodejs 10.15.0支持注释ruby 2.5.3 # This is a comment # This is another comment nodejs 10.15.0版本取值有四种格式格式含义10.15.0真实版本号支持二进制下载的插件将直接下载二进制ref:v1.0.2-a/ref:39cb398vb39从 GitHub 拉取指定 tag / commit / 分支并编译path:~/src/elixir使用自定义编译好的工具路径面向语言开发者system透传给系统中非 asdf 管理的同名工具版本同一工具可声明多个候选版本用空格分隔按顺序回退python 3.7.2 2.7.15 system在包含.tool-versions的目录中运行asdf install不带参数会安装其中声明的所有工具asdf install name只安装指定工具。文件既可直接编辑也可用asdf set命令更新。从源码看internal/toolversions/toolversions.go中Version结构体的Type字段明确限定为version、ref、path、system、latest五种WriteToolVersionsToFile负责创建/更新文件并保留已有行的注释asdf set命令的写文件逻辑见 internal/set/set.go。5. Shell 支持Bash、ZSH、Fish、Elvish 及更多Suporta Bash, ZSH, Fish Elvish com autocomplete. 支持 Bash、ZSH、Fish、Elvish且提供自动补全首页列出了四种主要 Shell实际仓库还支持 PowerShell Core、Nushell 与 POSIX Shell。各 Shell 的补全脚本位于 internal/completions/asdf.bash、asdf.zsh、asdf.fish、asdf.elvish、asdf.nushell可通过asdf completion shell动态生成。全部安装与配置步骤见 docs/pt-br/guide/getting-started.md。6. GitHub ActionsCI/CD 中直接复用.tool-versionsFornece um GitHub Action para instalar e utilizar seu .tool-versions em seu fluxo de trabalho CICD. 提供 GitHub Action在你的 CI/CD 工作流中安装并使用 .tool-versionsGitHub Action 的接入说明见 docs/pt-br/contribute/github-actions.md在 CI 中安装 asdf 并按其读取项目.tool-versions即可保证流水线与本地开发使用完全一致的工具版本。工作原理shim 与即时版本解析理解 asdf 的内部机制有助于排查问题和编写插件。核心流程依据 docs/pt-br/guide/introduction.md 与 docs/pt-br/manage/versions.md安装工具插件安装工具时会为包内每个可执行程序在$ASDF_DATA_DIR/shims默认~/.asdf/shims目录创建 shim。该目录通过asdf.sh/asdf.fish等脚本加入$PATH这就是已安装程序能在环境中被调用的原因。执行 shim当你运行被管理的可执行程序时实际运行的是 shim——一个极简包装器它exec辅助程序asdf exec并把插件名与包内可执行文件的路径传给它。版本解析asdf exec依据.tool-versions文件或环境变量确定要使用的工具版本再结合插件提供的exec-path回调确定包安装目录中的最终可执行路径并结合exec-env脚本构造执行环境最后真正执行该程序。版本查找是从当前工作目录逐级向上直到$HOME在所有.tool-versions文件中进行的且发生在执行被管理工具的**即时just-in-time**时刻。如果某个工具没有配置任何版本执行会直接报错用asdf current可以从当前目录查看各工具解析到或缺失的版本提前发现会失败的工具。::: warning 关于 shim 的 exec 机制 由于 shim 采用exec调用包内需要被 shell source 而不是直接执行的脚本必须绕过 shim 直接访问可用以下两个命令拿到真实路径# 返回当前版本主可执行文件路径 source $(asdf which ${PLUGIN})/../script.sh # 返回包安装目录路径 source $(asdf where ${PLUGIN})/bin/script.sh若想完全绕过 shim或希望在进入项目目录时自动设置环境变量官方推荐使用asdf-direnv社区插件。 :::shim 相关的核心命令详见 docs/pt-br/manage/core.md# 为当前版本重新生成 shimsnpm -g 安装 yarn 后需要 asdf reshim nodejs version # 列出提供某命令 shim 的插件与版本 asdf shimversions node # nodejs 14.8.0 # nodejs 14.17.3 # nodejs 16.5.0 # 在插件环境中执行命令 / 查看环境 asdf env node asdf env node which npmshim 生成与分发的实现位于 internal/shims/shims.goasdf exec/asdf env的实现在 internal/exec/exec.go 与 internal/execenv/execenv.go。快速开始安装、配置与第一个工具以下是 docs/pt-br/guide/getting-started.md 的完整实战主线。第一步安装 asdfasdf 提供多种安装方式方式命令Homebrewbrew install asdfZypperzypper install asdfPacman / AURgit clone https://aur.archlinux.org/asdf-vm.git cd asdf-vm makepkg -si或使用其他 AUR 助手预编译二进制从官方 Releases 下载对应系统/架构的压缩包解压出的asdf二进制放入$PATH目录go install先安装 Go再执行go install github.com/asdf-vm/asdf/cmd/asdfv0.20.0源码构建git clone仓库后执行make将生成的asdf二进制放入$PATH目录::: tip 版本说明 上文go install示例中的版本号来自入门文档由 release-please 自动维护本仓库 version.txt 当前记录的核心版本为0.15.0。实际安装时请以你所需的最新发布版本号为准。 :::安装后务必验证asdf已在$PATH中运行type -a asdf输出第一行应指向你放置二进制的目录否则说明安装未完成。第二步配置 Shell多数用户不需要自定义数据目录asdf 默认将插件、安装与 shim 数据写到$HOME/.asdf。如需修改先在 Shell RC 文件中导出ASDF_DATA_DIR。各 Shell 的核心配置Bash~/.bash_profileexport PATH${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH补全~/.bashrc. (asdf completion bash)ZSH~/.zshrcexport PATH${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH补全mkdir -p ${ASDF_DATA_DIR:-$HOME/.asdf}/completions asdf completion zsh ${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf # 然后在 .zshrc 中加入 fpath(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath) autoload -Uz compinit compinitFish~/.config/fish/config.fishif test -z $ASDF_DATA_DIR set _asdf_shims $HOME/.asdf/shims else set _asdf_shims $ASDF_DATA_DIR/shims end if not contains $_asdf_shims $PATH set -gx --prepend PATH $_asdf_shims end set --erase _asdf_shimsElvish~/.config/elvish/rc.elvvar asdf_data_dir ~/.asdf if (and (has-env ASDF_DATA_DIR) (!s $E:ASDF_DATA_DIR )) { set asdf_data_dir $E:ASDF_DATA_DIR } if (not (has-value $paths $asdf_data_dir/shims)) { set paths [$path $paths] }Nushell~/.config/nushell/config.nuconst asdf_data_dir ~/.asdf | path expand # or wherever you like const asdf_shims [$asdf_data_dir shims] | path join $env.PATH $env.PATH | where {$in ! $asdf_shims} | prepend $asdf_shimsasdf 脚本必须在设置$PATH之后、source 完框架如 oh-my-zsh之后再被 source。修改完成后重启 Shell通常新开一个终端标签页即可使PATH生效。第三步安装插件以 Node.jsasdf-nodejs插件为例。插件依赖因系统而异安装前请查阅插件仓库OS依赖安装命令Debianapt-get install dirmngr gpg curl gawkCentOS / Rocky Linux / AlmaLinuxyum install gnupg2 curl gawkmacOSbrew install gpg gawk部分插件存在 post-install 钩子因此建议先装依赖再装插件asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git第四步安装版本用asdf list all nodejs查看全部可用版本或用asdf list all nodejs 14过滤前缀。安装最新稳定版asdf install nodejs latest::: tip 关于latestasdf 强制使用精确版本号latest只是贯穿各命令的辅助关键字会在执行时解析为当时的实际版本号。 :::第五步设置版本设置全局默认版本写入$HOME/.tool-versions作用于 home 下所有目录除非被局部配置覆盖asdf set -u nodejs 16.5.0 # $HOME/.tool-versions: # nodejs 16.5.0在项目目录设置局部版本写入$PWD/.tool-versionsasdf set nodejs 16.5.0 # $PWD/.tool-versions: # nodejs 16.5.0asdf set只是把tool version写入对应.tool-versions文件的便捷封装可用-p/--parent写入最近的父目录文件。查找顺序为当前目录 → 逐级向上 →$HOME若完全找不到则版本解析失败并报错。对于系统已预装、不由 asdf 管理的工具如常见的python用asdf set name system将管理权交还给系统。版本管理命令速查安装asdf install name version从源码构建时可用ref:foo指定分支/tag/commit安装最新稳定版asdf install name latest按前缀asdf install name latest:17列出已安装asdf list name可按前缀过滤asdf list name 17列出全部可用asdf list all name可按前缀过滤显示最新稳定版asdf latest name可按前缀过滤设置版本asdf set [flags] name version [version...]-u/--home写$HOME-p/--parent写最近父目录卸载asdf uninstall name version查看当前版本asdf current/asdf current name通过环境变量临时指定版本asdf 支持形如ASDF_${TOOL}_VERSION的环境变量其取值格式与.tool-versions一致且优先于任何.tool-versions文件中的设置export ASDF_ELIXIR_VERSION1.18.1 # 当前 shell 会话使用 Elixir 1.18.1 ASDF_ELIXIR_VERSION1.4.0 mix test # 单条命令临时指定版本注意环境变量只在设置它的会话中生效其他运行中的 shell 会话仍遵循.tool-versions文件。配置详解.asdfrc与环境变量asdf 的配置由两部分组成随项目共享的.tool-versions以及用户机器特有的.asdfrc默认$HOME/.asdfrc。仓库根目录的 defaults 文件展示了全部默认值legacy_version_file no use_release_candidates no always_keep_download no plugin_repository_last_check_duration 60 disable_plugin_short_name_repository no concurrency auto各配置项含义配置项默认值说明legacy_version_fileno是否允许插件回退读取旧版版本文件如.ruby-versionuse_release_candidatesno是否在版本解析中使用预发布候选版本always_keep_downloadno安装成功后是否保留下载的源码/二进制yes保留plugin_repository_last_check_duration60短名插件仓库同步间隔分钟范围1~9999999990每次触发都同步never永不主动同步disable_plugin_short_name_repositoryno设为yes时禁用短名仓库同步asdf plugin add name git-url不受影响concurrencyauto编译源码使用的核心数auto依次探测nproc、sysctl hw.ncpu、/proc/cpuinfo失败则回退1常用环境变量变量默认行为示例ASDF_CONFIG_FILE$HOME/.asdfrcexport ASDF_CONFIG_FILE/home/john_doe/.config/asdf/.asdfrcASDF_TOOL_VERSIONS_FILENAME.tool-versionsexport ASDF_TOOL_VERSIONS_FILENAMEtool_versionsASDF_DIRbin/asdf可执行文件的父目录export ASDF_DIR/home/john_doe/.config/asdfASDF_DATA_DIR$HOME/.asdf存在时否则ASDF_DIRexport ASDF_DATA_DIR/home/john_doe/.asdfASDF_CONCURRENCY取concurrency配置export ASDF_CONCURRENCY32环境变量应在 sourceasdf.sh/asdf.fish之前设置。完整配置说明见 docs/pt-br/manage/configuration.md底层读取逻辑在 internal/config/config.go。此外.asdfrc还支持**钩子hooks**机制可在插件安装/更新/移除/reshim、工具安装/卸载以及插件命令执行前后运行自定义代码例如pre_plugin_name_command、pre_asdf_download_plugin_name、{pre,post}_asdf_{install,reshim,uninstall}_plugin_name等模式详见配置文档。更多进阶资源插件 API 与创建指南docs/pt-br/plugins/create.md核心命令exec、env、info、reshim、shimversions、update、uninstalldocs/pt-br/manage/core.md完整命令列表docs/pt-br/manage/commands.md内容来自 internal/help/help.txt常见问题与社区项目docs/pt-br/more/faq.md、docs/pt-br/more/community-projects.md参与 asdf 核心开发docs/pt-br/contribute/core.md从首页六条特性到 shim 的exec链路asdf 的设计始终围绕一个工具、一个配置文件、一个插件接口展开。掌握插件管理、版本解析顺序与.asdfrc配置后你就可以在同一项目里自由组合 Node.js、Ruby、Elixir、Erlang 等任意运行时并让团队与 CI 始终运行在完全一致的版本上。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
