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

注意: 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を使用した環境変数の読み込み

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

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

import { connection } from 'next/server'
 
export default async function Component() {
  await connection()
  // cookies、headers、その他の動的APIも
  // 動的レンダリングに参加するため、
  // この環境変数はランタイムで評価されます
  const value = process.env.MY_VALUE
  // ...
}

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

補足：

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

テスト環境変数

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*.localは.gitignoreを通じて無視されることを意図しているため、.env.test.localは含めるべきではありません。

単体テストを実行する際、@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を割り当てます。

バージョン履歴