ランタイム設定

Nuxtは、アプリケーション内で設定と秘密情報を公開するためのランタイム設定APIを提供します。

公開

アプリの他の部分に設定と環境変数を公開するには、nuxt.configファイルでruntimeConfigオプションを使用してランタイム設定を定義する必要があります。

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    // サーバーサイドでのみ利用可能な秘密鍵
    apiSecret: '123',
    // public内のキーはクライアントサイドにも公開されます
    public: {
      apiBase: '/api'
    }
  }
})

runtimeConfig.publicにapiBaseを追加すると、Nuxtはそれを各ページのペイロードに追加します。apiBaseはサーバーとブラウザの両方で普遍的にアクセスできます。

const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)

パブリックランタイム設定は、Vueテンプレート内で$config.publicとしてアクセスできます。

シリアライズ

ランタイム設定は、Nitroに渡される前にシリアライズされます。つまり、シリアライズおよびデシリアライズできないもの（関数、Set、Mapなど）は、nuxt.configに設定しないでください。

シリアライズできないオブジェクトや関数をnuxt.configからアプリケーションに渡す代わりに、このコードをNuxtまたはNitroのプラグインやミドルウェアに配置できます。

環境変数

設定を提供する最も一般的な方法は、環境変数を使用することです。

Nuxt CLIは、開発、ビルド、生成時に.envファイルを読み込むためのサポートを組み込んでいます。しかし、ビルドされたサーバーを実行するときは、.envファイルは読み込まれません。

こちらも参照 guide > directory-structure > env

ランタイム設定の値は、実行時に一致する環境変数によって自動的に置き換えられます。

2つの重要な要件があります：

目的の変数はnuxt.configに定義されている必要があります。これにより、任意の環境変数がアプリケーションコードに公開されないようにします。
特別に名前付けされた環境変数のみがランタイム設定プロパティを上書きできます。つまり、NUXT_で始まり、キーとケースの変更を_で区切る大文字の環境変数です。

runtimeConfigの値のデフォルトを異なる名前の環境変数（例えば、myVarをprocess.env.OTHER_VARIABLEに設定する）に設定すると、ビルド時にのみ機能し、実行時には壊れます。 runtimeConfigオブジェクトの構造に一致する環境変数を使用することをお勧めします。

Alexander Lichterによるランタイム設定の使用における開発者の最も一般的なミスを紹介するビデオを視聴してください。

例

.env

NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // NUXT_API_SECRET環境変数で上書き可能
    public: {
      apiBase: '', // NUXT_PUBLIC_API_BASE環境変数で上書き可能
    }
  },
})

読み取り

Vueアプリ

NuxtアプリのVue部分内でランタイム設定にアクセスするには、useRuntimeConfig()を呼び出す必要があります。

クライアントサイドとサーバーサイドで動作が異なります：

クライアントサイドでは、runtimeConfig.publicとruntimeConfig.app（Nuxtが内部で使用する）のキーのみが利用可能で、オブジェクトは書き込み可能でリアクティブです。
サーバーサイドでは、ランタイム設定全体が利用可能ですが、コンテキストの共有を避けるために読み取り専用です。

pages/index.vue

<script setup lang="ts">
const config = useRuntimeConfig()

console.log('ランタイム設定:', config)
if (import.meta.server) {
  console.log('APIシークレット:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>開発者コンソールを確認してください！</div>
  </div>
</template>

セキュリティ注意: ランタイム設定キーをクライアントサイドに公開しないように注意してください。レンダリングしたり、useStateに渡したりしないでください。

プラグイン

カスタムプラグイン内でランタイム設定を使用したい場合は、defineNuxtPlugin関数内でuseRuntimeConfig()を使用できます。

plugins/config.ts

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('APIベースURL:', config.public.apiBase)
});

サーバールート

サーバールート内でもuseRuntimeConfigを使用してランタイム設定にアクセスできます。

server/api/test.ts

export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`
    }
  })
  return result
})

useRuntimeConfigに引数としてeventを渡すことはオプションですが、サーバールートで実行時に環境変数によってランタイム設定が上書きされるようにするために渡すことをお勧めします。

ランタイム設定の型定義

Nuxtは、提供されたランタイム設定から自動的にTypeScriptインターフェースを生成しようとしますが、unjs/untypedを使用して手動でランタイム設定を型定義することも可能です。

index.d.ts

declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// 型を拡張する際には、何かをインポート/エクスポートすることを常に確認することが重要です
export {}

nuxt/schemaは、エンドユーザーがプロジェクトでNuxtが使用するスキーマのバージョンにアクセスするための便宜として提供されています。モジュールの作成者は代わりに@nuxt/schemaを拡張するべきです。

※このページは Nuxt.js 公式ドキュメントの翻訳ページ（非公式）です。

公式ドキュメントの該当ページはこちら：
https://nuxt.com/docs/3.x/guide/going-further/runtime-config