環境変数

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

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

警告: デフォルトの create-next-app テンプレートでは、すべての .env ファイルが .gitignore に追加されていることを確認しています。これらのファイルをリポジトリにコミットすることはほぼ避けるべきです。

環境変数の読み込み

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

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

# .env
 
# 改行を入れて書くことができます
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環境に自動的に読み込まれ、ルートハンドラで使用できます。

例：

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/envで環境変数を読み込む

Next.js実行時以外（ORMやテストランナーのルート設定ファイルなど）で環境変数を読み込む必要がある場合、@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_' プレフィックスにより、ここで使用できます。
// ビルド時に `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バンドルにインライン展開されます。

動的レンダリング中にサーバー上で安全に環境変数を読み取ることができます：

import { connection } from 'next/server'
 
export default async function Component() {
  await connection()
  // cookie、ヘッダー、その他のDynamic APIは
  // 動的レンダリングにオプトインします。つまり、
  // この環境変数はランタイムに評価されます
  const value = process.env.MY_VALUE
  // ...
}

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

補足：

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

Vercel上の環境変数

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

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

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

vercel env pull

補足: Next.jsアプリケーションをVercelにデプロイする場合、.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.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を割り当てます。

バージョン履歴