環境変数

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' 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` オプションはスタンドアロン出力モードでは機能しないため、使用することはお勧めしません。代わりに、この機能が必要な場合はApp Routerを段階的に採用することをお勧めします。

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` に設定されている場合、テストのデフォルト値が読み込まれますが、テストツールが自動的に処理してくれるため、通常は手動で行う必要はありません。

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

ご存知でしたか: デフォルト環境変数と同様に、`.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` を割り当てます。

バージョン履歴