環境変数

Next.jsには環境変数の組み込みサポートがあり、以下のことが可能です:

• .env.localを使用して環境変数を読み込む
• NEXT_PUBLIC_をプレフィックスとしてブラウザ用に環境変数をバンドルする

環境変数の読み込み

Next.jsには.env.localから環境変数をprocess.envに読み込む組み込みサポートがあります。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

注: Next.jsは.env*ファイル内の複数行にわたる変数もサポートしています:

# .env.local

# 改行して記述可能
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# またはダブルクォート内に`\n`を使用
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

注: /srcフォルダを使用している場合、Next.jsは親フォルダからのみ.envファイルを読み込み、/srcフォルダからは読み込みません。 これにより、process.env.DB_HOST、process.env.DB_USER、process.env.DB_PASSがNode.js環境に自動的に読み込まれ、Route Handlersで使用できるようになります。

例えば:

export async function GET() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

他の変数の参照

Next.jsは.env*ファイル内で$を使用して他の変数を参照する場合（例: $VARIABLE）、自動的に変数を展開します。これにより他のシークレットを参照できます。例えば:

TWITTER_USER=nextjs
TWITTER_URL=https://twitter.com/$TWITTER_USER

上記の例では、process.env.TWITTER_URLはhttps://twitter.com/nextjsに設定されます。

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

ブラウザ向け環境変数のバンドル

NEXT_PUBLIC_がプレフィックスされていない環境変数はNode.js環境でのみ利用可能で、ブラウザ（クライアントは異なる環境で実行される）からはアクセスできません。

ブラウザで環境変数の値を利用可能にするために、Next.jsはビルド時に値をjsバンドルに「インライン化」し、process.env.[variable]へのすべての参照をハードコードされた値に置き換えることができます。これを行うには、変数にNEXT_PUBLIC_をプレフィックスするだけです。例えば:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

これにより、Next.jsはNode.js環境内のprocess.env.NEXT_PUBLIC_ANALYTICS_IDへのすべての参照を、next buildを実行した環境の値で置き換え、コード内のどこでも使用できるようになります。これはブラウザに送信されるJavaScriptにインライン化されます。

注: ビルド後、アプリはこれらの環境変数の変更に応答しなくなります。例えば、Herokuパイプラインを使用してある環境でビルドしたスラグを別の環境にプロモートする場合や、単一のDockerイメージを複数の環境にビルド・デプロイする場合、すべてのNEXT_PUBLIC_変数はビルド時に評価された値で固定されるため、プロジェクトのビルド時に適切に設定する必要があります。ランタイム環境値にアクセスする必要がある場合は、クライアントに提供する独自のAPIを設定する必要があります（オンデマンドまたは初期化時）。

import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID'は'NEXT_PUBLIC_'がプレフィックスされているためここで使用可能。
// ビルド時に`setupAnalyticsService('abcdefghijk')`に変換されます。
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

動的ルックアップはインライン化されないことに注意してください:

// 変数を使用しているため、これはインライン化されません
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// 変数を使用しているため、これはインライン化されません
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

ランタイム環境変数

Next.jsはビルド時とランタイムの両方の環境変数をサポートできます。

デフォルトでは、環境変数はサーバーでのみ利用可能です。ブラウザに環境変数を公開するには、NEXT_PUBLIC_をプレフィックスする必要があります。ただし、これらの公開環境変数はnext build中にJavaScriptバンドルにインライン化されます。

ランタイム環境変数を読み取るには、getServerSidePropsを使用するか、App Routerへの段階的移行をお勧めします。App Routerでは、動的レンダリング中にサーバー上で安全に環境変数を読み取ることができます。これにより、異なる値を持つ複数の環境を通じてプロモート可能な単一のDockerイメージを使用できます。

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies(), headers()などの動的関数も
  // 動的レンダリングを選択するため、
  // このenv変数はランタイムで評価されます
  const value = process.env.MY_VALUE
  // ...
}

豆知識:

• register関数を使用してサーバー起動時にコードを実行できます。
• スタンドアロン出力モードでは動作しないため、runtimeConfigオプションの使用は推奨しません。代わりにApp Routerへの段階的移行をお勧めします。

デフォルト環境変数

一般的には.env.localファイル1つで十分です。しかし、development（next dev）またはproduction（next start）環境にデフォルトを追加したい場合があります。

Next.jsでは、.env（すべての環境）、.env.development（開発環境）、.env.production（本番環境）にデフォルトを設定できます。

.env.localは常に設定されたデフォルトを上書きします。

豆知識: .env、.env.development、.env.productionファイルはデフォルトを定義するためリポジトリに含めるべきです。.env*.localは.gitignoreに追加するべきで、これらのファイルは無視されることを意図しています。.env.localはシークレットを保存できる場所です。

Vercel上の環境変数

Next.jsアプリケーションをVercelにデプロイする場合、環境変数はプロジェクト設定で設定できます。

すべてのタイプの環境変数をそこで設定する必要があります。開発で使用される環境変数も含まれ、ローカルデバイスにダウンロードできます。

開発環境変数を設定している場合、以下のコマンドで.env.localにプルしてローカルマシンで使用できます:

vercel env pull .env.local

豆知識: VercelにNext.jsアプリケーションをデプロイする場合、.env*ファイル内の環境変数は、名前がNEXT_PUBLIC_でプレフィックスされていない限り、Edge Runtimeでは利用できません。代わりにプロジェクト設定で環境変数を管理することを強くお勧めします。そこからすべての環境変数が利用可能です。

テスト環境変数

developmentとproduction環境に加えて、3番目のオプションとしてtest環境が利用可能です。開発または本番環境のデフォルトを設定できるのと同じように、testing環境用に.env.testファイルでデフォルトを設定できます（ただし、これは前の2つほど一般的ではありません）。Next.jsはtesting環境では.env.developmentや.env.productionから環境変数を読み込みません。

これはjestやcypressなどのツールでテストを実行する際に、テスト目的でのみ特定の環境変数を設定する必要がある場合に便利です。NODE_ENVがtestに設定されている場合、テストデフォルト値が読み込まれますが、通常はテストツールがこれを処理するため手動で行う必要はありません。

test環境とdevelopmentおよびproduction環境の間には覚えておくべき小さな違いがあります: .env.localは読み込まれません。これはテストが誰にとっても同じ結果を生成することを期待しているためです。これにより、すべてのテスト実行は.env.local（デフォルトセットを上書きすることを意図）を無視することで、異なる実行間で同じenvデフォルトを使用します。

豆知識: デフォルト環境変数と同様に、.env.testファイルはリポジトリに含めるべきですが、.env.test.localは含めるべきではありません。.env*.localは.gitignoreで無視されることを意図しています。

ユニットテストを実行する際、@next/envパッケージのloadEnvConfig関数を活用することで、Next.jsと同じ方法で環境変数を読み込むことができます。

// 以下はJestのグローバルセットアップファイルなどでテストセットアップに使用できます
import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

環境変数の読み込み順序

環境変数は以下の場所で順番に検索され、変数が見つかった時点で停止します。

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の値が使用されます。

豆知識: NODE_ENVに許可される値はproduction、development、testです。

豆知識

• /srcディレクトリを使用している場合、.env.*ファイルはプロジェクトのルートに残す必要があります。
• 環境変数NODE_ENVが割り当てられていない場合、Next.jsはnext devコマンド実行時にはdevelopmentを、他のすべてのコマンドではproductionを自動的に割り当てます。

バージョン履歴