環境変数

このドキュメントは、Next.jsバージョン9.4以上を対象としています。古いバージョンのNext.jsを使用している場合は、アップグレードするか、next.config.jsの環境変数を参照してください。

例

• 環境変数

Next.js には、環境変数のビルトインサポートがあり、次のことが可能です:

• .env.local を使用して環境変数をロードする
• NEXT_PUBLIC_ prefix を用いてブラウザに環境変数を公開する

環境変数のロード

Next.js には、環境変数を .env.local ファイルから process.env にロードするためのビルトインサポートがあります。

.env.localファイルの例:

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

この例では、Node.js 環境の環境変数として process.env.DB_HOST 、process.env.DB_USER、process.env.DB_PASSが自動的にロードされます。環境変数は 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,
  })
  // ...
}

Note: In order to keep server-only secrets safe, Next.js replaces process.env.* with the correct values at build time. This means that process.env is not a standard JavaScript object, so you’re not able to use object destructuring. Environment variables must be referenced as e.g. process.env.PUBLISHABLE_KEY, not const { PUBLISHABLE_KEY } = process.env.

Note: Next.js will automatically expand variables ($VAR) inside of your .env* files. This allows you to reference other secrets, like so:

# .env
HOSTNAME=localhost
PORT=8080
HOST=http://$HOSTNAME:$PORT

If you are trying to use a variable with a $ in the actual value, it needs to be escaped like so: \$.

For example:

# .env
A=abc

# becomes "preabc"
WRONG=pre$A

# becomes "pre$A"
CORRECT=pre\$A

Note: If you are using a /src folder, please note that Next.js will load the .env files only from the parent folder and not from the /src folder.

ブラウザに環境変数を公開する

デフォルトでは、.env.localからロードされた環境変数は、Node.js 環境でのみ使用できます。つまり、ブラウザには公開されません。

変数をブラウザに公開するには、変数の前に NEXT_PUBLIC_ を付ける必要があります。例えば:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

こうすることで、process.env.NEXT_PUBLIC_ANALYTICS_IDが Node.js 環境に自動で読み込まれ、コードの任意の場所で使用できるようになります。NEXT_PUBLIC_を付けることで、ブラウザへ送信される JavaScript に値がインライン化されます。This inlining occurs at build time, so your various NEXT_PUBLIC_ envs need to be set when the project is built.

// pages/index.js
import setupAnalyticsService from '../lib/my-analytics-service'

// NEXT_PUBLIC_ を付けることで、 NEXT_PUBLIC_ANALYTICS_ID は、この場所で使用可能になります
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

デフォルトの環境変数

通常、必要なのは .env.local ファイルだけです。しかし、development (next dev) や production (next start) 環境で、デフォルト値を追加したい場合があります。

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

.env.local は常にデフォルト値を上書きします。

備考: .env、.env.development、.env.productionファイルは、デフォルト値を定義する場合にはリポジトリに含めるべきです。無視されることが意図されている.env*.localファイルは .gitignore に追加するべきです。.env.localファイルはシークレット値を保存できる場所です。

Vercelの環境変数

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

Development Environment Variables)を設定している場合、それらをローカルマシンで使用するには、次のコマンドで .env.local にプルできます:

vercel env pull .env.local

When using the Vercel CLI to deploy make sure you add a .vercelignore that includes files that should not be uploaded, generally these are the same files included in .gitignore.

テスト環境変数

development環境と production 環境とは別に、3 番目のオプションとして test 環境を利用できます。開発環境や本番環境でデフォルト値を設定できるのと同じ方法で、テスト環境の .env.test ファイルでも同じことができます(ただし、前の 2 つほど一般的ではありません)。

これは、テスト目的のために特定の環境変数を設定する必要がある jest や cypress などのツールを使用してテストを実行する場合に便利です。NODE_ENVに test が設定されている場合にテストのデフォルト値が読み込まれますが、通常はテストツールが自動で読み込むため、手動で設定する必要はありません。

test環境と、development``production環境の間には覚えておくべき小さな違いがあります。テストはすべての人に同じ結果をもたらすことが期待されるため、テスト環境では .env.local はロードされません。(デフォルト値のセットを上書きすることを目的としている).env.localを無視することで、すべてのテスト実行は異なる実行においても同じデフォルト値が使用されることになります。

備考: デフォルトの環境変数と同様に、.env.testファイルはリポジトリに含めるべきですが、.env.test.localは含めないでください。.env*.localは .gitignore によって無視されることが意図されています。

While running unit tests you can make sure to load your environment variables the same way Next.js does by leveraging the loadEnvConfig function from the @next/env package.

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

Depending on the environment (as set by NODE_ENV), Environment Variables are loaded from the following sources in top-to-bottom order. In all environments, the existing env is not overridden by following sources:

NODE_ENV=production

1. .env.production.local
2. .env.local
3. .env.production
4. .env

NODE_ENV=development

1. .env.development.local
2. .env.local
3. .env.development
4. .env

NODE_ENV=test

1. .env.test.local
2. .env.test
3. .env

Note: .env.local is not loaded when NODE_ENV=test.