ImportMetaエラー：Vite環境変数でProperty 'env' does not exist を解決

問題説明

Viteプロジェクト（VueやReactなど）でimport.meta.envを使用している際、以下のTypeScriptエラーが発生する場合があります：

Property 'env' does not exist on type 'ImportMeta'.ts(2339)

このエラーは、特にnpm run devでは動作するのにnpm run build時やIDE上でエラーが表示される場合が多いです。根本原因はTypeScriptがimport.metaオブジェクトのenvプロパティを認識していないことにあります。

// エラーが発生する典型的な使用例
const baseUrl = import.meta.env.BASE_URL; // ここでエラー

解決策

方法1: vite-env.d.tsの適切な設定（推奨）

最も確実な解決法は、Viteの型定義ファイルを正しく設定することです。

1. src/vite-env.d.ts ファイルを作成・更新

   /// <reference types="vite/client" />
   
   // 環境変数の型定義を拡張
   interface ImportMetaEnv {
     readonly BASE_URL: string;
     // 他のVite環境変数を追加
     readonly VITE_API_URL?: string;
     readonly VITE_APP_NAME?: string;
   }
   
   // ImportMetaインターフェースを拡張
   interface ImportMeta {
     readonly env: ImportMetaEnv;
   }

2. tsconfig.json を更新

   {
     "compilerOptions": {
       "types": ["vite/client"], // ここを必ず設定
       // 他の設定...
     },
     "include": [
       "src/**/*",
       "src/vite-env.d.ts" // ファイルを明示的に含める
     ]
   }

方法2: 追加の型参照が必要な場合 (Vite v4)

古いViteバージョンでは追加の参照が必要です。

/// <reference types="vite/client" />
/// <reference types="vite/types/importMeta.d.ts" /> // この行を追加

方法3: tsconfig.jsonのincludeパスを確認

型定義ファイルが検出されていないケースで有効です。

tsconfig.app.json またはメインの tsconfig.json を編集：

{
  "include": [
    "src/vite-env.d.ts", // このファイルを明示的に指定
    "src/**/*"
  ]
}

注意点

プロジェクトルートに env.d.ts を配置している場合、src/ 内に移動するだけで解決するケースがあります。

よくある落とし穴と追加対策

1. Vitest設定ファイルの干渉

Vitestを使用している場合、tsconfig.vitest.json の設定が競合する可能性があります。

// tsconfig.vitest.jsonの不適切な設定例：
{
  "include": ["tests/**/*.ts", "src/**/*.vue", "src/**/*.ts"] 
}

include からプロダクションコードパスを除外することで解決：

{
  "include": ["tests/**/*.ts"] // src関連を除外
}

2. IDEキャッシュの問題

設定を変更してもエラーが消えない場合、開発サーバーとIDEの再起動が必要です：

npm run dev -- --force  # Viteサーバー強制リスタート

3. サンプルプロジェクトとの比較

公式テンプレートの設定を参考にする：

npm create vite@latest my-app --template vue-ts

生成されたプロジェクトのvite-env.d.tsとtsconfig.jsonを比較します。

実践的なコード例

環境変数の安全なアクセス例：

const getEnvVariable = (key: string): string => {
  const value = import.meta.env[key];
  if (value === undefined) {
    console.warn(`環境変数 ${key} が設定されていません`);
    return "";
  }
  return value;
};

const API_URL = getEnvVariable('VITE_API_URL');

補足事項

1. エイリアスの利用
   特定の環境変数を頻繁に使う場合、エイリアスを作成：

   // src/constants/env.ts
   export const BASE_PATH = import.meta.env.BASE_URL;

2. TypeScript一時無視（最終手段）
   即時解決が必要な場合に限定：

   // @ts-expect-error: Vite環境変数のため暫定対応
   const baseUrl = import.meta.env.BASE_URL;

重要

一時無視はビルドエラーを防ぐだけの対症療法です。根本解決には型定義の拡張を実施してください。

結論

1. src/vite-env.d.tsでImportMetaEnvインターフェースを拡張
2. tsconfig.jsonでtypes: ["vite/client"]とincludeパスを設定
3. Vitest設定が干渉しないか確認
4. 開発サーバー再起動を実施

これらの手順により、Vite環境変数を型安全に利用できるようになります。公式ドキュメントのVite Environment Variablesも併せて参照してください。