はじめに
AWS Amplify Gen2上にNuxt3アプリケーションをデプロイした際、「Amplifyの環境変数設定がローカルのように自動で上書きされない」という落とし穴に遭遇しました。本記事では、その仕様と注意点、さらに追加で発生したboolean型の取り扱いについても解説します。Amplifyで環境変数を利用する際の実践的な知見を共有します。
Nuxt3の環境変数の基本的な設定方法
まず、Nuxt3での環境変数の設定方法と、ローカル環境での挙動を整理します。
nuxt.config.tsでの設定
nuxt.config.ts で runtimeConfig を以下のように設定します。
export default defineNuxtConfig({
runtimeConfig: {
public: {
testEnv: false,
},
},
})
Vueファイル（例: app.vue）では useRuntimeConfig() で値を取得できます。
const config = useRuntimeConfig()
const { testEnv } = config.public
console.log('testEnv', testEnv, typeof testEnv)
この場合、ログは以下のようになります。
testEnv false boolean
.envファイルによる上書き
.env ファイルを作成し、NUXT_PUBLIC_ プレフィックスを付けて環境変数を定義すると、ビルド時やランタイム時に値を上書きできます。
NUXT_PUBLIC_TEST_ENV=true
この状態で実行すると、ログは次のようになります。
testEnv true boolean
このように、ローカル環境では.envファイルの値が自動的に反映され、boolean型として扱われます。
Amplify Gen2での落とし穴：環境変数の自動上書きが効かない
Amplifyにデプロイした場合、環境変数の設定方法や挙動がローカル環境と異なります。
Amplifyでの環境変数の設定
AWS Amplifyの管理画面から「ホスティング > 環境変数」ページで NUXT_PUBLIC_TEST_ENV に true を設定します。
Amplifyのドキュメントではビルド時に .env ファイルへ書き出す方法も紹介されていますが、Gen2ではGUIで設定した値がそのままビルド環境に反映されるように見えます。
しかし…自動上書きはされない
同じように NUXT_PUBLIC_TEST_ENV に true を設定しても、Amplify上で実行すると以下のようなログが出力されます。
testEnv false boolean
つまり、ローカル環境と同じ方法ではAmplify上で値が反映されません。Amplifyの環境変数は、Nuxt3の.envによる自動上書き機能が効かない、という点が最大の落とし穴です。
追加で発生するboolean型の問題
Amplify環境で環境変数を正しく扱うため、nuxt.config.ts を以下のように修正して検証しました。
runtimeConfig: {
public: {
testEnv: false,
testEnvImport: import.meta.env.NUXT_PUBLIC_TEST_ENV ?? false,
testEnvBoolean: import.meta.env.NUXT_PUBLIC_TEST_ENV === 'true',
},
},
Vueファイルでのログ出力も追加します。
const config = useRuntimeConfig()
const { testEnv, testEnvImport, testEnvBoolean } = config.public
console.log('testEnv', testEnv, typeof testEnv)
console.log('testEnvImport', testEnvImport, typeof testEnvImport)
console.log('testEnvBoolean', testEnvBoolean, typeof testEnvBoolean)
Amplify上での出力結果は以下の通りです。
testEnv false boolean
testEnvImport true string
testEnvBoolean true boolean
この結果から、Amplifyの環境変数は import.meta.env で取得できるものの、型はstringとなり、Nuxt3の.envによる上書き機能は効かないことが分かりました。
結論と推奨設定
Amplify環境では、環境変数の自動上書きが効かないため、import.meta.env から直接値を取得し、boolean型に変換する必要があります。どちらの環境でも同じようにboolean型で扱いたい場合は、以下のように設定するのがベストです。
runtimeConfig: {
public: {
testEnv: import.meta.env.NUXT_PUBLIC_TEST_ENV === 'true',
},
},
こうすることで、NUXT_PUBLIC_TEST_ENV=true を設定すれば、ローカル・Amplifyのどちらでも boolean 型の true として扱うことができます。
おわりに
本記事では、Nuxt3をAmplify Gen2上にデプロイする際の「環境変数の自動上書きが効かない」という落とし穴と、追加で発生するboolean型の取り扱いについて解説しました。Amplifyで環境変数を利用する際は、環境ごとに仕様の違いを理解し、適切な型変換を行うことが重要です。この記事が同じ課題に直面している方の助けになれば幸いです。
Discussion