環境変数
例
Next.jsには環境変数のサポートが組み込まれており、以下のことが可能です:
警告: デフォルトの
create-next-app
テンプレートでは、すべての.env
ファイルが.gitignore
に追加されていることを確認しています。これらのファイルをリポジトリにコミットすることはほぼ避けるべきです。
環境変数の読み込み
Next.jsには、.env*
ファイルから環境変数をprocess.env
に読み込むサポートが組み込まれています。
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword
注意: Next.jsは
.env*
ファイル内の複数行の変数もサポートしています:# .env # 改行を入れて書くことができます PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ... Kh9NV... ... -----END DSA PRIVATE KEY-----" # または、ダブルクォート内で`\n`を使用 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
で環境変数を読み込む
Next.js実行時以外(ORMやテストランナーのルート設定ファイルなど)で環境変数を読み込む必要がある場合、@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パイプラインを使用して、あるステージングから別のステージングに向けて構築されたイメージを昇格させる、または単一のDockerイメージを複数の環境にビルドしてデプロイする場合、すべての
NEXT_PUBLIC_
変数はビルド時に評価された値で固定されるため、これらの値はプロジェクトがビルドされるときに適切に設定される必要があります。実行時の環境変数にアクセスする必要がある場合、クライアントに提供するための独自のAPIをセットアップする必要があります(オンデマンドまたは初期化中)。
import setupAnalyticsService from '../lib/my-analytics-service'
// 'NEXT_PUBLIC_' プレフィックスにより、ここで使用できます。
// ビルド時に `setupAnalyticsService('abcdefghijk')` に変換されます。
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
function HomePage() {
return <h1>Hello World</h1>
}
export default HomePage
動的なルックアップはインライン展開されないことに注意してください:
// これはインライン展開されません。変数を使用しているためです
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
// これもインライン展開されません。変数を使用しているためです
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()
// cookie、ヘッダー、その他のDynamic APIは
// 動的レンダリングにオプトインします。つまり、
// この環境変数はランタイムに評価されます
const value = process.env.MY_VALUE
// ...
}
これにより、異なる値を持つ複数の環境間で昇格させることができる単一のDockerイメージを使用できます。
補足:
- サーバー起動時にコードを実行するには、
register
関数を使用できます。 runtimeConfig
オプションの使用はお勧めしません。これはスタンドアロン出力モードでは動作しないためです。代わりに、この機能が必要な場合は、App Routerを段階的に採用することをお勧めします。
Vercel上の環境変数
Next.jsアプリケーションをVercelにデプロイする場合、環境変数はプロジェクト設定で設定できます。
すべてのタイプの環境変数をそこで設定する必要があります。開発で使用される環境変数も同様に、後でローカルデバイスにダウンロードできます。
開発環境変数を設定している場合、以下のコマンドでローカルマシン用の.env.local
にそれらをプルできます:
vercel env pull
補足: Next.jsアプリケーションをVercelにデプロイする場合、
.env*
ファイル内の環境変数は、その名前がNEXT_PUBLIC_
接頭辞を持つ場合を除き、Edge Runtimeで利用できません。環境変数は、すべての環境変数が利用可能なプロジェクト設定で管理することを強くお勧めします。
テスト環境変数
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と同じ方法で環境変数を確実に読み込むことができます。
// 以下は、Jestのグローバルセットアップファイルまたはテスト設定用の同様のファイルで使用できます
import { loadEnvConfig } from '@next/env'
export default async () => {
const projectDir = process.cwd()
loadEnvConfig(projectDir)
}
環境変数の読み込み順序
環境変数は、変数が見つかるまで、以下の順序で探索されます。
process.env
.env.$(NODE_ENV).local
.env.local
(NODE_ENV
がtest
の場合はチェックされません).env.$(NODE_ENV)
.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
を割り当てます。
バージョン履歴
バージョン | 変更点 |
---|---|
v9.4.0 | .env とNEXT_PUBLIC_ のサポートが導入されました。 |