はじめに
Node.jsのバージョン管理ツールであるnodenvについて、整理も兼ねて実務で使う基本コマンドをまとめました。
目次
🧷 nodenvとは？
nodenvは、Node.jsのバージョン管理ツールです。
複数のNode.jsバージョンを簡単に切り替えたり、プロジェクトごとに異なるバージョンを使い分けたりできます。
✅ nodenvを使うメリット
- プロジェクトごとに異なるNode.jsバージョンを指定できる
- 最新のNode.jsバージョンへ素早くアップデート可能
- システムのデフォルトバージョンを変更せずに切り替えられる
- npmと組み合わせて、環境構築がスムーズ
🧷 nodenvと他のツールの違い
✅ nodenvの特徴
- プロジェクトごとのバージョン固定が簡単
-
nodenv localでプロジェクトごとにバージョンを指定できる
-
- 高速で軽量
- 必要な時にバージョンを切り替える仕組みで、無駄なメモリ消費が少ない
- npmのバージョン管理もシンプル
- Node.jsのバージョンに応じたnpmが自動的に切り替わる
🚫 nvmとの違い
-
nvmはシェルごとにバージョンが反映されるのに対し、nodenvはディレクトリ単位で自動的にバージョンが反映されるため使い勝手が良い。
🧷 nodenvの仕組み
nodenvは、Node.jsのバージョン切り替えを シムリンク（仮想的な参照リンク） で実現しています。
✅ バージョン選択の優先順位
nodenvは以下の順でバージョンを読み取ります。
1. ローカル設定 (nodenv local)
- 現在のプロジェクトディレクトリ内で指定したバージョン
2. 環境変数 (NODE_VERSION)
- 環境変数で一時的にバージョンを指定する場合
3. グローバル設定 (nodenv global)
- システム全体のデフォルトバージョン
4. デフォルトのNode.js
-
nodenvが管理していない場合は、OSにインストールされているデフォルトのNode.js
🧷 nodenvの導入手順
✅ ① インストール
macOSの場合（Homebrew使用）
brew install nodenv
Linuxの場合（Ubuntu例）
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(nodenv init -)"' >> ~/.bashrc
exec $SHELL
-
nodenvをPATHに追加し、起動時に反映するように設定します。
✅ ② node-buildプラグインをインストール
node-buildはnodenvでNode.jsをインストールするために必要なプラグインです。
brew install node-build
これでnodenv installコマンドでNode.jsがインストールできるようになります。
✅ ③ 動作確認
nodenv -v
nodenvのバージョンが表示されればインストール成功！
🧷 nodenvの基本コマンドまとめ
🌤️ Node.jsバージョンの確認
🌿 現在のNode.jsバージョンを確認
nodenv version
20.10.0 (set by /path/to/.node-version)
- 現在有効になっているNode.jsのバージョンを表示します。
- バージョンが
.node-versionファイルで指定されている場合は、そのパスも表示されます。
🌿 インストール可能なバージョン一覧を表示
nodenv install -l
または
nodenv install --list-all
- インストール可能なNode.jsのバージョン一覧を表示します。
-
-lと--list-allは同じ意味で、どちらでも利用できます。
🌿 特定のバージョンのみ絞り込んで表示
nodenv install --list | grep -e "^20"
- 上記だと
grepコマンドで20系のバージョンのみ絞り込み表示します。 - 最新のLTSや特定系統のみインストールしたい場合に便利です。
🌤️ Node.jsバージョンのインストールと管理
🌿 nodenvとnode-buildを最新化
brew upgrade nodenv node-build
-
brewでnodenvとnode-buildを最新バージョンにアップグレードします。 - インストール可能なNode.jsバージョンが古い場合に最新版を取得するために実行します。
🌿 インストール済みのNode.jsバージョン一覧を表示
nodenv versions
18.17.1
* 20.10.0 (set by /usr/local/nodenv/version)
21.2.0
- すでにインストール済みのNode.jsバージョンを確認できます。
-
*がついているバージョンが現在有効になっているものです。
🌿 新しいNode.jsバージョンをインストール
nodenv install <バージョン番号>
nodenv install 20.10.0
- インストール後は
nodenv versionsでインストール済みかどうか確認しよう！
🌤️ 使用バージョンの設定
🌿 ローカル環境でプロジェクトごとに使用バージョンを指定
カレントディレクトリ以下で特定バージョンを使用
nodenv local <バージョン番号>
- 現在のディレクトリで特定のNode.jsバージョンを使用するように設定します。
-
.node-versionファイルが作成され、プロジェクトごとにバージョンを固定できます。
🌿 グローバル（システム全体）で使用バージョンを指定
nodenv global <バージョン番号>
- システム全体でのデフォルトNode.jsバージョンを指定します。
- グローバル設定は他のプロジェクトでも適用されます。
🌿 再認識（rehash）
nodenv rehash
- 新しいバージョンをインストールしたり変更した後に、nodenvに変更を認識させます。
- これを実行しないと、インストール済みのNode.jsが反映されない場合があります。
- 基本的にrehashが必要なタイミングは以下
-
npm install -gで新しい CLI コマンドを入れたとき -
npm uninstall -gでグローバルツールを消したとき
-
🌤️ npmのバージョン確認
npm -v
- 現在使用中のnpmのバージョンを確認します。
🧷 nodenvの活用例
🚀 プロジェクトごとに異なるNode.jsバージョンを使う
プロジェクトAとBで異なるNode.jsバージョンを使いたい場合
# プロジェクトA
cd ~/project-a
nodenv local 18.17.1
# プロジェクトB
cd ~/project-b
nodenv local 20.10.0
- project-aでは18系、project-bでは20系が使用されます。
🧷 トラブルシューティング
⚠️ インストールしたバージョンが反映されない場合
nodenv rehashを実行
nodenv rehash
⚠️ 最新のNode.jsバージョンが表示されない場合
brew upgradeでnodenvとnode-buildを最新化
brew upgrade nodenv node-build
🎉 まとめ
- 新しいNode.jsバージョンがリリースされた場合は、
brew upgrade nodenv node-buildで最新化しましょう。 - プロジェクトごとに異なるバージョンを使う場合は、
nodenv localを活用。 - 不具合時は
nodenv rehashで再認識を促しましょう。
✅ nodenvを導入することで、プロジェクトごとに柔軟なNode.jsのバージョン管理が可能になり、開発環境の構築が効率的になります！