はじめに：Nuxtにおける環境変数管理の重要性

Nuxtでの開発や運用において、環境変数は設定や挙動を柔軟に切り替えるために欠かせません。.envファイルは、開発やビルド時に環境変数を簡単に管理できる便利な仕組みですが、Nuxtの特性や本番環境での挙動を理解しないと、思わぬトラブルやセキュリティリスクにつながることもあります。

本記事では、Nuxt公式ドキュメントの補足として、.envファイルの基本的な使い方から、実務での活用例、注意すべきポイントまでを詳しく解説します。初〜中級者の方が安心して環境変数を扱えるよう、具体的なコード例や運用のコツも交えて紹介します。

まず結論：Nuxtの.envファイル活用のポイント

• .envファイルは開発・ビルド・生成時に自動で読み込まれ、process.envに反映される
• 本番環境では.envは読み込まれず、環境変数はホスティング環境側で設定する必要がある
• 複数の環境ごとに.env.localや.env.productionなどを使い分け可能
• アプリケーションコード内では直接process.envを使わず、Runtime Configを利用するのが推奨される
• .envの変更は開発中は自動で反映されるが、ビルド後は再ビルドが必要

いつ使うべきか、使わない方がよいケース

使うべきケース

• 開発中にAPIキーや設定値を簡単に切り替えたいとき
• ビルド時に環境ごとの設定を差し替えたいとき（例：開発・ステージング・本番）
• ローカル環境での動作確認やテストを行う際に環境変数を管理したいとき

使わない方がよいケース

• 本番環境の秘密情報を.envに直接書いてリポジトリに含める場合（セキュリティリスク）
• 実行時に動的に環境変数を変更したい場合（ビルド時に固定されるため）
• クライアントサイドで直接参照する必要がある値（Runtime Configのpublic側を使うべき）

実務でよくあるユースケースとサンプルコード

1. 開発環境と本番環境でAPIエンドポイントを切り替える

# .env
API_BASE_URL=https://dev-api.example.com

# .env.production
API_BASE_URL=https://api.example.com

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBaseUrl: process.env.API_BASE_URL || 'https://default-api.example.com'
    }
  }
})

const config = useRuntimeConfig()
const apiUrl = config.public.apiBaseUrl

2. ローカルでの開発時にのみ有効な設定を.env.localで管理

npx nuxt dev --dotenv .env.local

.env.localは.gitignoreに含めて秘密情報を管理しやすくする運用が一般的です。

3. 本番環境での環境変数設定（例：VercelやNetlify）

本番環境では.envファイルは読み込まれないため、ホスティングサービスの管理画面で環境変数を設定します。これにより、ビルド時や実行時に適切な値が注入されます。

よくある落とし穴・注意点

1. .envの変更が即時反映されない場合がある

開発中はNuxtが自動で再起動し反映されますが、ビルド済みのアプリでは再ビルドが必要です。変更後に反映されない場合はビルドプロセスを見直しましょう。

2. 本番環境で.envが無視される理由

Nuxtはサーバーレスやエッジ環境にも対応するため、ファイルシステムに依存しない設計です。したがって、本番環境では.envを使わず、環境変数はホスティング側で管理する必要があります。

3. クライアントサイドでの環境変数の扱い

process.envはサーバー側でのみ安全に使えます。クライアントで使う値は必ずRuntime Configのpublic側に設定し、useRuntimeConfig()で取得してください。

4. セキュリティリスクに注意

.envに秘密情報を含めたままリポジトリにコミットすると、情報漏洩のリスクがあります。必ず.gitignoreに追加し、秘密情報は安全な方法で管理しましょう。

まとめ

Nuxtの.envファイルは開発やビルド時の環境変数管理に非常に便利ですが、本番環境では使われない点を理解することが重要です。実務では環境ごとにファイルを分けたり、Runtime Configを活用したりすることで安全かつ柔軟な設定管理が可能です。落とし穴を避けるためにも、環境変数の役割とNuxtの動作を正しく理解し、適切に運用しましょう。