Next.jsで環境変数を使用する方法

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

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

注意： デフォルトのcreate-next-appテンプレートは、すべての.envファイルが.gitignoreに追加されることを保証します。通常、これらのファイルをリポジトリにコミットしたいことはありません。

環境変数の読み込み

Next.jsには、.env*ファイルからprocess.envに環境変数を読み込むための組み込みサポートがあります。

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データ取得メソッドとAPIルートで使用できるようになります。

たとえば、getStaticPropsを使用する場合：

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

@next/envで環境変数を読み込む

ORMやテストランナーのルート設定ファイルなど、Next.jsランタイム外で環境変数を読み込む必要がある場合は、@next/envパッケージを使用できます。

このパッケージはNext.js内部で使用され、.env*ファイルから環境変数を読み込みます。

これを使用するには、パッケージをインストールし、loadEnvConfig関数を使用して環境変数を読み込みます。

npm install @next/env

import { loadEnvConfig } from '@next/env'
 
const projectDir = process.cwd()
loadEnvConfig(projectDir)

その後、必要な場所で設定をインポートできます。たとえば、以下のようになります。

import './envConfig.ts'
 
export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

他の変数を参照する

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

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

上記の例では、process.env.TWITTER_URLはhttps://x.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を採用することをお勧めします。

これにより、複数の環境で異なる値を持つ単一のDockerイメージを昇格させることができます。

補足：

• register関数を使用して、サーバー起動時にコードを実行できます。

テスト環境変数

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

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

test環境とdevelopmentおよびproductionの両方の間には、心に留めておく必要がある小さな違いがあります。.env.localは読み込まれません。これはテストがすべての人に対して同じ結果を生成することが期待されるためです。このようにして、すべてのテスト実行は、.env.local（デフォルトセットをオーバーライドするためのもの）を無視することで、異なる実行間で同じ環境デフォルトを使用します。

補足： デフォルト環境変数と同様に、.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を割り当てます。

バージョン履歴