ランタイム設定

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

公開

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

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available within server-side
    apiSecret: '123',
    // Keys within public, will be also exposed to the client-side
    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 ファイルは読み込まれません。
Docs > 4 X > Guide > Directory Structure > Env で詳細を読む。

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

2つの主要な要件があります

  1. 目的の変数は nuxt.config で定義されている必要があります。これにより、任意の環境変数がアプリケーションコードに公開されないようにします。
  2. ランタイム設定プロパティを上書きできるのは、特別な名前の環境変数のみです。つまり、NUXT_ で始まり、キーとケース変更を _ で区切る大文字の環境変数です。
runtimeConfig 値のデフォルトを異なる名前の環境変数（たとえば、myVar を process.env.OTHER_VARIABLE に設定するなど）に設定すると、ビルド時のみ機能し、ランタイムでは壊れます。runtimeConfig オブジェクトの構造と一致する環境変数を使用することをお勧めします。
Alexander Lichter が runtimeConfig を使用する開発者が犯す最大のミスを紹介するビデオをご覧ください。

例

.env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxt.dokyumento.jp
nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // can be overridden by NUXT_API_SECRET environment variable
    public: {
      apiBase: '', // can be overridden by NUXT_PUBLIC_API_BASE environment variable
    },
  },
})

読み込み

Vue アプリ

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

クライアント側とサーバー側で動作が異なります
  • クライアント側では、runtimeConfig.public および runtimeConfig.app (Nuxt が内部的に使用) のキーのみが利用可能であり、オブジェクトは書き込み可能でリアクティブです。
  • サーバー側では、ランタイム設定全体が利用可能ですが、コンテキスト共有を避けるために読み取り専用です。
app/pages/index.vue
<script setup lang="ts">
const config = useRuntimeConfig()

console.log('Runtime config:', config)
if (import.meta.server) {
  console.log('API secret:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>Check developer console!</div>
  </div>
</template>
セキュリティに関する注意: ランタイム設定キーをクライアント側にレンダリングしたり、useState に渡したりして公開しないように注意してください。

プラグイン

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

app/plugins/config.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('API base 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
})
event を useRuntimeConfig の引数として渡すことは任意ですが、サーバー ルートの実行時に 環境変数 によって上書きされたランタイム設定を取得するために渡すことをお勧めします。

ランタイム設定の型付け

Nuxt は、提供されたランタイム設定から typescript インターフェースを自動的に生成しようとします。unjs/untyped.

しかし、ランタイム設定を手動で型付けすることも可能です

index.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}
nuxt/schema は、エンドユーザーがプロジェクトで使用されているスキーマのバージョンにアクセスするための便利な機能として提供されています。モジュール作成者は、代わりに @nuxt/schema を拡張する必要があります。