nvm-windowsは、Windows環境で複数のNode.jsバージョンを効率的に切り替えるためのコマンドラインツールです。公式リポジトリはGitHub上で公開されており、安定版はReleasesページからダウンロード可能です。Node.jsの全リリース一覧はnodejs.orgのリリースアーカイブで確認できます。

基本コマンド一覧

インストール後にターミナル（PowerShellまたはCMD）でnvm -hを実行すると、以下のようなヘルプが表示されます（v1.1.11基準）：

PS C:\> nvm -h
Running version 1.1.11.
Usage:
  nvm arch                     : 現在のNode実行モード（x86/x64）を表示
  nvm current                  : 現在有効なNodeバージョンを表示
  nvm debug                    : 環境診断（権限・パス・プロキシ等の問題検出）
  nvm install <version> [arch] : 指定バージョンのインストール（例: "lts", "latest", "18.17.0"）
  nvm list [available]         : インストール済みバージョン／利用可能バージョンを一覧表示（別名: ls）
  nvm use [version] [arch]     : バージョン切り替え（例: nvm use 16.20.2）
  nvm uninstall <version>      : 不要バージョンの完全削除
  nvm node_mirror [url]        : NodeバイナリのミラーURLを設定（例: https://npmmirror.com/mirrors/node/）
  nvm npm_mirror [url]         : npmパッケージのミラーURLを設定（例: https://npmmirror.com/mirrors/npm/）
  nvm root [path]              : nvmのインストールルートディレクトリを変更（デフォルト: %USERPROFILE%\AppData\Roaming\nvm）
  nvm version                  : nvm自身のバージョンを表示（別名: v）

初期セットアップと操作フロー

1. インストール：公式サイトからnvm-setup.exeをダウンロードし、管理者権限で実行。インストーラーが自動的にPATHに追加します。
2. バージョン確認：nvm -vでnvmのバージョン、nvm listで既存インストールを確認。
3. 利用可能バージョンの参照：nvm list availableでダウンロード可能なNode.js全バージョンを取得。
4. 新規インストール：nvm install 18.17.0（LTS推奨ならnvm install lts）。
5. アクティブ化：nvm use 18.17.0で即時切り替え。以降のnodeやnpmコマンドはこのバージョンで実行されます。
6. ミラー設定（中国ユーザー向け）：
   • nvm node_mirror https://npmmirror.com/mirrors/node/
   • nvm npm_mirror https://npmmirror.com/mirrors/npm/

代表的な課題と回避策

① 権限エラー（Exit Code 1 / 5 / 145）

Windowsでは、シンボリックリンクの作成やC:\Program Filesへの書き込みに管理者権限が必要です。解決策として以下の3つが推奨されます：

• 開発者モードの有効化：Windows 10/11の「設定 → 更新とセキュリティ → 開発者向けオプション」から有効化すると、シンボリックリンク作成にUACプロンプトが不要になります。
• 非特権ディレクトリへのインストール：例えばC:\nvmやD:\nvmなど、システム保護領域外のパスをnvm rootで指定します。
• 事前のNodeアンインストール：nvm導入前に既存のNode.jsをコントロールパネルから完全削除し、PATHからnode.exeへの直接参照を除去してください。

② シンボリックリンクのロック問題

PowerShellやエクスプローラーでnvm use対象のバージョンフォルダ（例：C:\nvm\v18.17.0）を開いていると、Windowsがそのディレクトリをロックし、切り替えに失敗します。対処法は単純で、事前に別のディレクトリへ移動（cd \など）するだけです。

③ CI/CD環境でのタイミング問題

スクリプト内でnvm use直後にnpmコマンドを実行すると、シンボリックリンクの更新が完了しておらずエラーになることがあります。PowerShellではStart-Sleep -Seconds 1を挿入することで確実に同期できます：

nvm use lts
Start-Sleep -Seconds 1
npm install -g yarn

④ npmのインストール失敗

Node 14.x系（特に14.19.x）では、付属するnpm 6.14.7のダウンロード障害が報告されています。これはnpm公式リポジトリ側の問題であり、nvm-windows 1.1.7以降を使用することで回避可能です。また、npm.cmdの存在による競合時はnpm-windows-upgradeツールの利用が有効です。

高度なユースケース

複数Nodeバージョンの並列実行

nvm-windowsは「同時アクティブ化」をサポートしませんが、絶対パスによる明示的実行は可能です。たとえば：

• C:\nvm\v16.20.2\node.exe server.js
• C:\nvm\v18.17.0\node.exe worker.js

同様に、特定バージョンのnpmも直接呼び出せます：C:\nvm\v18.17.0\npm.cmd install。

Yarnのグローバルインストール

YarnはNode.jsのパッケージであるため、各Nodeバージョンごとに再インストールが必要です：

nvm use 18.17.0
npm install -g yarn

nvm use 16.20.2
npm install -g yarn

セキュリティ警告について

nvm-windowsの一部バイナリ（特にnvm-update.exe）はコード署名されていません。Microsoft DefenderやSmartScreenが「疑わしい」と判断することがありますが、これは機械学習ベースの判定であり、実際のマルウェアではありません。信頼性を高めるには、Windows Defenderの除外リストにnvmディレクトリを登録することを推奨します。

設計上の制約と代替案

.nvmrcファイルや自動バージョン検出などの機能は意図的に未実装です。これは、Windows上でのシェルスクリプトによる「shim」方式が安定性に乏しく、シンボリックリンクによる直接実行がより堅牢なアプローチであるという設計思想に基づいています。将来的なランタイム管理ニーズに対応するため、関連プロジェクト「Runtime Manager（rt）」の開発も進行中です。