Environment Variables

Next.js は、組み込みの environment variables サポートを備えており、以下のことが可能です：

• .env.localを使用して environment variables をロードします
• NEXT_PUBLIC_のプレフィックスを付けて、ブラウザ用の environment variables をバンドルします

Loading Environment Variables

Next.js は、.env.localからprocess.envに loading environment variables ための組み込みサポートを持っています。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

これにより、process.env.DB_HOST、process.env.DB_USER、process.env.DB_PASSは自動的に Node.js の環境に読み込まれます。これにより、Next.js のデータ取得方法やAPI routesでそれらを使用することができます。

例えば、getStaticPropsを使用すると：

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

他の変数を参照する

Next.js は、$ を使って他の変数を参照する変数を自動的に展開します。たとえば、.env* ファイル内の $VARIABLE。これにより、他のシークレットを参照することができます。例えば：

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

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

Good to know: 実際の value に $ が必要な variable を使用する場合、例えば \$ のようにエスケープする必要があります。

Bundling Environment Variables for the Browser

非 NEXT_PUBLIC_ environment variables は、 Node.js 環境でのみ利用可能であり、それらはブラウザ ( client は別の環境で動作します) にはアクセスできません。

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

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

これは、process.env.NEXT_PUBLIC_ANALYTICS_IDへのすべての参照をnext buildを実行する環境からの value に置換するように Next.js に指示します。これにより、コードの任意の場所でそれを使用することができます。それは、ブラウザに送信される任意の JavaScript にインライン化されます。

注意: build 後、あなたの app はこれらの environment variables への変更には反応しなくなります。例えば、Heroku パイプラインを使用して一つの環境で build されたスラッグを別の環境にプロモートした場合、または build と deploy の一つの Docker の image を複数の環境に配置した場合、全ての NEXT_PUBLIC_ variables は、build 時に評価された value でフリーズされるので、プロジェクトが build される際にこれらの value は適切に設定する必要があります。もし、runtime の環境 value にアクセスする必要があるなら、それらを client に提供するための独自の 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

dynamic 検索はインライン化されません。例えば：

// 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);

Runtime Environment Variables

Next.js は、build 時間と runtime environment variables の両方をサポートすることができます。

default で、environment variables は server 上でのみ使用可能です。 environment variables をブラウザで利用するためには、それをNEXT_PUBLIC_にプレフィックスする必要があります。ただし、これらの公開 environment variables は、next build中に JavaScript バンドルにインライン化されます。

runtime environment variables を読むためには、getServerSidePropsを使うか、App Router の段階的な採用を推奨します。 App Router を使用すると、dynamic レンダリングの間に server で安全に environment variables を読むことができます。これにより、異なる値を持つ複数の環境でプロモーション可能な一つの Docker の image を使用することができます。

import { unstable_noStore as noStore } from "next/cache";

export default function Component() {
  noStore();
  // cookies(), headers(), and other dynamic functions
  // will also opt into dynamic rendering, making
  // this env variable is evaluated at runtime
  const value = process.env.MY_VALUE;
  // ...
}

Good to know:

• ご利用いただけます code を server の起動時に、register functionを使用して実行します。
• 私たちはruntimeConfigオプションの使用をお勧めしません。それはスタンドアロン出力モードとは互換性がありません。代わりに、App Router をincrementally adoptingすることをお勧めします。

Default Environment Variables

一般的には、一つの .env.local ファイルだけが必要です。しかし、時として development (next dev) や production (next start) 環境に対していくつかの default を追加したい場合もあります。

Next.js は、.env(すべての環境)、.env.development(development 環境)、および.env.production(production 環境)で default を設定することを可能にします。

.env.localは常に default の設定を上書きします。

Good to know: .env、.env.development、そして .env.production ファイルは default を定義するため、リポジトリに含めるべきです。.env*.local は .gitignore に追加すべきです、なぜならそれらのファイルは無視することを意図しているからです。.env.local は秘密情報を保存することができます。

Environment Variables on Vercel

あなたの Next.js アプリケーションを Vercel にデプロイする際、 Environment Variables は プロジェクトの Settings で設定 することができます。

すべての type の Environment Variables はそこに設定する必要があります。 Development で使用される Environment Variables でさえも - これは後であなたのローカルデバイスにダウンロード することができます。

あなたがDevelopment Environment Variables を設定した場合、以下のコマンドを使用して、それらを.env.localに取り込み、ローカルマシンで使用できます。

vercel env pull .env.local

Good to know: Vercel に対して Next.js アプリケーションをデプロイする際には、.env* ファイル内の environment variables が NEXT_PUBLIC_で始まっていない限り、 Edge Runtime で利用できるようにはなりません。我々は、全ての environment variables が利用可能な Project Settings で 貴方の environment variables を管理することを強く推奨いたします。

Test Environment Variables

developmentとproductionの環境以外に、3 つ目の選択肢が利用可能です：それはtestです。 development や production の環境で default を設定するのと同じように、testing環境用の .env.testファイルで同じことを行うことができます(ただし、このオプションは前述の 2 つほど一般的ではありません)。 Next.js はtesting環境で.env.developmentや.env.productionから environment variables を読み込みません。

この機能は、jestやcypressのようなツールでテストを実行する際に、テスト目的のためだけに特定の environment variables を設定する必要がある場合に便利です。 Test default の値は、NODE_ENVがtestに設定されている場合にロードされますが、通常はこれを手動で行う必要はありません。なぜなら、テストツールが代わりに処理してくれるからです。

test環境と、developmentおよびproductionには少し違いがあり、心に留めておく必要があります：テストは全員が同じ結果を出すことを期待するため、.env.localは読み込まれません。このように、すべての test 実行は、あなたの.env.local (これは default 設定を上書きすることを目的としています)を無視して、異なる実行間で同じ envdefault を使用します。

Good to know: Default Environment Variables と似ていますが、.env.testファイルはリポジトリに含まれるべきですが、.env.test.localは含まれるべきではありません。.env*.localは.gitignoreを通じて無視されることを意図しています。

ユニットテストを実行する際に、@next/envパッケージのloadEnvConfig関数を利用することで、Next.js が行うのと同じ方法で environment variables をロードすることを確認できます。

// 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);
};

Environment Variable Load Order

Environment variables は、以下の場所で順番に探され、 variable が見つかった時点で探索が停止します。

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の両方で variable を定義した場合、.env.development.localの value が使用されます。

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

Good to know

• あなたが/src ディレクトリを使用している場合、.env.* ファイルはプロジェクトの root に残すべきです。
• もし環境の variable であるNODE_ENVが未割り当てである場合、Next.js はnext devコマンドを実行するときに自動的にdevelopmentを割り当て、または他のすべてのコマンドに対してproductionを割り当てます。

Version History