.env ファイルが反映されない？Nuxt の環境変数ロードタイミングと prefix 問題

2025.09.27

Nuxt 3 プロジェクトで .env ファイルを作成して環境変数を設定したのに、開発サーバーや本番デプロイで値が反映されず、undefined になってしまった経験はありませんか？特に process.env.MY_KEY や useRuntimeConfig() から値を取得できないケースは、Nuxt の 環境変数ロードタイミング や prefix ルール を正しく理解していないとハマりやすいポイントです。

本記事では、Nuxt 3 の .env ロードの仕組みを整理し、ローカル・Docker・クラウド環境での再現例、よくあるミス、解決方法をまとめます。

目次

1. Nuxt における環境変数ロードの仕組み

Nuxt 3 は Vite ベースで動作しており、環境変数の読み込みは ビルド時 と ランタイム時 に分かれています。

  • ビルド時
    Vite が .env, .env.development, .env.production などをロードし、import.meta.env に埋め込む
  • ランタイム時
    runtimeConfig に注入された値を useRuntimeConfig() 経由で参照できる

特に注意が必要なのは、クライアントから参照可能な環境変数には必ず NUXT_PUBLIC_ prefix が必要という点です。たとえば次のような .env があった場合：

API_SECRET_KEY=abcdef123
NUXT_PUBLIC_API_BASE=/api
  • API_SECRET_KEY → サーバー側では process.env.API_SECRET_KEY や runtimeConfig.apiSecretKey で参照可能
  • NUXT_PUBLIC_API_BASE → クライアントサイドからも useRuntimeConfig().public.apiBase として参照可能

2. よくある間違い例とエラー症状

よくあるミス

  • .env ファイルをプロジェクトルート以外に置いている（例：/config/.env）
  • prefix がついていない値をクライアントから参照しようとしている
  • .output や .nuxt ディレクトリが古く、キャッシュされた値が残っている
  • Docker や CI/CD 環境でビルド時に .env がコピーされていない

例えば、以下のコードを pages/index.vue に書いた場合：

<script setup lang="ts">
const config = useRuntimeConfig()
console.log(config.public.apiBase)
</script>

.env に API_BASE=/api とだけ書いていると、ブラウザコンソールには undefined と表示されます。これが典型的な「.env が効かない」症状です。

3. 再現環境とデバッグ方法

環境変数が正しくロードされているかを確認するために、次のようなデバッグコードを仕込むと便利です。

// server/api/debug.get.ts
export default defineEventHandler(() => {
  return {
    env: process.env.API_SECRET_KEY,
    runtime: useRuntimeConfig()
  }
})

これをブラウザから /api/debug にアクセスすると、サーバーが参照している環境変数と runtimeConfig の中身を確認できます。

4. 解決策と設定例

4-1. prefix を正しく付ける

クライアントから参照する値には必ず NUXT_PUBLIC_ を付与します。

NUXT_PUBLIC_API_BASE=/api

4-2. nuxt.config.ts で runtimeConfig を明示する

環境変数を runtimeConfig にマッピングすると、意図せぬ未定義を防げます。

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecretKey: process.env.API_SECRET_KEY,
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE
    }
  }
})

4-3. Docker / CI 環境では .env をビルド時にコピー

docker-compose.yml では以下のように .env を build context に含めます。

services:
  nuxt:
    build:
      context: .
      dockerfile: Dockerfile
    env_file:
      - .env

4-4. クラウド環境では環境変数をダッシュボードで設定

Vercel, Netlify, Cloudflare Pages などのホスティングサービスでは、.env はデプロイ時に反映されないため、必ず管理画面から環境変数を設定する必要があります。

5. よくあるハマりどころと対策

  • ビルドキャッシュの罠
    .output ディレクトリを削除せずに再デプロイすると、古い値が残ることがあります。CI/CD では毎回クリーンビルドするようにしましょう。
  • ランタイム変更が反映されない問題
    nuxt build で値が埋め込まれてしまうため、ビルド後に .env を変更しても反映されません。ランタイムで変更可能にしたい場合は runtimeConfig 経由で参照する必要があります。

6. まとめ

  • .env はプロジェクトルートに置き、クライアント向け変数には NUXT_PUBLIC_ を付与する
  • nuxt.config.ts で runtimeConfig を明示するとデバッグしやすい
  • Docker やクラウド環境では、ビルド時とランタイム時のロードタイミングに注意する
  • CI/CD では毎回クリーンビルドを行い、最新の環境変数を反映させる

環境変数の取り扱いはシンプルに見えて、Nuxt のビルド・ランタイムモデルを理解していないと予期せぬ挙動につながります。本番デプロイ前にローカルで useRuntimeConfig() の出力を確認しておくと安心です。

参考

タイトルとURLをコピーしました