メインコンテンツまでスキップ

環境変数

例

Next.jsは環境変数をネイティブでサポートしており、以下のことが可能です：

環境変数のロード​

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
envConfig.ts
import { loadEnvConfig } from '@next/env'

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

その後、必要な場所で設定をインポートできます。例として：

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

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

これにより、Node.js環境でのprocess.env.NEXT_PUBLIC_ANALYTICS_IDのすべての参照が、next buildを実行した環境の値に置き換えられ、どこでもコード内で使用できるようになります。これはブラウザに送信される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バンドルにインライン化されます。

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

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

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

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

Good to know:

  • サーバーの起動時にコードを実行するには、register関数を使用できます。
  • runtimeConfigオプションの使用は推奨されません。これはスタンドアロン出力モードと連携しないためです。代わりにapp routerを段階的に採用することをお勧めします。

デフォルトの環境変数​

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

Next.jsはdevelopment（開発環境）、.env.production（本番環境）、および.env（すべての環境）でデフォルトを設定することを許可します。

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

Vercelでの環境変数​

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

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

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

Terminal
vercel env pull

Good to know: Next.jsアプリケーションをVercelにデプロイする際、NEXT_PUBLIC_で始まらない限り、.env*ファイル内の環境変数はEdge Runtimeでは利用できません。環境変数をプロジェクト設定で管理することを強くお勧めします。そこからすべての環境変数が利用できます。

テスト用の環境変数​

development環境とproduction環境に加えて、3番目のオプションがあります。それはtestです。開発または本番環境のデフォルトを設定するのと同じ方法で、.env.testファイルを使用してテスト環境にもデフォルトを設定できます（ただし、これは前述の2つより一般的ではありません）。Next.jsはテスト環境では.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)
}

環境変数のロード順序​

環境変数は、以下の場所で順に検索され、変数が見つかると停止します。

  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の値が使用されます。

Good to know: NODE_ENVに許可される値はproduction、development、そしてtestです。

知っておくと良いこと​

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

バージョン履歴​

Version変更点
v9.4.0.envとNEXT_PUBLIC_が導入されました。