環境変数

Next.jsは環境変数に対する組み込みサポートを提供しており、以下のことが可能です。

• `.env`を使用して環境変数をロードする
• `NEXT_PUBLIC_`をプレフィックスとして付けることで、ブラウザ用に環境変数をバンドルする

環境変数の読み込み

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は`next build`を実行する環境の値を使用して、Node.js環境内の`process.env.NEXT_PUBLIC_ANALYTICS_ID`へのすべての参照を置き換え、コードのどこにでも使用できます。ブラウザに送信されるJavaScriptにインライン化されます。

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

import setupAnalyticsService from '../lib/my-analytics-service'
 
// 'NEXT_PUBLIC_ANALYTICS_ID' can be used here as it's prefixed by 'NEXT_PUBLIC_'.
// It will be transformed at build time to `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
 
function HomePage() {
  return <h1>Hello World</h1>
}
 
export default HomePage

動的なルックアップはインライン化されません（例：

// This will NOT be inlined, because it uses a variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
 
// This will NOT be inlined, because it uses a variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

実行時環境変数

Next.js は、ビルド時と実行時の両方の環境変数をサポートできます。

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

実行時環境変数を読み取るには、getServerSideProps を使用するか、App Router を段階的に採用することをお勧めします。

これにより、異なる値を持つ複数の環境でプロモーションできる単一の Docker イメージを使用できます。

知っておくと良いこと

• register 関数 を使用して、サーバーの起動時にコードを実行できます。
• runtimeConfig オプションの使用はお勧めしません。これはスタンドアロン出力モードでは機能しないためです。段階的に採用することをお勧めします。

デフォルトの環境変数

通常、.env* ファイルのみが必要です。ただし、開発環境（next dev）または本番環境（next start）のデフォルトを追加したい場合があります。

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

覚えておくべき点：.env、.env.development、.env.production ファイルは、デフォルトを定義するため、リポジトリに含める必要があります。すべての .env ファイルはデフォルトで .gitignore に除外されており、これらの値をリポジトリにコミットすることを選択できます。

Vercel での環境変数

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

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

開発環境変数 を設定した場合、次のコマンドを使用して、ローカルマシンでの使用のために .env.local にそれらを取り込むことができます。

vercel env pull

覚えておくべき点：Next.js アプリケーションを Vercel にデプロイする場合、.env* ファイル内の環境変数は、名前の先頭に NEXT_PUBLIC_ が付いている場合を除き、Edge Runtime で使用可能になりません。プロジェクト設定 で環境変数を管理することを強くお勧めします。すべての環境変数がそこで使用可能になります。

テスト環境変数

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

これは、テスト専用の環境変数を設定する必要がある jest や cypress などのツールでテストを実行する場合に役立ちます。NODE_ENV が test に設定されている場合、テストのデフォルト値がロードされますが、通常はテストツールが自動的に処理するため、手動でこれを行う必要はありません。

test 環境と開発環境と本番環境の間には、覚えておく必要がある小さな違いがあります。テストはすべてのユーザーに対して同じ結果を生成することを期待するため、.env.local はロードされません。これにより、.env.local（デフォルト設定を上書きすることを目的とする）を無視することで、すべてのテスト実行で同じ env デフォルトが異なる実行間で使用されます。

覚えておくべき点：デフォルトの環境変数と同様に、.env.test ファイルはリポジトリに含める必要がありますが、.env.test.local は含めるべきではありません。.env*.local は .gitignore を介して無視されることを目的としているためです。

単体テストの実行中は、@next/env パッケージの loadEnvConfig 関数を利用して、Next.js と同じ方法で環境変数をロードできます。

// The below can be used in a Jest global setup file or similar for your testing set-up
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 を割り当てます。

バージョン履歴