環境変数

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

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

環境変数の読み込み

Next.jsは、`.env*`ファイルから`process.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環境に自動的にロードされ、ルートハンドラで使用できます。

例:

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

import { loadEnvConfig } from '@next/env'
 
const projectDir = process.cwd()
loadEnvConfig(projectDir)

その後、必要に応じて設定をインポートできます。例:

import './envConfig.ts'
 
export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

他の変数の参照

Next.jsは、`.env*`ファイル内で`$`を使用して他の変数を参照する変数（例:`$VARIABLE`）を自動的に展開します。これにより、他のシークレットを参照できます。例:

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

注記: アプリケーションがビルドされた後、これらの環境変数の変更には応答しなくなります。例えば、Herokuパイプラインを使用して、ある環境でビルドされたslugを別の環境に昇格させる場合、または単一のDockerイメージを複数の環境にビルドしてデプロイする場合、すべてのNEXT_PUBLIC_変数はビルド時に評価された値で固定されるため、プロジェクトのビルド時にこれらの値を適切に設定する必要があります。実行時の環境変数へのアクセスが必要な場合は、クライアントにそれらを提供する独自の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

動的なルックアップはインライン化されません。例えば

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

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

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

デフォルトの環境変数

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

Next.jsでは、.env（すべての環境）、.env.development（開発環境）、.env.production（本番環境）でデフォルト値を設定できます。

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

Vercelでの環境変数

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

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

開発環境変数を設定した場合、次のコマンドを使用して、ローカルマシンで使用する.env.localにそれらを取り込むことができます。

vercel env pull

知っておくと良い点: Next.jsアプリケーションをVercelにデプロイする場合、.env*ファイル内の環境変数は、名前がNEXT_PUBLIC_で始まる場合を除き、Edge Runtimeで使用できません。プロジェクト設定で環境変数を管理することを強くお勧めします。そこでは、すべての環境変数を使用できます。

テスト環境変数

開発環境と本番環境以外にも、3つ目のオプションとして「テスト」環境があります。開発環境や本番環境でデフォルト値を設定するのと同じように、テスト環境用の.env.testファイルでデフォルト値を設定できます（ただし、これは前述の2つほど一般的ではありません）。Next.jsは、テスト環境では.env.developmentまたは.env.productionから環境変数をロードしません。

これは、テスト専用に特定の環境変数を設定する必要があるjestやcypressなどのツールでテストを実行する場合に役立ちます。テストツールが自動的に処理するため、通常は手動で実行する必要はありませんが、NODE_ENVがtestに設定されている場合、テストのデフォルト値がロードされます。

テスト環境と開発環境、本番環境の間には、考慮すべき小さな違いがあります。テストはすべての人に同じ結果をもたらすことが期待されるため、.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です。

知っておくと良い点

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

バージョン履歴