環境変数

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
 
# you can write with line breaks
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"
 
# or with `\n` inside double quotes
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 Handlerでそれらを使用できるようになります。

例

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`による環境変数の読み込み

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バンドルにインライン化されます。

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

import { connection } from 'next/server'
 
export default async function Component() {
  await connection()
  // cookies, headers, and other Dynamic APIs
  // will also opt into dynamic rendering, meaning
  // this env variable is evaluated at runtime
  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と同じ方法で環境変数を読み込ませることができます。

// 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` を割り当てます。

バージョン履歴