環境変数
例
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環境に自動的に読み込まれ、Route Handlersで使用できるようになります。
例えば：
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やテストランナーのroot設定ファイルで環境変数を読み込む必要がある場合、@next/envパッケージを使用できます。
このパッケージは、Next.jsが.env*ファイルから環境変数を読み込むために内部で使用しています。
使用するには、パッケージをインストールし、loadEnvConfig関数を使用して環境変数を読み込みます：
npm install @next/env
- TypeScript
- JavaScript
import { loadEnvConfig } from '@next/env'
const projectDir = process.cwd()
loadEnvConfig(projectDir)
import { loadEnvConfig } from '@next/env'
const projectDir = process.cwd()
loadEnvConfig(projectDir)
その後、必要な場所で設定をインポートできます。例えば：
- TypeScript
- JavaScript
import './envConfig.ts'
export default defineConfig({
dbCredentials: {
connectionString: process.env.DATABASE_URL!,
},
})
import './envConfig.js'
export default defineConfig({
dbCredentials: {
connectionString: process.env.DATABASE_URL,
},
})
他の変数の参照
Next.jsは、.env*ファイル内で他の変数を参照するために$を使用する変数を自動的に展開します。これにより、他のシークレットを参照できます。例えば：
TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER
上記の例では、process.env.TWITTER_URLはhttps://x.com/nextjsに設定されます。
Good to know: 実際の値に
$を含む変数を使用する必要がある場合は、\$でエスケープする必要があります。
ブラウザ用に環境変数をバンドルする
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パイプラインを使用して1つの環境でビルドされたスラグを別の環境に昇格させる場合や、単一のDockerイメージを複数の環境にデプロイする場合、すべての
NEXT_PUBLIC_変数はビルド時に評価された値で固定されるため、プロジェクトがビルドされるときにこれらの値を適切に設定する必要があります。ランタイム環境の値にアクセスする必要がある場合は、クライアントに提供する独自のAPIを設定する必要があります（オンデマンドまたは初期化時に）。
import setupAnalyticsService from '../lib/my-analytics-service'
// 'NEXT_PUBLIC_ANALYTICS_ID'は'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バンドルにインライン化されます。
動的レンダリング中にサーバー上で環境変数を安全に読み取ることができます：
- TypeScript
- 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
// ...
}
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イメージを使用できます。
Good to know:
register関数を使用してサーバーの起動時にコードを実行できます。runtimeConfigオプションの使用は推奨しません。これはスタンドアロン出力モードでは機能しないためです。この機能が必要な場合は、App Routerを段階的に採用することをお勧めします。
Vercelでの環境変数
Next.jsアプリケーションをVercelにデプロイする際、環境変数はプロジェクト設定で設定できます。
すべての種類の環境変数はそこで設定する必要があります。開発で使用される環境変数でさえも、後でローカルデバイスにダウンロードできます。
開発環境変数を設定した場合、次のコマンドを使用してローカルマシンで使用するために.env.localに取り込むことができます：
vercel env pull
Good to know: 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（デフォルトセットを上書きすることを意図している）を無視することで、異なる実行間で同じ環境デフォルトを使用します。
Good to know: デフォルト環境変数と同様に、
.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の値が使用されます。
Good to know:
NODE_ENVの許可される値はproduction、development、およびtestです。
Good to know
/srcディレクトリを使用している場合、.env.*ファイルはプロジェクトのrootに残すべきです。- 環境変数
NODE_ENVが未割り当ての場合、Next.jsはnext devコマンドを実行するときに自動的にdevelopmentを割り当て、他のすべてのコマンドにはproductionを割り当てます。
バージョン履歴
| バージョン | 変更点 |
|---|---|
v9.4.0 | .envとNEXT_PUBLIC_のサポートが導入されました。 |