nvmによるNode.js環境構築ガイド 基本コマンドと実践的運用

Node.jsとバージョン管理の必要性

Node.jsはサーバーサイドでJavaScriptを実行するためのランタイム環境である。イベント駆動型のアーキテクチャと非同期処理を特徴とし、Web APIの構築やフロントエンドのビルドツール実行など幅広い領域で利用されている。npmをはじめとするパッケージマネージャの存在もあり、現代の開発現場では欠かせない基盤技術となった。

Node.jsは公式サイトからインストーラを取得して導入できる。しかし実際のプロジェクト運用では、複数バージョンを切り替えながら作業する場面が頻繁に発生する。たとえば既存システムがNode.js 18で稼働している一方で、新しいプロジェクトはNode.js 22を採用するといった状況である。このような場合に有効なのが、バージョン管理ツールのnvm（Node Version Manager）である。

nvmはユーザー領域にNode.jsをインストールし、シェルの設定に応じて利用するバージョンを切り替える仕組みを提供する。システム全体に影響を与えず、管理者権限なしで導入できる点が大きな利点である。

nvmの概要と仕組み

nvmはシェルの関数として実装されたバージョン管理ツールである。公式インストールスクリプトを実行すると、nvmのスクリプトがホームディレクトリ配下に展開され、シェルの起動時に読み込まれる。利用者はコマンドひとつでNode.jsのインストール、切り替え、削除を実行できる。

nvmの主要な機能は次のとおりである。

• 任意のバージョンのNode.jsをインストール
• インストール済みバージョンの一覧表示
• プロジェクトごとのバージョン自動切り替え
• デフォルトで使用するバージョンの指定
• 不要なバージョンのアンインストール

システム全体に影響を与える公式インストーラと異なり、nvmはホームディレクトリ配下に環境を閉じ込める。そのため複数バージョンの共存が容易であり、バージョンを切り替えても他の開発ツールに影響が及ばない。

nvmのインストール方法

macOSおよびLinuxの場合

macOSとLinuxでは、nvm公式のインストールスクリプトをcurlまたはwgetで取得して実行する。インストールスクリプトはGitHub上で公開されており、最新の手順はnvm-sh/nvmリポジトリのREADMEに記載されている。

インストール後、シェルの設定ファイルに以下の記述が追加される。

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

この記述により、シェル起動時にnvmが読み込まれる。zshを使用している場合は.zshrc、bashを使用している場合は.bashrcに追記される。インストール後はシェルを再起動するか、設定ファイルを再読み込みする必要がある。

Windowsの場合

Windows標準のコマンドプロンプトやPowerShellでは、nvmそのものは動作しない。Windows環境ではnvm-windowsという互換ツールを利用する。nvm-windowsはcoreybutler氏が開発している別プロジェクトであり、インストーラを公式リポジトリから取得して導入する。

nvm-windowsはnvmと似たコマンド体系を提供するが、内部実装は異なる。たとえばシンボリックリンクを利用してNode.jsのパスを切り替える方式であり、管理者権限が必要な場合がある。インストール前に既存のNode.jsを削除しておかないと、パスの競合が発生する可能性がある。

動作確認

インストール後、以下のコマンドでnvmのバージョンを確認できる。

nvm --version

バージョン番号が表示されれば導入は成功である。コマンドが見つからない場合は、シェルの設定ファイルにnvmの読み込み設定が正しく記述されているか確認する。

nvmの基本コマンド

バージョンのインストール

利用可能なNode.jsのバージョン一覧を表示するには、以下のコマンドを実行する。

nvm ls-remote

特定のメジャーバージョンをインストールする場合は次のように指定する。

nvm install 22

このコマンドはNode.js 22系の最新バージョンをインストールする。開発版や特定のマイナーバージョンを指定することも可能である。

nvm install 22.14.0

LTS版を明示的に指定したい場合は、リリース系統を指定する方法もある。

nvm install --lts

インストール済みバージョンの確認

インストール済みのバージョン一覧は以下のコマンドで確認できる。

nvm ls

現在使用中のバージョンには矢印が付与される。システムに複数のバージョンが存在する場合、切り替えが必要になる。

バージョンの切り替え

特定のバージョンを使用するには、nvm useコマンドを実行する。

nvm use 20

この操作は現在のシェルセッションにのみ影響する。新しいターミナルを開いた場合は、デフォルトとして設定されたバージョンが使用される。

デフォルトバージョンの設定

シェルを開いたときに自動的に適用されるバージョンは、以下のコマンドで設定する。

nvm alias default 22

この設定により、以降のシェル起動時はNode.js 22系が読み込まれる。新規メンバーのオンボーディング時に統一バージョンを強制したい場合、この設定を明示することが有効である。

バージョンのアンインストール

不要になったバージョンは以下のコマンドで削除できる。

nvm uninstall 18

アンインストール前に、そのバージョンが使用中でないことを確認する必要がある。現在使用中のバージョンを削除しようとするとエラーが発生する。

Node.jsとnpmの基本ワークフロー

nvmでNode.jsを導入すると、npmも同時にインストールされる。npmはNode.js標準のパッケージマネージャであり、ライブラリの導入やスクリプトの実行に使用する。

プロジェクトの初期化

新規プロジェクトを作成する際は、最初にpackage.jsonを生成する。

npm init -y

package.jsonにはプロジェクト名、バージョン、依存パッケージ、スクリプト情報が記録される。チーム開発ではこのファイルをリポジトリにコミットし、環境の再現に利用する。

パッケージのインストール

依存関係を追加するには、npm installコマンドを実行する。

npm install express

実行後、node_modulesディレクトリにパッケージが展開される。またpackage.jsonのdependenciesに追記される。開発時のみ必要なパッケージは—save-devオプションを付与する。

npm install --save-dev jest

スクリプトの実行

package.jsonのscriptsフィールドに定義したコマンドは、npm runで実行できる。

npm run test

lintやビルド、テストなど繰り返し実行する処理をスクリプトとして定義することで、チーム内の手順を統一できる。

package-lock.jsonの役割

npm installを実行すると、package-lock.jsonが自動生成される。このファイルは依存関係の正確なバージョンを固定する役割を担う。チーム開発ではpackage-lock.jsonもリポジトリにコミットし、全員が同一バージョンのパッケージを利用できるようにする。

プロジェクト運用での実践的なパターン

.nvmrcによるバージョン固定

プロジェクトのルートディレクトリに.nvmrcファイルを設定すると、利用するNode.jsのバージョンを明示できる。

22

このファイルが存在するディレクトリでnvm useコマンドを実行すると、自動的に指定バージョンへ切り替わる。

nvm use

.nvmrcはチーム開発において重要な役割を果たす。メンバーがNode.jsのバージョンを誤って使用することを防ぎ、ローカル環境と本番環境の差分を縮小できる。

package.jsonのenginesフィールド

package.jsonのenginesフィールドには、プロジェクトが対応するNode.jsのバージョン範囲を記述できる。

"engines": {
 "node": ">=20 <23"
}

この設定はnpm install時に警告を表示する。ただしnpm単体では厳密な強制力を持たないため、CI環境での検証と組み合わせて利用することが推奨される。

CI環境でのNode.jsバージョン指定

GitHub ActionsなどCI環境では、セットアップ用アクションを利用してNode.jsのバージョンを指定する。GitHub Actionsの場合、actions/setup-nodeを利用し、.nvmrcを参照する設定が一般的である。

- uses: actions/setup-node@v4
 with:
 node-version-file: '.nvmrc'

この方法により、ローカル環境とCI環境で同一のNode.jsバージョンを確保できる。nvm自体をCI環境にインストールする必要はなく、セットアップアクションがバージョン解決を担う。

nvmの利用に関する注意点

nvmはシェルの関数として動作するため、シェル起動時の設定ファイル読み込みに失敗するとコマンドを認識できない。特にmacOSでターミナルのデフォルトがzshに移行して以降、.zshrcへの追記漏れが起きやすい。トラブルシューティングの際は、まずwhich nodeの出力を確認する。システム側のNode.jsが優先されている場合、パスの優先順位を見直す必要がある。

またnvmでインストールしたNode.jsには、公式インストーラが同梱するnpmのグローバル設定が含まれない。グローバルパッケージを利用している場合は、nvm導入後に再インストールが必要となる場合がある。

編集部の見解

編集部はNode.jsの環境構築を評価する際、プロジェクトごとの再現性とチーム内の統一性を最重視する。nvmはこの観点で非常に優れたツールであり、導入コストの低さとコマンド体系の単純さは初心者にも扱いやすい。一方で、バージョン固定を.nvmrc任せにする運用は、メンバーの意識次第で破綻するため、CIでの検証を必須とするべきだと評価する。

現場での落とし穴として、nvm導入後に既存のグローバルパッケージが参照できなくなる問題が挙げられる。とくにWindowsのnvm-windowsでは管理者権限とパス構成の違いにより、予期しない動作が発生する。導入前に対象マシンの既存Node.js環境を調査し、必要に応じてクリーンインストールを実施することが重要である。

今後の方向性として、Node.js本体にバージョン管理機能が統合される可能性には注視が必要だ。BunやDenoの台頭によりランタイムの選択肢が広がる一方で、Node.js互換環境の管理手段も多様化している。nvmは今後も安定した選択肢であり続けるが、プロジェクトの特性に応じてVoltaやasdfなど代替ツールの評価も進めるべきだと見る。

参考

• Node.js 公式サイト
• nvm-sh/nvm GitHubリポジトリ
• coreybutler/nvm-windows GitHubリポジトリ
• npm 公式ドキュメント