.nvmrc の書き方：nvm use の自動化とチームでのバージョン固定

# .nvmrc の中身：バージョン文字列を1行書くだけ
echo "20.11.0" > .nvmrc

# .nvmrc のバージョンに切り替える
nvm use
# Now using node v20.11.0

.nvmrc はプロジェクトで使う Node.js バージョンを記録するファイルです。チームメンバーが同じバージョンで開発できるよう、リポジトリに含めて管理します。

.nvmrc の書き方

プロジェクトのルートに .nvmrc を作成します。

# バージョンを直接書く
echo "20.11.0" > .nvmrc

# LTS のエイリアスを使う方法
echo "lts/iron" > .nvmrc

# メジャーバージョンだけ指定する方法
echo "20" > .nvmrc

バージョン指定の書き方：

書き方	例	意味
完全なバージョン	`20.11.0`	完全一致
メジャー.マイナー	`20.11`	マイナー内の最新
メジャーのみ	`20`	メジャー内の最新
LTS エイリアス	`lts/iron`	その LTS 系列の最新

実運用では 完全なバージョン を指定するのが確実です。

nvm use で読み込む

cd my-project

nvm use
# Found '/path/to/my-project/.nvmrc' with version <20.11.0>
# Now using node v20.11.0 (npm v10.2.4)

.nvmrc のバージョンがインストールされていない場合：

nvm use
# Found '/path/to/my-project/.nvmrc' with version <20.11.0>
# N/A: version "20.11.0" is not yet installed.

# インストールしてから切り替え
nvm install
nvm use

nvm install も .nvmrc を読んで対象バージョンをインストールします。

ディレクトリ移動で自動切り替えする

cd するたびに手動で nvm use するのは手間です。zsh のフックを使うと自動化できます。

# ~/.zshrc に追加
autoload -U add-zsh-hook

load-nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version
    nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use
    fi
  elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
    nvm use default
  fi
}

add-zsh-hook chpwd load-nvmrc
load-nvmrc

設定後は source ~/.zshrc で反映します。これでディレクトリに入ると自動で nvm use が走り、出ると default バージョンに戻ります。

bash の場合は $PROMPT_COMMAND を使います。

# ~/.bashrc に追加
cdnvm() {
  command cd "$@" || return $?
  local nvm_path
  nvm_path=$(nvm_find_nvmrc)
  if [ -n "$nvm_path" ]; then
    nvm use
  fi
}
alias cd='cdnvm'

チームで .nvmrc を Git 管理する

.nvmrc はリポジトリに含めてチームで共有します。

# .gitignore には追加しない
git add .nvmrc
git commit -m "add .nvmrc: Node.js 20.11.0"

.gitignore に .nvmrc が含まれていないか確認します。

package.json の engines フィールドと組み合わせる

.nvmrc はランタイムの切り替えに使い、package.json の engines フィールドでバージョン要件をドキュメント化する運用がよく使われます。

{
  "engines": {
    "node": ">=20.11.0"
  }
}

engines は npm install 時の警告表示に使われます。どちらか一方でも良いですが、両方書くと意図が明確になります。

mise を使っている場合

mise は .nvmrc を自動で読み込みます。mise use で管理している環境でも .nvmrc がそのまま使えます。

# mise は .nvmrc を認識してバージョンを切り替える
cd my-project   # .nvmrc があれば自動で切り替わる

mise と nvm を混在させるより、どちらか一方に統一する方が管理しやすいです。

まとめ

操作	コマンド
.nvmrc を作成	`echo "20.11.0" > .nvmrc`
.nvmrc のバージョンに切り替え	`nvm use`
.nvmrc のバージョンをインストール	`nvm install`
自動切り替え（zsh）	`~/.zshrc` にフックを追加

nvm のインストールや基本コマンドは「nvm の使い方：Node.js のインストールとバージョン切り替え手順」を参照してください。

Node.js のバージョン管理ツールの比較は「Node.jsのバージョン管理：mise・nvm・Volta・asdf・nodenvの使い方」も参照してください。