コンテンツにスキップ
App 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

注意: Next.js は .env* ファイル内の複数行変数もサポートしています。

# .env
 
# you can write with line breaks
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"
 
# or with `\n` inside double quotes
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 を使用した環境変数の読み込み

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* ファイル内で $ を使用して他の変数を参照する変数を自動的に展開します。これにより、他のシークレットを参照できます。たとえば、次のようになります。

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

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

app/page.ts
import { connection } from 'next/server'
 
export default async function Component() {
  await connection()
  // cookies, headers, and other Dynamic APIs
  // will also opt into dynamic rendering, meaning
  // this env variable is evaluated at runtime
  const value = process.env.MY_VALUE
  // ...
}

これにより、複数の環境を異なる値で昇格できる単一の 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_ のサポートが導入されました。