プロジェクトフロントエンド開発環境の構築

ツールの紹介

Node.js

Node.jsは、オープンソースのクロスプラットフォームJava Scriptランタイム環境です。Chromeで使用されているV8エンジンをベースにしており、JavaScriptをブラウザ外で运行环境で実行できるようにしている。

Node.jsは、Webサーバーサイドプログラムの開発だけでなく、フロントエンドエンジニアリングツール、コマンドラインツール、自動スクリプトなどの構築にも使用できます。最新のフロントエンドプロジェクトは、ビルドツールの実行、依存関係のインストール、開発サーバーの起動にNode.jsに依存しています。

V8は、インスタントコンパイルなどの编译技术を使用してJavaScriptを実行する。この最適化は、従来の逐次解釈脚本语言実行と比較してコードの运行速度を強化し、チームが重複するツールチェーンの开发成本を削減するのに役立ちます。

npm

npmはNode.jsエコシステムでよく使われるパッケージマネージャです。Node.jsのインストールは通常、npmと一緒に行われるため、別々にインストールする必要はありません。

npmは、在线提供开源 Node.jsパッケージのレジストリと、以下のためのコマンドラインツールの両方を接続します。

• package.jsonに従ってプロジェクトの依存関係をインストールおよび管理します。
• package-lock.jsonロック依存性解析結果により、異なる環境での実装の一貫性を向上させます。
• package.jsonで定義されているスクリプトnpm run devなどを実行します。
• npmパッケージのリリースと保守。

Yarn、pnpm、cnpmはすべてnpmエコシステムに関連していますが、まったく同じ方向には向いていません。Yarnとpnpmはオプションのパッケージマネージャであり、cnpmはnpmの使い方と互換性のあるクライアントです。単に“npmの国内ミラー”と解釈すべきではありません。プロジェクトはパッケージマネージャを可能な限り統一し、対応するロックファイルをコミットして依存関係の相違を避けるべきです。

NVM for Windows

NVM for Windowsは、Windowsプラットフォーム用のNode.jsバージョン管理ツールで、同じコンピュータに複数のNode.jsバージョンをインストールして切り替えることができます。

主な用途は：

• 異なるバージョンのNode.jsをインストール、アンインストール、表示します。
• プロジェクト要件に応じてNode.jsバージョンを切り替えます。
• 現在有効なNode.jsのバージョンを設定します。
• 異なるバージョンのNode.jsとの複数プロジェクトの互換性コストを削減。

注：WindowsはNVM for Windowsを使用しているが、macOS、Linuxで一般的に使用されているnvmとは同一プロジェクトではなく、インストール方法や一部コマンドに違いがある。

インストールのシナリオの説明

Node.jsのインストールと管理には、NVM for Windowsを使用することをお勧めします。Node.jsのスタンドアロン版をインストールしてからNVM for Windowsをインストールすることはお勧めしません。両方のインストールが存在する場合、環境変数またはインストールディレクトリの競合により、nvm useの切り替え後もnode -vに古いバージョンが表示されることがあります。

このプロジェクトで使用しているNode.jsのバージョンは22.17.0です。14.20.0は、古いプロジェクトとの互換性が必要な場合のバージョン切り替え演習にのみ使用され、現在のプロジェクトのデフォルトバージョンとしては使用できません。

古い環境の清掃

Node.jsまたはNVM for Windowsをインストールした場合は、古い環境をクリーンアップすることをお勧めします。新しいコンピュータはこのセクションをスキップします。

ステップ1：関連プログラムを閉じる

Node.jsを使用しているターミナル、IDE、開発サーバー、およびその他の関連プロセスをシャットダウンして、ファイルが占有されないようにします。

ステップ2：現在の環境を記録する

コマンド·プロンプトを開き、次のコマンドを実行します。

node -v
npm -v
where node
where npm

whereコマンドは、システムが実際に実行ファイルを呼び出しているディレクトリを確認するのに役立ちます。

! [Node.jsおよびnpmバージョンチェック] https//r2.hoshiumi.xyz/old_img/20260731085602274.png

ステップ3：古いNode.jsをアンインストールする

Windowsの“設定”または“コントロールパネル”でスタンドアロンのNode.jsをアンインストールし、元のインストールディレクトリが残っているかどうかを確認します。

NVM for Windowsを使用する場合は、特に元のNode.jsエンティティディレクトリがNVMのシンボリックリンクの場所を占有していないことを確認してください。ディレクトリを削除する前に、保存する必要のある構成やファイルが存在しないことを確認してください。

ステップ4：Windows 用の古いNVMのアンインストール

NVM for Windowsを再インストールする必要がある場合は、Windowsのアプリケーションアンインストール機能を使用してアンインストールできます。アンインストール後、NVM_HOME、NVM_SYMLINK、およびPATHに無効な構成が残っているかどうかを確認します。

なじみのない環境変数を削除しないでください。変数が古いNVMインストールディレクトリを指していることを確認してください。

ステップ5：npm 残留物の処理

npmのキャッシュとグローバルインストールディレクトリは、次のコマンドを使用して確認できます。

npm config get cache
npm config get prefix

古い環境が不要になったことを確認したら，対応するディレクトリをクリーンアップする.ユーザーディレクトリの.npmrcには、ミラー、プロキシ、またはプライベートウェアハウス構成が含まれている場合があり、削除する前にバックアップする必要があります。

Windows 用のNVMのインストール

ステップ1：インストーラを実行する

チームまたはコースから提供されたNVM for Windowsインストーラを実行します。インストール時にはデフォルトのディレクトリを使用することをお勧めします。ディレクトリを変更する場合は、パスに特殊文字が含まれないようにし、シンボリックリンクディレクトリに同じ名前のエンティティフォルダが存在しないことを確認してください。

インストーラが既存のNode.jsを引き継ぐかどうかを尋ねる場合は、インストールを終了し、前述のようにスタンドアロンNode.jsをアンインストールしてから再インストールしてパス競合を避けることをお勧めします。

ステップ2：ターミナルの再起動

インストールが完了したら、コマンドプロンプトまたはPower Shellを閉じてから再度開きます。Node.jsのバージョンを切り替える場合、Windowsは通常管理者権限を必要とするため、ターミナルを管理者として開くことをお勧めします。

次のコマンドを実行して、NVM for Windowsを確認します。

nvm version

一部の古いバージョンでもサポート：

nvm -v

! [NVM for Windowsバージョンチェック] httr2.hoshi.z_img2026073108560523.png

Node.jsバージョンのインストールと切り替え

現在のプロジェクトバージョンをインストールする

次のコマンドを実行して、このプロジェクトで必要なNode.jsをインストールします。

nvm install 22.17.0

インストール完了後に、このバージョンに切り替えるには：

nvm use 22.17.0

切り替え時にWindowsが権限確認ウィンドウをポップアップする場合は、コマンドのソースが正しいことを確認してから操作を許可します。

! [Node.js 22.17.0に切り替える] https//r2.hoshiumi.xyz/old_img/20260731085607937.png

現在のバージョンを確認する

次のコマンドを実行します。

nvm current
node -v
npm -v

ネイティブにインストールされているすべてのNode.jsバージョンを確認することもできます。

nvm list

古いバージョンのNVM for Windowsも利用できます。

nvm ls

リストにアスタリスクが付いているバージョンは、現在有効なバージョンです。

! [インストールされているバージョンと現在のバージョンを表示] https//r2.hoshiumi.xyz/old_img/20260731085609706.png

旧プロジェクトのバージョン切り替えの例

古いプロジェクトでNode.js 14.20.0が明示的に必要な場合にのみインストールしてください。

nvm install 14.20.0

! [Node.js 14.20.0をインストール] https//r2.hoshiumi.xyz/old_img/20260731085612493.png

インストール後、バージョンを切り替えて表示できます。

nvm use 14.20.0
nvm list

! [旧プロジェクトのバージョンを表示] https//r2.hoshiumi.xyz/old_img/20260731085614381.png

古いプロジェクトの処理が完了したら、現在のプロジェクトのバージョンに切戻してください。

nvm use 22.17.0

フロントエンドプロジェクトの起動

ステップ1：プロジェクトディレクトリに移動する

コマンドプロンプトまたはIDEターミナルを開き、プロジェクトのwebuiディレクトリに移動します。

cd <项目目录>\webui

ステップ2：Node.jsバージョンの確認

node -v
npm -v

現在のプロジェクトではNode.js 22.17.0を使用してください。バージョンが正しくない場合、次のように実行します。

nvm use 22.17.0

ステップ3：依存関係のインストール

プロジェクトを初めて実行したり、依存関係が変更されたりする場合は、依存関係をインストールする必要があります。

プロジェクトがコミットされており、package-lock.jsonが変更されていない場合は、次の繰り返し可能なインストールコマンドを優先します。

npm ci

package-lock.jsonがない場合、またはロックファイルを更新する必要がある場合は、次のようにします。

npm install

同じプロジェクト内でnpm、Yarn、pnpmを混ぜないでください。複数のロックファイルが同時に生成され、依存関係のバージョンが矛盾する可能性があります。

ステップ4：開発サーバーを起動する

npm run dev

起動に成功したら、端末の出力アドレスが優先されます。Viteプロジェクトのデフォルトのアドレスは、通常次のとおりです。

http://localhost:5173

5173ポートがすでに使用されている場合は、開発サーバが自動的に別のポートを選択することがあります。そのため、固定アドレスだけで起動が成功したかどうかを判断しないでください。

よくある質問のチェック

nvm useは正常に実行されたが、Node.jsバージョンに変更はない

次の項目を順番にチェックします。

• ターミナルを管理者として再度開きます。
• 古いターミナルウィンドウを閉じてから再確認します。
• where nodeを実行して、スタンドアロンNode.jsのパス競合をチェックします。
• nvm debugを実行して、NVM for Windowsで検出された問題を確認します。
• NVMのシンボリックリンクディレクトリが同じ名前のエンティティディレクトリで占有されていないことを確認します。

nodeまたはnpmが見つかりません

最初に実装：

nvm list
nvm use 22.17.0

ターミナルを閉じて開きます。それでも失敗する場合は、NVM_HOME、NVM_SYMLINK、およびPATHをチェックしてください。

npm installまたはnpm ciの失敗

主なチェック：

• 現在のNode.jsバージョンがプロジェクト要件を満たしているかどうか。
• package.jsonはpackage-lock.jsonと一致しているか。
• コマンドが正しいwebuiディレクトリで実行されているかどうか。
• ネットワーク、プロキシ、ミラー、プライベートウェアハウスは、構成が有効かどうかを認証します。
• 異なるパッケージマネージャが生成するロックファイルが混在しているかどうか。

npm run devプロンプトスクリプトは存在しません

package.jsonを開き、scriptsにdevが定義されているか確認します。npm run devはプロジェクト宣言を実行するスクリプトであり、すべてのフロントエンドプロジェクトがこのコマンドを使用するわけではない。