Vite環境変数をvite.config.jsで使用する方法

Viteプロジェクトで環境変数を設定する際、特にvite.config.jsファイル内で環境変数を参照したい場合があります。しかし、クライアントサイドのコードとビルド設定での環境変数の扱いには重要な違いがあります。

問題点

Viteのデフォルト動作では、環境変数は以下のように扱われます：

• クライアントサイドコードではimport.meta.envオブジェクトを通じてアクセス可能
• VITE_プレフィックスのみがクライアントに公開される
• vite.config.jsでは直接環境変数を参照できない

以下のような.envファイルがある場合：

VITE_NAME=Wheatgrass
VITE_PORT=8080

vite.config.jsでVITE_PORTを参照してサーバーポートを設定したいというのが一般的なユースケースです。

解決策

方法1: loadEnv関数を使用する（公式推奨）

Viteが提供するloadEnv関数を使用するのが最も安全で公式な方法です。

import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig(({ mode }) => {
  // 環境変数を読み込む
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    plugins: [vue()],
    server: {
      port: parseInt(env.VITE_PORT) || 3000
    }
  }
})

ポイント

• modeは開発時は'development'、ビルド時は'production'が自動的に渡されます
• 第3引数の''はプレフィックス制限を無効化し、すべての環境変数を読み込むためです
• ポート番号のように数値が必要な場合はparseInt()で変換します

方法2: 環境変数をprocess.envにマージする

既存のプロセス環境変数とVite環境変数を結合する方法：

import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'

export default ({ mode }) => {
  // 環境変数をprocess.envにマージ
  process.env = { ...process.env, ...loadEnv(mode, process.cwd()) }
  
  return defineConfig({
    plugins: [vue()],
    server: {
      port: parseInt(process.env.VITE_PORT)
    }
  })
}

方法3: 特定の環境ファイルを読み込む

異なる環境ごとに別々の.envファイルを使用する場合：

import { defineConfig } from 'vite'
import dotenv from 'dotenv'
import fs from 'fs'

export default defineConfig(() => {
  // 環境に応じて適切な.envファイルを選択
  const envFile = process.env.NODE_ENV === 'production' 
    ? '.env.production' 
    : '.env.development'
  
  // dotenvで環境変数を読み込む
  const envConfig = dotenv.parse(fs.readFileSync(envFile))
  process.env = { ...process.env, ...envConfig }

  return {
    server: {
      port: parseInt(process.env.VITE_PORT)
    }
  }
})

環境変数の命名規則

Viteでは以下のプレフィックス規則に従うことを推奨します：

# クライアント公開OK（VITE_プレフィックス必須）
VITE_API_URL=https://api.example.com
VITE_APP_NAME=MyApp

# サーバーサイドのみ（任意のプレフィックス）
INTERNAL_API_KEY=secret-key
DATABASE_URL=postgres://...

注意事項

VITE_プレフィックスのない環境変数はクライアントバンドルに含まれないため、サーバーサイド専用の機密情報に使用できます。

よくある問題と解決策

問題1: process is not definedエラー

ESLintでprocess is not definedエラーが発生する場合：

// .eslintrc.cjs
module.exports = {
  env: {
    browser: true,
    es2020: true,
    node: true // node環境を有効化
  }
}

問題2: 型定義の追加

TypeScriptを使用している場合、環境変数の型定義を追加：

// env.d.ts
interface ImportMetaEnv {
  readonly VITE_PORT: string
  readonly VITE_API_URL: string
  // 他の環境変数...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

まとめ

Viteの環境変数をvite.config.jsで使用するには、loadEnv関数を使用するのが最も安全で公式な方法です。環境に応じて適切な方法を選択し、セキュリティに注意しながら環境変数を活用してください。

追加情報

• Vite公式ドキュメント - 環境変数
• Vite公式ドキュメント - 設定での環境変数使用