😊

Next.jsにおける環境変数 (env) の取り扱い

に公開
Next.js
tech

個人のメモレベルで公式ドキュメントの環境変数について日本語翻訳した感じにしてます。

環境変数の基本的な設定方法

Next.jsのバージョン9.4以上から取り込まれた機能になります。

This document is for Next.js versions 9.4 and up. If you’re using an older version of Next.js, upgrade or refer to Environment Variables in next.config.js.

Next.js には環境変数の組み込みサポートが付属しており、次のことが可能になります。

  • .env.local を使用して環境変数の読み込みます。
  • NEXT_PUBLIC_ keyのprefixにすることで、ClientでもServer側でも読み込めるようにする

環境変数の読み込み

Next.jsは、環境変数を.env.localからprocess.envに読み込むことが可能です。

たとえば以下のように.env.localに書いた場合

.env.local
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

これにより、process.env.DB_HOST、process.env.DB_USER、および process.env.DB_PASSがNode.js環境に自動的に読み込まれ、Next.jsのData Fetching MethodとAPI Routerで利用できるようになります。

たとえばgetStaticPropsメソッドで利用する場合はこのように書きます。

pages/index.js
export const getStaticProps = async ()=> {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

Note
Next.jsは.env*の変数($VAR)を自動的に展開します。これにより、次のように他のシークレットを参照できます。

.env
HOSTNAME=localhost
PORT=8080
HOST=http://$HOSTNAME:$PORT

実際の値に$を含む変数を使用しようとしている場合は、\$のようにエスケープする必要があります。

例えば

.env
A=abc

# becomes "preabc"
WRONG=pre$A

# becomes "pre$A"
CORRECT=pre\$A

Note
/src フォルダーを使用している場合、Next.jsは/srcディレクトリからではなく、親ディレクトリからのみ.envを読み込むことに注意してください。

ブラウザへの環境変数の公開

デフォルトでは、環境変数はNode.js環境でのみ使用できます。つまり環境変数はブラウザーに公開されません。
変数をブラウザに公開するには、変数の前にNEXT_PUBLIC_を付ける必要があります。

.env
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

これは process.env.NEXT_PUBLIC_ANALYTICS_IDを自動的にNode.js環境に読み込み、コード内の任意の場所で使用できるようにします。
この値は、NEXT_PUBLIC_というprefixがあるため、ブラウザに送信されるJavaScriptにインライン化されます。
このインライン化はビルド時に行われるため、様々なNEXT_PUBLIC_環境はプロジェクトのビルド時に設定される必要があります。

pages/index.js
import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID'はprefixに`NEXT_PUBLIC_`がついているためここで使用可能です。
// ビルド時にsetupAnalyticsService('abcdefghijk')に変換んされます。
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

const HomePage = () =>(<h1>Hello World</h1>)

export default HomePage

Note
次のように変数を利用した場合のインライン化されません。

// 変数を使用した指定はインライン化されない
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// 変数を使用した指定はインライン化されない
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

defaultの環境変数

通常、必要な.env.localは1つですが、環境ごと(develop(next dev)やproduction(dev start))に.envを切り替えたい場合があります

Next.jsでは、.env(すべての環境)、.env.development(開発環境)、および.env.production (実稼働環境)を利用して各環境のdefaultを設定できます。

優先順位としては.env.localが上になるので常にdefaultの設定を上書きします。

Note
.env、.env.development、.env.productionについてはdefault定義なのでgitに含めたほうが良いです。
.env*.localについては役割としてはシークレットキーなどを書く事を想定しているため、git管理の対象から外すために.gitignoreに追加しましょう

環境変数の読み込み順

環境変数は次の順番に検索して最初に見つかった値を使います

  1. process.env
  2. .env.$(NODE_ENV).local
  3. .env.local(NODE_ENVがtestの場合はチェックされない)
  4. .env.$(NODE_ENV)
  5. .env

たとえば、NODE_ENVがdevelopmentで、.env.development.localと .env の両方で変数を定義した場合、.env.development.localの値が優先されます。

Note
NODE_ENVに利用できるのはproduction、development、testの3つです。

まとめ

今回は自分が現状使う部分だけを翻訳して書き残しました。
Vercelの場合の設定や、テスト環境での使い方に関してはまた別途時間のあるときに

参照情報

Next.JS - 環境変数

Discussion