Node.js トラブルシューティング

本ドキュメントは、ServBayローカル開発環境を利用中にNode.js関連パッケージでよく発生する問題への対処法を開発者向けに解説します。

Node.js/npm/pnpm/yarn コマンドのバージョンが見つからない・認識されない

ServBayでNode.js、npm、pnpm、yarnを実行する際、下記のようなエラーが表示される場合は指定されたNode.jsバージョンの実行ファイルが見つかっていないことを示しています。

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

これは主に、使用しようとしているNode.jsの特定バージョンがServBayにインストールされていないか、もしくはnvmやhomebrew等でインストールした別のNode.jsバージョンを利用したいものの、環境設定の問題でServBayからそれらが認識できない状況で発生します。

ヒント

ServBayインストール後は、そこで提供するスクリプトエイリアス（Script Alias）が優先的にServBayのNode.jsパッケージを使うよう設定されます。万一指定バージョンがServBay上にない場合、nvm経由で管理されたデフォルトバージョン、続いてhomebrew管理バージョンを順に探しますが、それも見つからなければ上記のエラーが発生します。

主な原因：

1. 利用しようとしているNode.jsバージョンがServBayアプリ内でインストールされていない。
2. nvmまたはhomebrewを利用中でNode.jsバージョン切り替えを期待しているが、シェルの環境変数（特にPATHやNVM_BIN）の設定ミスでServBayのフォールバックが外部Node.jsを認識できていない。

解決策：

nvmでNode.jsバージョンを管理している場合でも同様のエラーが出る場合、典型的な原因はNVM_BIN環境変数が設定もしくはエクスポートされていないことです。nvmの正しいインストール時にはこの変数が自動で設定され、nvm管理のNode.js実行ファイルのパスを示します。

ホームディレクトリ上の~/.zshrcや~/.bash_profileなどのシェル設定ファイル内でnvm関連設定を確認し、NVM_BIN変数が正しく設定・エクスポートされているかを点検してください。そして設定反映のためsource ~/.zshrcなどで再読込するか、ターミナルを再起動しましょう。これでServBayはnvmのNode.jsバージョンを問題なく認識できるようになります。

もしnvmやhomebrewをそもそも使用していない、またはServBay管理のNode.jsバージョンを利用したい場合は、ServBayアプリの「パッケージ」画面から目的のNode.jsバージョンがインストール済みであることを確認してください。

node-sass などのnpmパッケージ利用時にアーキテクチャ非対応エラーが出る場合

Apple Silicon (M1/M2/M3/M4などArm64)チップ搭載Macで、古いまたはネイティブモジュール依存のnpmパッケージ（例: node-sass）を使用すると、Unsupported architecture (arm64)といったエラーに遭遇することがあります。これは、古いパッケージがx86_64用のバイナリしか持たない・もしくはビルド設定されていないためです。

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

主な原因：

一部のnpmパッケージにはC++などのネイティブコードが含まれていて、特定CPUアーキテクチャ向けにコンパイルが必要です。古いバージョンのパッケージではArm64（Apple Silicon）対応済みバイナリや対応コードが提供されていない場合があります。

解決策：

1. Arm64対応の最新代替パッケージへ移行（推奨）

   一番推奨されるのはArm64に完全対応した代替パッケージへ切り替えることです。具体的には、保守終了しつつあるnode-sassから、より機能的かつ積極的にメンテナンスされているsassパッケージへの移行です。ほとんどのモダンなフロントエンドプロジェクトやツールも既にsassへと移行済みです。

   npm uninstall node-sass
   npm install --save-dev sass

2. ServBayにてx86_64版Node.jsをRosetta 2で利用（非推奨）

   ServBayではx86_64アーキテクチャ用のNode.jsパッケージもインストール可能です。Apple Silicon搭載Macの場合はこれをmacOS標準のRosetta 2翻訳レイヤー経由で動作させることで、x86_64向けネイティブモジュールを含むNode.jsパッケージも一応利用できます。インストールはServBayアプリ「パッケージ」画面からx86_64バージョンを選択してください。

   

   ご注意： ただし、これはあくまで一時的な回避策として利用し、長期運用は推奨しません。Rosetta 2によるエミュレーションにはパフォーマンス低下や予期せぬ動作リスクがあるため、できる限り上記1の方法（Arm64完全対応パッケージへの移行）をご選択ください。

---