Nuxt 3 で runtimeConfig が undefined に？環境変数・バージョン依存の読み込み失敗の対処法

Nuxt 3 を使った開発で、useRuntimeConfig() を呼び出したら undefined が返ってきてしまった……という現象に遭遇することがあります。とくに 3.13.0 などの一部バージョンや、Docker / クラウド環境にデプロイした際に発生しやすい印象です。

この記事では、Nuxt 3 の runtimeConfig の基本仕様を整理しつつ、undefined が返る原因と、環境変数・バージョン・Nitro 設定のチェックポイントを具体的にまとめます。CI/CD 環境や Docker でも役立つトラブルシューティングのヒントも紹介します。

目次

1. runtimeConfig の基本仕様とよくある落とし穴

Nuxt 3 では、環境変数は runtimeConfig を通じてアプリケーションに注入されます。nuxt.config.ts で次のように設定できます。

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: process.env.API_SECRET,
    public: {
      apiBase: process.env.API_BASE_URL || 'https://api.example.com'
    }
  }
});

そして、コンポーネント内では useRuntimeConfig() で参照します。

<script setup lang="ts">
const config = useRuntimeConfig();
console.log(config.public.apiBase); // 期待値: "https://api.example.com"
</script>

しかし、ある環境で config が undefined になったり、config.public が空オブジェクトになることがあります。この現象は、呼び出し順序の問題、ビルド時とランタイム時の差異、あるいは .env の命名やロードタイミングの問題が絡んでいるケースが多いです。

2. よくある原因パターンと再現例

runtimeConfig が undefined になる典型パターンを整理します。

  • .env ファイルの変数が NUXT_ プレフィックスで定義されていない
  • SSR 無効化設定（ssr: false）で Nitro が正しく初期化されていない
  • useRuntimeConfig() をビルド時のコード（nuxt.config.ts 外）で直接呼んでしまう
  • Nuxt 3 の特定バージョンで Nitro のバグにより config が初期化されない
  • Docker で環境変数が正しく渡されていない（docker-compose.yml の env_file 設定忘れ）

たとえば、以下のように .env に API_BASE_URL とだけ書いた場合、Nuxt 3 は自動で読み込みません。

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

正しくは NUXT_PUBLIC_ を付与します。

NUXT_PUBLIC_API_BASE_URL=https://api.example.com

そして参照するときは：

<script setup>
const config = useRuntimeConfig();
console.log(config.public.apiBaseUrl); // OK
</script>

この命名規則の違いに気づかず、undefined に悩まされるケースが多いです。

3. バージョン依存の問題とアップデート

Nuxt 3.13 系では、nitro のビルドキャッシュや環境変数のマージ処理に関連したバグが報告されていました。もし古いバージョンを利用している場合は、まずアップデートを検討しましょう。

# 最新の Nuxt 3 と Nitro に更新
npm install nuxt@latest
npm install @nuxt/nitro@latest

また、バージョン固定をしている場合は package-lock.json や pnpm-lock.yaml を削除し、クリーンインストールを行うと解決することがあります。

rm -rf node_modules
npm ci

CI/CD では古いキャッシュを持ったビルド環境で同じ問題が発生しやすいため、キャッシュをクリアして再ビルドすると改善します。

4. デフォルト値を設定して安全にする

ランタイム環境によっては環境変数が存在しないこともあるため、nuxt.config.ts でデフォルト値を設定しておくと本番で落ちる事故を防げます。

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: process.env.API_SECRET || 'default-secret',
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE_URL || 'https://fallback.example.com'
    }
  }
});

さらに TypeScript を併用するなら、型定義を追加しておくと安心です。

declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}

こうしておけば、useRuntimeConfig().public.apiBase をタイプセーフに参照できます。

5. Docker・クラウド環境での注意点

ローカルでは動くのに、Docker やクラウド（Vercel, Netlify）にデプロイすると runtimeConfig が空になることもあります。この場合は次のポイントを確認してください。

  • docker-compose.yml に env_file: .env を指定しているか
  • ENV NUXT_PUBLIC_... が Dockerfile 内で定義されているか
  • Vercel の環境変数 UI に正しく設定されているか
  • nitro.preset = 'node-server' など、ランタイムのモードを明示しているか

実運用では、Docker ビルド時に環境変数を固定してしまい、デプロイ先で変更できないケースがあるため、環境変数はできるだけランタイム注入にするのが理想です。

# 悪い例: ビルド時に固定
ENV NUXT_PUBLIC_API_BASE_URL=https://prod-api.example.com

ではなく、docker-compose.override.yml などで実行時に渡すようにします。

services:
  app:
    environment:
      - NUXT_PUBLIC_API_BASE_URL=${NUXT_PUBLIC_API_BASE_URL}

6. まとめ

Nuxt 3 の runtimeConfig は便利ですが、環境変数の命名、SSR 設定、バージョン依存バグ、Docker 環境の変数注入方法によっては undefined になることがあります。

  • .env では NUXT_PUBLIC_ プレフィックスを付与する
  • useRuntimeConfig() は実行時に呼び出し、ビルド時に直接参照しない
  • Nuxt / Nitro は最新版にアップデート
  • デフォルト値を設定して安全に運用
  • Docker・クラウド環境ではランタイム変数注入を徹底

これらを押さえておけば、本番環境で急に undefined になって慌てるリスクを大幅に減らせます。

参考

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