【Windows11+WSL2】asdfの使い方【v0.14.0】

はじめに

バージョン管理ツール asdf の紹介と使い方の記事です。

弊社でも導入を決定したので、手順をまとめます！

色々なプロジェクトを

弊社では基本的には Docker で運用していますが、やっぱり直接 node や PHP を触ることは多いです。
開発する上でバージョン管理ツールは必須なんですが、nvm や n など乱立しているせいで、逆に手間がかかる状況になっていました。
この asdf は汎用的なバージョン管理ツールで、プラグインの仕組みにより様々な言語を一括で管理できる優れものです！

想定環境

• Windows 11
• WSL 2
  • Ubuntu 24.04 LTS
  • bash
  • apt

その他、mac、Linux環境であれば問題なく動作するはず。
公式でかなりの環境をサポートしているので、そちらを参照のこと。

また、既にバージョン管理ツールが入っている場合は、消しておくと良い。
一応共存できるようだが、想定外の不具合に苦しむ（1敗）

asdf コアのインストール

curl と git が必要らしいので、確認してとってくる。

$ curl --version
curl 8.5.0 (x86_64-pc-linux-gnu) 
$ git -v
git version 2.43.0

# 上記が入っていなければ
$ sudo apt install curl git

次に GitHub から asdf を持ってくる。
バージョンは ここ から最新のものを参照すると良い。
asdf のファイルは全て、HOMEディレクトリの ~/.asdf というフォルダに格納される。

$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

asdf を自動的に起動させるため、 ~/.bashrc に以下のスクリプトを書き込む。

~/.bashrc

. "$HOME/.asdf/asdf.sh"
. "$HOME/.asdf/completions/asdf.bash"

ワンライナー
$ echo -e '\n# asdf\n. "$HOME/.asdf/asdf.sh"\n. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc && source ~/.bashrc

書き込んだら設定の再読込か、再起動をする。

$ source ~/.bashrc

$ asdf --version
v0.14.0-ccdd47d

これが本体

プラグインの使い方（nodejs）

入れたい言語のプラグインを入れて、必要なバイナリをインストール管理する。
様々な言語のプラグインがコミュニティで作成されている。
誰でも作成可能な反面、セキュリティは自己責任なので注意。

基本的にはここから探すとよい。このリストのものはコマンドからインストールできる。
https://github.com/asdf-vm/asdf-plugins

試しに nodejs でやってみる。
検索が貧弱なので grep コマンドと併用すると便利。
<プラグイン名> や <バージョン> はTAB補完に対応しているので、適宜使用するとよい。

# プラグインの検索
$ asdf plugin list all | grep node
nodejs                       *https://github.com/asdf-vm/asdf-nodejs.git

# プラグインの追加
# asdf plugin add <プラグイン名>
$ asdf plugin add nodejs

# バージョン一覧の表示
# asdf list all <プラグイン名>
$ asdf list all nodejs | grep 20.
...

# 特定バージョンのインストール
# asdf install <プラグイン名> <バージョン>
$ asdf install nodejs 20.10.0

# インストール済みのバージョンを確認
# asdf list <プラグイン名>
$ asdf list nodejs
  22.4.0

これだけでは使えない。
後述するバージョン指定が必要となる。

$ node -v
No version is set for command node
Consider adding one of the following versions in your config file at
nodejs 20.10.0

バージョンの切り替え方法（nodejs）

大きく二種類 global と local のバージョンが存在する。

global

システム全体で使用するバージョン。

# システム全体で使用するバージョンを指定
# asdf global <プラグイン名> <バージョン>
$ asdf global nodejs 20.10.0

$ node -v
v20.10.0

お手軽！
切り替えたいときはもう一回実行すれば良い。

local

ディレクトリごとに使用するバージョン。
現在のディレクトリに .tool-version というファイルが作成される。

# システム全体で使用するバージョンを指定
# asdf local <プラグイン名> <バージョン>
$ asdf local nodejs 20.10.0

$ node -v
v20.10.0

$ cat .tool-versions
nodejs 20.10.0

サブディレクトリも再帰的に反映される。

git clone する時

大体の人は、既存のリポジトリを git clone で持ってくるだけだと思う。
その時、.tool-versions のファイルがあれば自動的に拾ってくれる。

もし、記載のバージョンがインストールされていない場合は、エラーの中心にあるコマンドをそのまま実行する。

$ cat .tool-versions
nodejs 16.20.0

$ node -v
No preset version installed for command node
Please install a version by running one of the following:

asdf install nodejs 16.20.0

or add one of the following versions in your config file at /root/code/test/.tool-versions
nodejs 20.10.0
nodejs 22.4.0

$ asdf install nodejs 16.20.0

$ node -v
v16.20.0

yarn の注意点

node を入れると npm もセットで付いてくるのだが、 yarn は各バージョンごとに生成される。
もし yarn を使う場合は、npm からインストールしよう。

# 20.10.0 で yarn を入れる
$ asdf local nodejs 20.10.0
$ npm install -g yarn
$ yarn -v
1.22.22

# バージョンを変える
$ asdf local nodejs 16.20.0
$ yarn -v
No preset version installed for command yarn
Please install a version by running one of the following:

asdf install nodejs 16.20.0

or add one of the following versions in your config file at /root/code/test/.tool-versions
nodejs 20.10.0

# このバージョンでも yarn を入れる
$ npm install -g yarn
$ yarn -v 
1.22.22

いったんここまで！