はじめに：ランタイム設定がもたらす利便性と課題解決

Nuxtのランタイム設定は、アプリケーションの設定値や秘密情報を安全かつ柔軟に管理できる仕組みです。環境変数を直接コードに埋め込むのではなく、runtimeConfigを使うことで、ビルド時ではなく実行時に設定を切り替えられます。これにより、開発・ステージング・本番環境で異なる設定を簡単に適用でき、セキュリティ面でもクライアントに公開すべきでない情報を守ることが可能です。

しかし、便利な反面、使い方を誤るとクライアントに秘密情報が漏れたり、SSRとCSRの挙動の違いでバグが発生したりすることもあります。この記事では、Nuxtのランタイム設定の基本から実務での活用例、注意すべきポイントまでを丁寧に解説します。

まず結論：ランタイム設定の要点まとめ

• runtimeConfigはサーバー専用の秘密情報とクライアントにも公開する設定を分けて管理できる
• 環境変数はNUXT_プレフィックス付きで定義し、nuxt.configのruntimeConfigに対応させる必要がある
• クライアント側でアクセスできるのはruntimeConfig.publicのみで、サーバー側は全体を読み取り専用で利用可能
• useRuntimeConfig()を使ってVueコンポーネントやプラグイン、サーバールートから設定を取得できる
• シリアライズできない値（関数やMapなど）は設定に含められず、プラグインやミドルウェアで管理するのが望ましい
• 秘密情報を誤ってクライアントに渡さないように注意が必要

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

使うべきケース

• 環境ごとに異なるAPIキーやURLを切り替えたいとき
  例：開発環境はテストAPI、本番環境は本物のAPIを使う場合など

• 秘密情報をクライアントに公開せずサーバー側で安全に扱いたいとき
  例：APIのシークレットキーや認証トークン

• ビルド時ではなく実行時に設定を変更したいとき
  例：Dockerコンテナの環境変数で設定を差し替える場合

使わない方がよいケース

• 頻繁に変更される動的な設定を管理したい場合
  ランタイム設定はアプリ起動時に読み込まれるため、動的な変更には向きません。DBや外部APIから取得する方法が適切です。

• クライアント側で秘密情報を使いたい場合
  セキュリティ上のリスクが高いため、秘密情報はクライアントに渡さない設計が推奨されます。

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

1. APIのベースURLを環境ごとに切り替える

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: '' // 環境変数 NUXT_PUBLIC_API_BASE で上書き可能
    }
  }
})

// .env
NUXT_PUBLIC_API_BASE=https://api.example.com

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

2. サーバー側でAPIシークレットを安全に利用する

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '' // 環境変数 NUXT_API_SECRET で上書き可能
  }
})

// server/api/data.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)
  const secret = config.apiSecret
  const data = await $fetch('https://secure.api.com/data', {
    headers: { Authorization: `Bearer ${secret}` }
  })
  return data
})

3. プラグインでランタイム設定を利用して初期化処理を行う

// plugins/init.ts
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()
  console.log('APIベースURL:', config.public.apiBase)
  // ここでAPIクライアントの初期化などを行う
})

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

1. クライアントに秘密情報を誤って公開しない

runtimeConfigのpublic以外のキーはクライアントに送られませんが、テンプレートやuseStateに秘密情報を渡すとクライアントに漏れる可能性があります。必ずサーバー側だけで利用してください。

2. SSRとCSRでの挙動の違いに注意

• サーバー側ではruntimeConfig全体が読み取り専用で利用可能
• クライアント側ではruntimeConfig.publicのみが利用可能で、リアクティブかつ書き換え可能

この違いを理解せずにコードを書くと、クライアントで存在しないキーにアクセスしてエラーになることがあります。

3. シリアライズできない値は設定に含めない

関数やMap、SetなどはJSONに変換できないため、runtimeConfigに直接設定できません。こうした値はプラグインやミドルウェアで管理しましょう。

4. 環境変数の命名規則を守る

runtimeConfigの値を環境変数で上書きするには、NUXT_プレフィックスを付け、大文字かつアンダースコア区切りで指定する必要があります。これを守らないと実行時に反映されません。

5. .envファイルはビルド時のみ読み込まれる

開発やビルド時は.envファイルが読み込まれますが、ビルド後のサーバー起動時には読み込まれません。実行環境の環境変数設定が必須です。

まとめ

Nuxtのランタイム設定は、環境ごとに異なる設定や秘密情報を安全に管理できる強力な機能です。runtimeConfigを正しく使うことで、開発効率が上がり、セキュリティリスクも低減できます。ただし、SSR/CSRの違いや環境変数の命名規則、シリアライズ制限などのポイントを理解しないとトラブルの原因になるため、この記事の内容を参考に実務での活用を進めてください。