環境変数

例

環境変数

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

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

環境変数のロード

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

.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環境にロードされ、Route Handlersで使用できるようになります。

例：

app/api/route.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やテストランナー用のroot設定ファイルなど）、@next/envパッケージを使用できます。

このパッケージは、Next.jsが.env*ファイルから環境変数をロードするために内部で使用しています。

使用するには、このパッケージをインストールし、loadEnvConfig関数を使って環境変数をロードします：

npm install @next/env

TypeScript
JavaScript

envConfig.ts
import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

envConfig.js
import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

必要な場所で設定をインポートできます。例えば：

TypeScript
JavaScript

orm.config.ts
import './envConfig.ts'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

orm.config.js
import './envConfig.js'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
})

他の変数を参照する

Next.jsは、.env*ファイル内で他の変数を参照するための$を使用した変数（例： $VARIABLE）を自動的に展開します。これにより、他の秘密情報を参照できます。例として：

.env

TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

上記の例では、process.env.TWITTER_URLはhttps://x.com/nextjsに設定されます。

Good to know: 実際の値に$を使用する必要がある場合、エスケープする必要があります（例： \$）。

ブラウザ用に環境変数をバンドルする

非NEXT_PUBLIC_環境変数はNode.js環境でのみ使用可能であり、ブラウザにはアクセスされません（クライアントは別の環境で実行されます）。

環境変数の値をブラウザで利用可能にするために、Next.jsはビルド時に値をjsバンドルに"インライン"し、すべてのprocess.env.[variable]への参照をハードコードされた値に置き換えることができます。それを行うためには、変数にNEXT_PUBLIC_をプレフィックスするだけです。例えば：

Terminal

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

これにより、Next.jsはNode.js環境内のすべてのprocess.env.NEXT_PUBLIC_ANALYTICS_IDへの参照をビルドを実行する環境の値に置き換え、コード内のどこでも使用できるようにします。これは、ブラウザに送信される任意のJavaScriptにインライン化されます。

注意: ビルド後、これらの環境変数に対する変更にアプリは反応しなくなります。例えば、ある環境でビルドされたスラッグを別の環境にプロモートするHerokuパイプラインを使用する場合や、1つのDockerイメージを複数の環境にビルドおよびデプロイする場合、すべてのNEXT_PUBLIC_変数はビルド時に評価された値で固定されるため、プロジェクトがビルドされるときにこれらの値を適切に設定する必要があります。ランタイムの環境値にアクセスする必要がある場合は、自分のAPIを設定してクライアントに提供する必要があります（要求ごとまたは初期化時に）。

pages/index.js
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バンドルにインラインされます。

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

TypeScript
JavaScript

app/page.ts
import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies, headers, and Dynamic API
  // は動的レンダリングに選択されるため、
  // このenv変数はランタイムで評価されます
  const value = process.env.MY_VALUE
  // ...
}

app/page.js
import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies, headers, and Dynamic API
  // は動的レンダリングに選択されるため、
  // このenv変数はランタイムで評価されます
  const value = process.env.MY_VALUE
  // ...
}

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

Good to know:

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

デフォルト環境変数

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

Next.jsでは、.env（すべての環境）、.env.development（開発環境）、および.env.production（本番環境）でデフォルトの設定が可能です。

Good to know: .env、.env.development、および.env.productionファイルは、デフォルトを定義するためリポジトリに含める必要があります。すべての.envファイルは、デフォルトで.gitignoreに除外されており、これらの値をリポジトリにコミットするオプションがあります。

Vercelでの環境変数

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

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

開発環境変数を設定した場合、次のコマンドを使用してローカルマシンで使用するために.env.localにプルすることができます：

Terminal

vercel env pull

Good to know: 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（デフォルトセットを上書きすることを目的としたもの）を無視することにより、異なる実行間で同じ環境のデフォルトが使用されます。

Good to know: デフォルト環境変数と同様に、.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)
}

環境変数のロード順序

環境変数は次の場所で順番に参照され、変数が見つかった時点で停止します。

process.env
.env.$(NODE_ENV).local
.env.local（NODE_ENVがtestの場合はチェックされません）
.env.$(NODE_ENV)
.env

たとえば、NODE_ENVがdevelopmentで、.env.development.localと.envの両方に変数を定義している場合、.env.development.localの値が使用されます。

Good to know: NODE_ENVの許可される値はproduction、development、testです。

Good to know

/srcディレクトリを使用する場合、.env.*ファイルはプロジェクトのルートに残す必要があります。
環境変数NODE_ENVが未割り当ての場合、Next.jsはnext devコマンドを実行する際に自動的にdevelopmentを割り当て、それ以外のすべてのコマンドに対してproductionを割り当てます。

バージョン履歴

バージョン	変更点
`v9.4.0`	`.env`および`NEXT_PUBLIC_`のサポートが導入されました。

環境変数のロード​

@next/envで環境変数をロードする​

他の変数を参照する​

ブラウザ用に環境変数をバンドルする​

ランタイム環境変数​

デフォルト環境変数​

Vercelでの環境変数​

テスト環境変数​

環境変数のロード順序​

Good to know​

バージョン履歴​