🚀

【Next.js和訳】Basic Features/Environment Variables

5 min read

この記事について

株式会社 UnReact はプロジェクトの一環としてNext.js ドキュメントの和訳を行っています。

この記事は、Basic Features/Environment Variablesの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

環境変数

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

Next.js には、環境変数のサポートが組み込まれており、次のようなことが可能です。

環境変数の読み込み

Next.js には、.env.localからprocess.env への環境変数の読み込みがサポートされています。

.env.localの例です。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

これにより、process.env.DB_HOSTprocess.env.DB_USERprocess.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.js はビルド時にprocess.env.*を正しい値に置き換えています。つまり、process.envは標準の JavaScript オブジェクトではないため、オブジェクトのデストラクションを使用することはできません。環境変数は、例えばprocess.env.NEXT_PUBLIC_PUBLISHABLE_KEYのように参照する必要があり、const { NEXT_PUBLIC_PUBLISHABLE_KEY } = process.env.NEXT_PUBLIC_PUBLISHABLE_KEYではありません。

注意
Next.js は、.env*ファイルの中で自動的に変数($VAR)を展開します。これにより、次のように他のシークレットを参照することができます。

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

実際の値に$が含まれている変数を使おうとしている場合、次のようにエスケープする必要があります: \$

例えば、以下のようになります。

# .env
A=abc

# becomes "preabc"
WRONG=pre$A

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

環境変数のブラウザへの公開

デフォルトでは、.env.localで読み込まれたすべての環境変数は、Node.js の環境でのみ利用可能であり、ブラウザには公開されません。

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

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

これにより、process.env.NEXT_PUBLIC_ANALYTICS_IDが Node.js の環境に自動的にロードされ、コード内の任意の場所で使用できるようになります。この値は、NEXT_PUBLIC_という接頭辞が付いているため、ブラウザに送信される JavaScript にインライン化されます。このインライン化はビルド時に行われるため、プロジェクトのビルド時にさまざまなNEXT_PUBLIC_環境を設定する必要があります。

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

// NEXT_PUBLIC_ANALYTICS_IDは、NEXT_PUBLIC_の前に付いているので、ここで使用できます。
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

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

export default HomePage

デフォルトの環境変数

一般的には、.env.localファイルは 1 つしか必要ありません。しかし、devlopment(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にデプロイする際、プロジェクト設定で環境変数を設定することができます。

すべての種類の環境変数をここで設定する必要があります。開発用の環境変数であっても、その後にローカルデバイスにダウンロードすることができます。

開発用の環境変数を設定した場合、以下のコマンドで.env.localにプルしてローカルマシンで使用することができます。

vercel env pull .env.local

Vercel CLI を使用してデプロイする場合は、アップロードしてはいけないファイルを含む .vercelignore を追加してください。通常、これらのファイルは .gitignore に含まれるファイルと同じです。

テスト環境変数

developmentproductionとは別に、3 つ目の選択肢としてtestがあります。開発環境や本番環境のデフォルト値を設定するのと同じように、テスト環境用の.env.testファイルでも同じことができます(ただし、これは前の 2 つの環境ほど一般的ではありません)。

このファイルは、テスト用に特定の環境変数を設定する必要がある場合に、 jestcypress などのツールを使ってテストを実行する際に便利です。NODE_ENVtestに設定されていると、テストのデフォルト値がロードされますが、通常はテストツールが対応してくれるので、手動で設定する必要はありません。

test環境と、developmentおよびproductionとの間には、わずかな違いがあります。テストでは誰もが同じ結果を得られることが期待されるため、.env.local はロードされません。この方法では、テストを実行するたびに .env.local を無視して同じ環境変数のデフォルトを使用します (これはデフォルトの設定を上書きするためのものです)。

注意
.env*.localのようなものは.gitignoreを通じて無視されるようになっているのに対して、デフォルト環境変数と同様、.env.test ファイルはリポジトリに含めるべきですが、.env.test.local は含めるべきではありません。

ユニットテストを実行する際には、@next/envパッケージのloadEnvConfig関数を利用することで、Next.js と同じように環境変数を読み込むことができます。

// 以下は、Jestのグローバルセットアップファイルなどで、テストのセットアップに使用することができます。
import { loadEnvConfig } from "@next/env"

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Discussion

ログインするとコメントできます