Next.jsの環境変数をわかりやすく解説

Next.jsの環境変数

Next.jsの環境変数：.envとNEXT_PUBLIC_ | We.Inc

Next.jsが.envファイルを読み込む仕組みと順序、NEXT_PUBLIC_がビルド時に実際に行うこと、実行時に値を読む方法。.envを貼り付けると、ブラウザーに届く変数がわかります。

Next.jsはプロジェクトのルートにある.envファイルをprocess.envに読み込みます。変数はデフォルトでサーバー専用です。名前の先頭にNEXT_PUBLIC_を付けると、Next.jsはnext buildの際にその値をブラウザー用のJavaScriptにコピーします。そのため値は公開され、再ビルドするまで固定されます。このプレフィックスの付いた変数にシークレットを入れてはいけません。

読み込み順序：最初に変数を定義したファイルが優先される

順序
読み込み元
補足

シェルやホストですでに設定された値が常に優先される

.env.$(NODE_ENV).local
例：.env.development.local

.env.local
NODE_ENVがtestのときは読み飛ばされる

.env.$(NODE_ENV)
例：.env.production

.env
すべての環境で共通のデフォルト値

下に.envファイルの内容を貼り付けてください。チェッカーが各変数を「サーバー専用」と「ブラウザーに送信」に分類し、シークレットのように見える公開変数の名前を警告します。処理はすべてこのページ上で行われ、貼り付けた内容がアップロードされることはありません。

.envの行をボックスに貼り付けるか、サンプルを編集します。
表を確認します。各変数に「サーバー専用」か「ブラウザーに送信」の印が付きます。
KEY、SECRET、TOKENを含むNEXT_PUBLIC_の名前など、警告があれば対処します。
NEXT_PUBLIC_の値を変更したら再ビルドします。古い値がバンドルに埋め込まれているためです。

コードがsrcフォルダーにある場合でも、.envファイルはプロジェクトのルートに置きましょう。Next.jsはsrcの中は探しません。
チームが望むなら、安全なデフォルト値を入れた.envと.env.testはコミットして構いません。ただし.env*.localファイルは決してコミットしないでください。
公開変数は完全な名前をそのまま書いて読み取りましょう。process.env[name]や分割代入したprocess.envは、ビルド時に置き換えられません。
ステージングと本番で1つのDockerイメージを使いたい場合は、動的レンダリング中にサーバー変数を読み取り、ブラウザーが必要とするものはpropsとして渡しましょう。
Next.jsの外にあるORMの設定、スクリプト、テストのセットアップで同じファイルを読み込むには、@next/envのloadEnvConfigを使います。

よくある質問

ブラウザーで環境変数がundefinedになるのはなぜですか？

NEXT_PUBLIC_プレフィックスがない変数はサーバーにしか存在せず、クライアントのコードではNext.jsが空文字列に置き換えます。公開しても安全な値の場合に限ってプレフィックスを付け、もう一度ビルドしてください。

ホスティング先でNEXT_PUBLIC_の値を変えたのに何も変わりません。なぜですか？

公開変数の値はnext buildの実行時にインライン化されます。デプロイ済みのバンドルは、新しい値で再ビルドするまで古い値のままです。

テストで.env.localは使えますか？

使えません。NODE_ENVがtestのとき、Next.jsは.env.localを読み飛ばすため、どのテスト実行でも同じ値になります。テスト用のデフォルト値は.env.testに、個人用の上書きは.env.test.localに書きましょう。

変数から別の変数を参照できますか？

できます。値の中に$OTHER_NAMEと書くと、Next.jsが展開します。ドル記号をそのまま使いたい場合は\$とエスケープします。

NODE_ENVには何が設定されますか？

自分で設定しない場合、next devではdevelopment、その他のコマンドではproductionが使われます。使える値はproduction、development、testです。

NEXT_PUBLIC_が実際に行うこと

このプレフィックスはバンドラーへの指示です。next buildの際、コード内のprocess.env.NEXT_PUBLIC_SOMETHINGという記述はすべて、ビルドを実行した環境の値に置き換えられ、そのテキストは誰でもダウンロードできるJavaScriptファイルに含まれます。
これには2つの帰結があります。1つ目に、ファイル名がどうであれ、公開変数は決してシークレットになりません。2つ目に、値は固定されます。ステージングのビルドを本番に昇格させると、ステージングの値もそのまま持ち込まれます。

実行時に値を読み取る

サーバーのコードは、公開かどうかに関係なくどの変数でも読み取れます。値をビルド時ではなくリクエストごとに確実に読み取るには、ページを動的にレンダリングします。たとえば、process.envを読む前にnext/serverのconnection()をawaitします。
ブラウザーはサーバー変数をまったく読み取れません。Client Componentで実行時の値が必要なら、自前のRoute Handlerから取得するか、Server Componentからpropsとして渡しましょう。

漏洩を防ぐ

APIキーを読み取るヘルパーが、誤ってClient Componentにインポートされることがあります。そうしたファイルの先頭にimport 'server-only'を追加しておけば、クライアントのファイルが取り込んだときにビルドが失敗します。

コードで変数を読み取る

Route Handler内のサーバー専用の値

DB_URLにはプレフィックスがないため、サーバーにのみ存在します。Route HandlersとServer Componentsからは自由に読み取れます。

Client Component内の公開値

完全な名前をそのまま書く必要があります。ビルド時にNext.jsが値に置き換えるため、ブラウザーにはただの文字列が見えます。

リクエストごとに値を読み取る

connection()をawaitするとページが動的にレンダリングされるため、値はビルド時ではなく稼働中のサーバーから取得されます。

loadEnvConfigは同じ読み込み順序を適用するため、スクリプトやテストのセットアップをアプリと揃えられます。

.envチェッカー

.envの行を貼り付け

各変数を読み取れる場所

変数

利用できる場所

補足

サーバー専用

サーバーとブラウザー（ビルド時にインライン化）

変数の行ではありません

名前がシークレットのように見えます。NEXT_PUBLIC_が付いたものはすべての訪問者に見えます。

{v}を参照しています。Next.jsが展開します。

NODE_ENVに使えるのはproduction、development、testだけです。

変数はまだ見つかりません。

サーバー専用{n}個、ブラウザーに送信{v}個

無料で始める · クレジットカード不要

製品

AI ホームページ作成ツール：作りたいサイトを普段の言葉で伝えるだけで、数分で公開
ホワイトラベルプラットフォーム：自社ブランド、自社ドメイン、自社の利益で運営
エンタープライズ：SSO、個別の SLA、専任サポート
開発者向け API：自社の SaaS にサイト生成機能を組み込み

ご利用いただける方

制作会社・代理店向け：自社ブランドで再販
フリーランス向け：自分ブランドのビルダーを持つ
ホスティング事業者向け：サービスにビルダーを追加
SaaS プラットフォーム向け：API でサイト作成を組み込み
スタートアップ向け
金融サービス向け
医療・ヘルスケア向け

機能

リソース

会社情報

サイトマップを見る

Next.jsの環境変数をわかりやすく解説