.env と runtimeConfig を用いた環境変数の利用方法【Nuxt3】
※ 環境
Nuxt 3.2.3
Node v18.11.0
Nuxt3 で環境変数を利用するには、
useRuntimeConfigを使う.envファイルを作成し、その中で定義する の 2 パターンの方法があります。
また、同じような設定ファイルで、useAppConfigを使う方法もあります。
今回は、それぞれの使い方・使い分けについて解説していきます。
useRuntimeConfig を使う
以下のようにruntimeConfigをnuxt.config.tsで定義することでランタイムの構成を使うことができます。
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
serverEnv: "serverValue",
public: {
clientEnv: "clientValue",
},
},
});
デフォルトの runtimeCountig の key、つまり例のserverEnvは、サーバサイドのみで利用できます。
また、publicプロパティの中で定義したものはクライアントサイド・サーバーサイド両方で使うことができます。
それらの値は、Nuxt が公開している composable であるuseRuntimeConfigを介してアクセスすることができます。
<script setup lang="ts">
const runtimeConfig = useRuntimeConfig();
console.log(runtimeConfig.public.clientEnv);
console.log(runtimeConfig.serverEnv); // サーバーサイドのみで利用できる
</script>
また、useRuntimeConfigは型の補完が効くため、環境変数に型安全にアクセスすることが可能です。
useAppConfig を使う
app.config.tsファイルをルートに置くことで、useAppConfigを介して環境変数を取得することができます。
app.config.ts
export default defineAppConfig({
theme: {
mode: "dark",
},
});
<script setup lang="ts">
const appConfig = useAppConfig();
</script>
useAppConfigで取得した値は、クライアント・サーバーサイドどちらでも利用することができます。
しかし、runtimeConfigと異なり、app.config.tsに設定した値はクライアントのコードにバンドルされてしまいます。
そのため、このファイルには機密性の高い情報を含めないように注意してください。
.env ファイルを使う
Nuxt CLI には起動時・開発時にdotenvが組み込みで入っています。そのため、ルート ディレクトリに.envファイルがあるとそれを読み込み、環境変数として利用することができます。
例えば、以下のような.envファイルを作成します。
.env
API_SECRET = "api secret";
process.envを介して呼び出すことができます。
この時、サーバーサイドでしか環境変数は呼び出せないので注意が必要です。
console.log(process.env?.API_SECRET);
.env ファイルと useRuntimeConfig を共存させる
また、.envファイルにNUXT_という接頭辞をつけると、ランタイム構成の環境変数を上書きすることができます。
以下のような構成を想定します。
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
secret: "hoge",
public: {
token: "fuga",
},
},
});
.env
NUXT_SECRET = "secret";
NUXT_PUBLIC_TOKEN = "token";
NUXT_をつけることで、環境変数secret、tokenを上書きすることができます。
また、ここで注目して欲しいところが、オブジェクトの階層を_で表現できるという点です。
ex. public > token → PUBLIC_TOKEN
const runtimeConfig = useRuntimeConfig();
// .envによるランタイム構成の上書き
// サーバーで'secret'と出力される
console.log(runtimeConfig.secret);
// ブラウザ・サーバーで'token'と出力される
console.log(runtimeConfig.public.token);
環境に応じて.env ファイルを使い分ける
.env.localや.env.productionのようにローカル・プロダクション環境など、環境に応じて環境変数を切り替えたいケースは多々あると思います。
そのような時は、--dotenvフラグを nuxt cli に渡すことで実現できます。
例を見てみましょう。
以下のようにローカル限定の環境変数を定義します。
.env.local
NUXT_SECRET = "local secret";
NUXT_PUBLIC_TOKEN = "local token";
次にpackage.json で開発時に—-dotenvフラグを使って.env.localを渡すようにします。
package.json
"dev-local": "nuxt dev --dotenv .env.local",
すると、.env.localの値が優先されるので、値が書き変わります。
const runtimeConfig = useRuntimeConfig();
// .envによるランタイム構成の上書き
// サーバーで'local secret'と出力される
console.log(runtimeConfig.secret);
// ブラウザ・サーバーで'local token'と出力される
console.log(runtimeConfig.public.token);
ユースケースによって環境変数の構成を使い分ける
最後にユースケースによって環境変数設定の使い分けを説明します。
| ユースケース | 使い分け |
|---|---|
| 型付された環境変数を使いたい | runtimeConfig, appConfig |
| 機密情報の高い変数を環境変数として扱いたい | runtimeConfig, .env |
| 環境によって環境変数を書き換えたい | .env(環境ごとの.env ファイルを用意) |
| process.env 経由でアクセスしたい(サーバサイドのみ) | .env |
個人的には、
「環境ごとの.env.XXXファイルを用意し、設定する値は全てruntimeConfigを置き換えるようにする(NUXT_を接頭辞につける)」方法がおすすめです。
これだと型が自動でつく & 環境ごとに柔軟に環境変数を切り替えれる という恩恵が得られるためです。
よければ Nuxt3 アプリケーション構成の参考にしてみてください！