コンテンツにスキップ
Pages Routerガイド環境変数

Next.js で環境変数を使用する方法

Next.js には環境変数に対する組み込みサポートがあり、以下のことが可能になります。

警告: デフォルトの create-next-app テンプレートは、すべての .env ファイルが .gitignore に追加されることを保証します。これらのファイルをリポジトリにコミットすることは、ほとんどありません。

環境変数の読み込み

Next.js には、.env* ファイルから process.env への環境変数の読み込みをサポートする組み込み機能があります。

.env
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 ルートで使用できるようになります。

たとえば、getStaticProps を使用する場合

pages/index.js
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/env を使用した環境変数の読み込み

ORM やテストランナーのルート設定ファイルなど、Next.js の実行時以外の環境で環境変数を読み込む必要がある場合は、@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 に設定されます。

注意: 実際の値に $ を含む変数を使用する必要がある場合は、エスケープする必要があります (例: \$)。

ブラウザ向け環境変数のバンドル

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 を設定する必要があります (オンデマンドまたは初期化中)。

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

実行時環境変数を読み取るには、getServerSideProps を使用するか、App Router を段階的に採用することをお勧めします。

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

知っておくと良いこと

  • register 関数を使用して、サーバー起動時にコードを実行できます。

テスト環境変数

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 です。

Good to know

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

バージョン履歴

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