viteコマンドが認識されない原因と解決策

問題概要

npm run dev を実行した際に以下のエラーが発生する場合：

'vite' is not recognized as an internal or external command, operable program or batch file.

このエラーは、Vite開発サーバーを起動するためのviteコマンドがシステムで見つからないことを示しています。

主な原因

この問題にはいくつかの一般的な原因があります：

1. 依存関係がインストールされていない - npm install を実行していない
2. Node.jsのバージョン問題 - 互換性のないNode.jsバージョンを使用している
3. 環境変数の設定 - NODE_ENV=production が設定されている
4. プロジェクトパスの問題 - パスに特殊文字が含まれている
5. グローバルインストールの不足 - Viteがグローバルにインストールされていない

解決策

1. 基本的な解決手順

まずは以下の基本的な手順を試してください：

# 依存関係のインストール
npm install

# 開発サーバーの起動
npm run dev

TIP

npm install はプロジェクトの package.json に記載されているすべての依存関係をインストールします。Viteは通常 devDependencies に含まれるため、このコマンドでインストールされます。

2. Node.jsのバージョン確認

ViteにはNode.js 14.18+（または16+）が必要です。バージョンを確認してください：

node -v

バージョンが古い場合は、Node.jsをアップグレードするか、Node Version Manager（NVM）を使用して適切なバージョンをインストールします：

NVMのインストール

# NVMのインストール（Windows以外）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
source ~/.nvm/nvm.sh

Node.js 18のインストール

nvm install 18
nvm use 18

3. キャッシュのクリアと再インストール

依存関係のキャッシュ問題が発生している可能性があります：

# node_modulesとpackage-lock.jsonを削除
rm -rf node_modules package-lock.json

# 依存関係の再インストール
npm install

4. 環境変数の確認

NODE_ENV が production に設定されていると、devDependencies（Viteを含む）がインストールされません：

# 環境変数を確認
echo $NODE_ENV

# 開発環境に設定（一時的に）
export NODE_ENV=development

# または明示的にdevDependenciesを含めてインストール
npm install --include dev

5. グローバルインストール

ローカルインストールが機能しない場合、Viteをグローバルにインストールします：

npm install -g vite

WARNING

グローバルインストールは一時的な解決策として有効ですが、プロジェクトごとにローカルにインストールされるべきです。チーム開発では特に、バージョンの一貫性を保つためにローカルインストールを推奨します。

6. プロジェクトパスの確認

プロジェクトのパスに特殊文字（:, &, /など）が含まれていると問題が発生する可能性があります：

• パスにコロンやアンパサンドが含まれていないか確認
• 可能な場合はシンプルなパス名に変更

7. package.jsonのスクリプト修正

直接パスを指定して実行する方法：

{
  "scripts": {
    "dev": "./node_modules/.bin/vite",
    "build": "./node_modules/.bin/vite build"
  }
}

トラブルシューティングフローチャート

以下の問題解決の流れを参考にしてください：

予防策

今後のプロジェクトで同様の問題を防ぐには：

1. Node.jsのLTSバージョンを使用 - 互換性の問題を最小限に抑えます
2. 定期的な依存関係の更新 - npm outdated で古いパッケージを確認
3. 一貫した環境設定 - チーム全体で同じ開発環境を維持
4. バージョン管理 - .nvmrc ファイルでプロジェクトのNode.jsバージョンを指定

まとめ

vite is not recognized エラーは一般的な問題ですが、ほとんどの場合は基本的なトラブルシューティング手順で解決できます。依存関係のインストール忘れやNode.jsのバージョン問題が主な原因であるため、まずはこれらの点から確認することをおすすめします。

INFO

Viteの公式トラブルシューティングガイドも参照してください：Vite Troubleshooting