環境変数（.env）と公開範囲の基本 | 開発環境構築とNext.js（TypeScript）入門 | Next.jsによるWebアプリケーション開発概論

この節で学ぶこと

この節では、Next.js における環境変数の役割、.env ファイルの基本、そして「どこまで公開されるのか」という非常に大切な境界線を学びます。Next.js では環境変数を標準で読み込めますが、既定ではサーバー側でのみ利用可能で、ブラウザ側へ渡したい値だけを NEXT_PUBLIC_ 接頭辞付きで明示的に公開します。

初心者の段階では、ここを「設定の細かい話」と見てしまいがちです。けれど実際は逆で、環境変数は事故を防ぐための最前線です。

たとえば API キー、データベース接続情報、Webhook シークレットのような値を、うっかり画面側へ漏らさないために使います。

Next.js の公式文書でも、NEXT_PUBLIC_ が付かない値は private で、クライアントへ漏れないよう扱われると説明されています。

この節を読み終えたときの到達目標は、次の4つです。

.env が何のためのファイルか説明できること。
NEXT_PUBLIC_ が付く値と付かない値の違いを言えること。
.env の読み込み順序をざっくり理解すること。
「この値はサーバー専用にすべきか、ブラウザへ公開してよいか」を判断する感覚を持つことです。

Next.js 公式は環境変数の読み込み順序も明示しており、Node.js 公式は .env を key-value 形式のファイルとして定義しています。

環境変数とは何か

一言でいえば「コードの外に置く設定値」

環境変数とは、プログラムの中に直書きせず、実行環境側から渡す設定値です。Node.js の process.env は、その環境変数を格納するオブジェクトとして提供されています。Node.js 公式では process.env はユーザー環境を含むオブジェクトであると説明されています。

たとえば、次のような値は環境変数に向いています。

API キー
データベース URL
外部サービスのシークレット
開発環境と本番環境で変えたい URL
ポート番号やデバッグ設定

ここでの感覚はとても大事です。

「変わるかもしれない値」「公開すると危険な値」は、コード本体から分ける。これが環境変数の基本思想です。Next.js も Node.js も、この考え方を前提に環境変数を扱っています。

なぜコードに直接書かないのか

理由は主に3つあります。

秘密情報を守るため

API キーや接続文字列をソースコードへ直接書くと、Git 管理や誤公開で漏れやすくなります。Next.js では、公開してよい値だけを NEXT_PUBLIC_ で明示する仕組みがあります。

環境ごとの差し替えをしやすくするため

開発用と本番用で URL やキーを変えたいことはよくあります。Next.js には .env.development や .env.production のような使い分けがあります。

コードを汚さないため

設定値をコードから分離すると、アプリ本体の責務がはっきりします。これは設計としてもきれいです。

.envファイルとは何か

形式はシンプルな key-value

Node.js 公式では、.env ファイルはキーと値の組を書くファイルだと説明されています。各行は 変数名=値 の形です。Node.js は「正式な共通仕様があるわけではないが、自身の仕様を定義している」と案内しています。

たとえば、次のように書きます。

DATABASE_URL=postgres://user:password@localhost:5432/mydb
API_KEY=secret-key
NEXT_PUBLIC_SITE_NAME=My App

ここで見るべきポイントは2つです。

DATABASE_URL や API_KEY は秘密情報寄りです。一方、NEXT_PUBLIC_SITE_NAME はブラウザに見えても問題がない前提の値です。Next.js はこの接頭辞による公開範囲の区別を採用しています。

Next.js は `.env` を標準で読み込む

Next.js では .env ファイルの読み込みが標準機能です。Next.js 9.4 以降、.env ロードがデフォルトでサポートされるようになり、現在の環境変数ガイドでもその前提で説明されています。

つまり、初心者のうちは「dotenv を別途入れないといけないのでは」と心配しなくて大丈夫です。

Next.js の通常利用なら、まずは公式の環境変数機能を使えばよい、という理解で問題ありません。

Next.js における公開範囲の基本

既定ではサーバー専用

Next.js の self-hosting ガイドでは、既定では環境変数はサーバー側でのみ利用可能と説明されています。つまり、何も付けずに定義した値は、ブラウザでそのまま見える前提ではありません。

たとえば、次のような値はサーバー専用にしたい代表です。

DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_xxx
INTERNAL_API_TOKEN=xxx

この種の値は、ユーザーのブラウザへ送ってはいけない類いです。Next.js のドキュメントでも、NEXT_PUBLIC_ が付かない private な値はサーバー側にとどまる前提で説明されています。

ブラウザへ渡すには `NEXT_PUBLIC_` を付ける

Next.js 公式では、クライアントから参照したい環境変数には NEXT_PUBLIC_ を付ける必要があると明記されています。エラーページでも、クライアントでアクセスする環境変数は NEXT_PUBLIC_ を付けて「安全にインライン化してよい」と示さなければならないと説明されています。

たとえば次のようにします。

NEXT_PUBLIC_SITE_NAME=Prince Academy
NEXT_PUBLIC_API_BASE_URL=https://example.com

この値は画面側でも使えます。

反対に、NEXT_PUBLIC_ を付けるということは、公開されてもよいと自分で宣言しているのと同じです。ここ、静かに見えてかなり重要です。名前を変えただけで、責任範囲まで変わります。

サーバー側とクライアント側の違い

サーバー側で使う例

サーバー側では process.env から通常の環境変数を読み取れます。Node.js 公式は process.env を環境変数オブジェクトとして定義し、Next.js 公式は private な値をサーバー側で使う前提で説明しています。

const dbUrl = process.env.DATABASE_URL

if (!dbUrl) {
  throw new Error('DATABASE_URL が設定されていません')
}

このコードの感覚は大切です。

「あるはずの値がないなら、静かに進まない」。これは安全設計の入口です。Next.js の Missing Env Value 文書でも、必要な環境値が存在しないときに問題になることが説明されています。

クライアント側で使う例

クライアント側では、NEXT_PUBLIC_ が付いた値だけを使います。Next.js 公式は、クライアントでアクセスする環境変数には NEXT_PUBLIC_ が必要だと明示しています。

export default function Page() {
  return <h1>{process.env.NEXT_PUBLIC_SITE_NAME}</h1>
}

ここで SITE_NAME ではなく NEXT_PUBLIC_SITE_NAME であることが重要です。

もし process.env.API_KEY のような private 値をクライアント側で触ろうとすると、Next.js の文書では private 値はクライアントへ漏れないよう扱われ、特定の文脈では空文字に置き換えられると説明されています。

「公開してよい値」と「公開してはいけない値」の見分け方

公開してよい値

たとえば次のようなものです。

サイト名
公開用 API のベース URL
公開前提の計測 ID
フロントエンドだけで使う公開設定値

NEXT_PUBLIC_SITE_NAME=My Service
NEXT_PUBLIC_ANALYTICS_ID=abc-123

これらは、見られても重大な問題にならない設計の値です。とはいえ、外に見えてもよいかは毎回考える必要があります。Next.js の NEXT_PUBLIC_ は「便利な接頭辞」ではなく、公開の意思表示です。

公開してはいけない値

次のようなものは原則 private です。

シークレットキー
管理者 API トークン
データベース接続文字列
Webhook secret
内部システム用トークン

DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_xxx
WEBHOOK_SECRET=super-secret

これに NEXT_PUBLIC_ を付けてしまうのは、金庫の鍵に「玄関前に置いてあります」とラベルを貼るようなものです。Next.js の公開範囲ルールは、ここを機械的に切り分けるためにあります。

.envの読み込み順序

どのファイルが優先されるのか

Next.js 公式は、環境変数の読み込み順序を次のように示しています。上から順に探し、見つかった時点で止まります。

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 の方が使われます。これは Next.js 公式の Environment Variable Load Order に明記されています。

これをどう覚えるか

初心者向けには、こう覚えると十分です。

より具体的なものが強い
local が付くものはローカル個別設定寄り
最後の土台が .env 全部を丸暗記しなくてもよいです。

ただ、「同じキーを書いたときは上書き順がある」という認識は持っておくと、あとでかなり助かります。

`NODE_ENV` とファイルの使い分け

よく出てくるファイル名

Next.js の公式ガイドに基づくと、代表的には次のようなファイルを使い分けます。

.env
.env.local
.env.development
.env.development.local
.env.production
.env.production.local この構成を見ると、環境変数は1枚岩ではなく、共通設定・環境別設定・ローカル専用設定に分けられることが分かります。

たとえばチーム共通の開発設定は .env.development、自分のローカルだけで使う微調整は .env.development.local、という整理ができます。

process.envの基本

値は `process.env` から読む

Node.js では process.env が環境変数の窓口です。Next.js でも同じ入口を使います。Node.js 公式は process.env をオブジェクトとして説明しており、Windows では大文字小文字が区別されないという注意点も記載しています。

const apiBaseUrl = process.env.NEXT_PUBLIC_API_BASE_URL
const secret = process.env.INTERNAL_API_TOKEN

ここで大事なのは、読み方は同じでも公開範囲は同じではないことです。

process.env から読めるからといって、何でもブラウザへ出してよいわけではありません。Next.js はそこを NEXT_PUBLIC_ で区別しています。

存在チェックを書く癖をつける

初心者の段階ほど、次のような存在チェックは役に立ちます。

const apiKey = process.env.API_KEY

if (!apiKey) {
  throw new Error('API_KEY が設定されていません')
}

環境変数は「ある前提」でコードを書きたくなりますが、実際には未設定のこともあります。Next.js の Missing Env Value 文書も、必要な環境値が提供されていないときにエラーになる理由を説明しています。

Next.js には next.config.js / next.config.ts の env 設定もあります。公式では、この設定で定義した値はビルド時に process.env.customKey のように参照でき、JavaScript バンドルへ追加されると説明されています。また、process.env の分割代入は DefinePlugin の性質上うまく動かないと明記されています。

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  env: {
    customKey: 'my-value',
  },
}

export default nextConfig

ただ、初心者にとってはまず .env の理解を優先する方が自然です。

なぜなら .env の方が「環境ごとに差し替える」という発想に直結しやすいからです。Next.js の公式でも環境変数ガイドは .env を中心に説明しています。

よくあるミス

ミス1：秘密値に `NEXT_PUBLIC_` を付ける

これは最も避けたいミスです。

NEXT_PUBLIC_ を付けるということは、クライアントに見えてよい前提で扱うことです。Next.js の Missing Env Value 文書でも、クライアントでアクセスする環境変数には NEXT_PUBLIC_ が必要だと説明されています。裏を返せば、付けたものはクライアントへ出る想定です。

ミス2：クライアント側で private 値を読もうとする

たとえば次のようなコードです。

export default function Page() {
  return <p>{process.env.API_KEY}</p>
}

これは設計としてまずいです。Next.js の文書では、private な環境変数はクライアントへ漏れないよう扱われます。

ミス3：同じキーを複数ファイルに書いて、どれが効いているか分からなくなる

これもよくあります。

原因は読み込み順序の把握不足です。Next.js 公式の Load Order を頭の片隅に置いておくだけで、かなり混乱が減ります。

初心者向けのおすすめ運用

まずはこのルールで十分

秘密値は NEXT_PUBLIC_ を付けない
画面で使う公開値だけ NEXT_PUBLIC_ を付ける
共通設定は .env、ローカル個別設定は .env.local を意識する
未設定ならエラーにする
迷ったら「この値をブラウザの人に見られて困るか」で判断する

この5つが身に付くと、環境変数はただの設定ではなく、設計上の境界線として見えてきます。Next.js の環境変数機能は、まさにその境界線をはっきりさせるためにあります。

ミニ実践

例1：サイト名をブラウザへ出す

.env.local

NEXT_PUBLIC_SITE_NAME=Prince Academy

app/page.tsx

export default function Page() {
  return <h1>{process.env.NEXT_PUBLIC_SITE_NAME}</h1>
}

このケースでは、サイト名は公開されても問題がない前提です。そのため NEXT_PUBLIC_ を付けます。Next.js 公式のクライアント公開ルールに沿った使い方です。

例2：シークレットキーはサーバー側にとどめる

.env.local

PAYMENT_SECRET_KEY=sk_test_xxx

サーバー側コード

const paymentSecret = process.env.PAYMENT_SECRET_KEY

if (!paymentSecret) {
  throw new Error('PAYMENT_SECRET_KEY が未設定です')
}

このケースでは、キーは外へ見せてはいけません。したがって NEXT_PUBLIC_ は付けません。Next.js 公式の private value の考え方に一致します。

練習問題

問1

Next.js において、ブラウザ側で安全に参照させる前提の環境変数に必要な接頭辞はどれですか。

A. PUBLIC_ B. NEXT_PUBLIC_ C. CLIENT_ D. NEXT_CLIENT_

答え

解説

Next.js 公式では、クライアントでアクセスする環境変数には NEXT_PUBLIC_ を付ける必要があると説明されています。

問2

次のうち、原則として NEXT_PUBLIC_ を付けるべきではないものはどれですか。

A. サイト名

B. 公開用 API のベース URL

C. データベース接続文字列

D. 公開前提の計測 ID

答え

解説

データベース接続文字列は秘密情報であり、サーバー専用にすべき値です。Next.js では NEXT_PUBLIC_ が付かない private 値はサーバー側で扱う前提です。

問3

Next.js 公式の環境変数読み込み順序で、.env より優先されるものとして正しいものはどれですか。

A. .env が常に最優先 B. .env.local や .env.$(NODE_ENV).local C. README.md D. public/ フォルダ

答え

解説

Next.js 公式では、読み込み順序は process.env、.env.$(NODE_ENV).local、.env.local、.env.$(NODE_ENV)、.env の順です。つまり .env.local などの方が .env より優先されます。

問4

Node.js における環境変数の基本的な参照先はどれですか。

A. window.env B. document.env C. process.env D. globalThis.config

答え

解説

Node.js 公式では process.env はユーザー環境を含むオブジェクトだと説明されています。Next.js でも通常ここから環境変数を読みます。

問5

次のコードの問題点として最も適切なものはどれですか。

export default function Page() {
  return <p>{process.env.API_KEY}</p>
}

A. TypeScript が使われていない

B. private な環境変数をクライアント側で表示しようとしている

C. localhost では動かない

D. .env は数字しか保存できない

Next.js では、その境界を NEXT_PUBLIC_ という非常に分かりやすいルールで表現します。既定では環境変数はサーバー専用で、クライアントへ出したいものだけを明示的に公開します。

初心者のうちは、次の4点を覚えておけば十分です。

.env は キー=値 の形で書く設定ファイルである。
Next.js は .env を標準で読み込める。
NEXT_PUBLIC_ が付いた値だけがブラウザ側で使える。
読み込み順序があるので、同じキーを複数ファイルへ書くと優先順位が効く。

envファイルが、アプリを安全に育てるための柵のように見えてきたら理解が深まったと考えて良いと思います。

参考文献

Next.js Documentation, Environment Variables.
Next.js Documentation, Self-Hosting.
Next.js Documentation, Missing Env Value.
Next.js Documentation, Composition Patterns.
Next.js Documentation, next.config.js / env.
Node.js Documentation, Environment Variables.
Node.js Documentation, process.env.

この節で学ぶこと

初心者の段階では、ここを「設定の細かい話」と見てしまいがちです。けれど実際は逆で、環境変数は事故を防ぐための最前線です。

たとえば API キー、データベース接続情報、Webhook シークレットのような値を、うっかり画面側へ漏らさないために使います。

Next.js の公式文書でも、NEXT_PUBLIC_ が付かない値は private で、クライアントへ漏れないよう扱われると説明されています。

この節を読み終えたときの到達目標は、次の4つです。

.env が何のためのファイルか説明できること。
NEXT_PUBLIC_ が付く値と付かない値の違いを言えること。
.env の読み込み順序をざっくり理解すること。
「この値はサーバー専用にすべきか、ブラウザへ公開してよいか」を判断する感覚を持つことです。

Next.js 公式は環境変数の読み込み順序も明示しており、Node.js 公式は .env を key-value 形式のファイルとして定義しています。

環境変数とは何か

一言でいえば「コードの外に置く設定値」

たとえば、次のような値は環境変数に向いています。

API キー
データベース URL
外部サービスのシークレット
開発環境と本番環境で変えたい URL
ポート番号やデバッグ設定

ここでの感覚はとても大事です。

なぜコードに直接書かないのか

理由は主に3つあります。

秘密情報を守るため

環境ごとの差し替えをしやすくするため

開発用と本番用で URL やキーを変えたいことはよくあります。Next.js には .env.development や .env.production のような使い分けがあります。

コードを汚さないため

設定値をコードから分離すると、アプリ本体の責務がはっきりします。これは設計としてもきれいです。

.envファイルとは何か

形式はシンプルな key-value

たとえば、次のように書きます。

DATABASE_URL=postgres://user:password@localhost:5432/mydb
API_KEY=secret-key
NEXT_PUBLIC_SITE_NAME=My App

ここで見るべきポイントは2つです。

DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_xxx
INTERNAL_API_TOKEN=xxx

ブラウザへ渡すには `NEXT_PUBLIC_` を付ける

たとえば次のようにします。

NEXT_PUBLIC_SITE_NAME=Prince Academy
NEXT_PUBLIC_API_BASE_URL=https://example.com

この値は画面側でも使えます。

サーバー側とクライアント側の違い

サーバー側で使う例

const dbUrl = process.env.DATABASE_URL

if (!dbUrl) {
  throw new Error('DATABASE_URL が設定されていません')
}

このコードの感覚は大切です。

クライアント側で使う例

export default function Page() {
  return <h1>{process.env.NEXT_PUBLIC_SITE_NAME}</h1>
}

ここで SITE_NAME ではなく NEXT_PUBLIC_SITE_NAME であることが重要です。

「公開してよい値」と「公開してはいけない値」の見分け方

公開してよい値

たとえば次のようなものです。

サイト名
公開用 API のベース URL
公開前提の計測 ID
フロントエンドだけで使う公開設定値

NEXT_PUBLIC_SITE_NAME=My Service
NEXT_PUBLIC_ANALYTICS_ID=abc-123

公開してはいけない値

次のようなものは原則 private です。

シークレットキー
管理者 API トークン
データベース接続文字列
Webhook secret
内部システム用トークン

DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_xxx
WEBHOOK_SECRET=super-secret

.envの読み込み順序

どのファイルが優先されるのか

Next.js 公式は、環境変数の読み込み順序を次のように示しています。上から順に探し、見つかった時点で止まります。

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 の方が使われます。これは Next.js 公式の Environment Variable Load Order に明記されています。

これをどう覚えるか

初心者向けには、こう覚えると十分です。

より具体的なものが強い
local が付くものはローカル個別設定寄り
最後の土台が .env 全部を丸暗記しなくてもよいです。

ただ、「同じキーを書いたときは上書き順がある」という認識は持っておくと、あとでかなり助かります。

`NODE_ENV` とファイルの使い分け

よく出てくるファイル名

Next.js の公式ガイドに基づくと、代表的には次のようなファイルを使い分けます。

.env
.env.local
.env.development
.env.development.local
.env.production
.env.production.local この構成を見ると、環境変数は1枚岩ではなく、共通設定・環境別設定・ローカル専用設定に分けられることが分かります。

たとえばチーム共通の開発設定は .env.development、自分のローカルだけで使う微調整は .env.development.local、という整理ができます。

process.envの基本

値は `process.env` から読む

const apiBaseUrl = process.env.NEXT_PUBLIC_API_BASE_URL
const secret = process.env.INTERNAL_API_TOKEN

ここで大事なのは、読み方は同じでも公開範囲は同じではないことです。

process.env から読めるからといって、何でもブラウザへ出してよいわけではありません。Next.js はそこを NEXT_PUBLIC_ で区別しています。

存在チェックを書く癖をつける

初心者の段階ほど、次のような存在チェックは役に立ちます。

const apiKey = process.env.API_KEY

if (!apiKey) {
  throw new Error('API_KEY が設定されていません')
}

next.configのenvについて

使えるが、まずは `.env` を優先した方が理解しやすい

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  env: {
    customKey: 'my-value',
  },
}

export default nextConfig

ただ、初心者にとってはまず .env の理解を優先する方が自然です。

export default function Page() {
  return <p>{process.env.API_KEY}</p>
}

これは設計としてまずいです。Next.js の文書では、private な環境変数はクライアントへ漏れないよう扱われます。

秘密値は NEXT_PUBLIC_ を付けない
画面で使う公開値だけ NEXT_PUBLIC_ を付ける
共通設定は .env、ローカル個別設定は .env.local を意識する
未設定ならエラーにする
迷ったら「この値をブラウザの人に見られて困るか」で判断する

ミニ実践

例1：サイト名をブラウザへ出す

.env.local

NEXT_PUBLIC_SITE_NAME=Prince Academy

app/page.tsx

export default function Page() {
  return <h1>{process.env.NEXT_PUBLIC_SITE_NAME}</h1>
}

例2：シークレットキーはサーバー側にとどめる

.env.local

PAYMENT_SECRET_KEY=sk_test_xxx

サーバー側コード

const paymentSecret = process.env.PAYMENT_SECRET_KEY

if (!paymentSecret) {
  throw new Error('PAYMENT_SECRET_KEY が未設定です')
}

このケースでは、キーは外へ見せてはいけません。したがって NEXT_PUBLIC_ は付けません。Next.js 公式の private value の考え方に一致します。

B. 公開用 API のベース URL

C. データベース接続文字列

D. 公開前提の計測 ID

export default function Page() {
  return <p>{process.env.API_KEY}</p>
}

A. TypeScript が使われていない

B. private な環境変数をクライアント側で表示しようとしている

C. localhost では動かない

D. .env は数字しか保存できない

初心者のうちは、次の4点を覚えておけば十分です。

.env は キー=値 の形で書く設定ファイルである。
Next.js は .env を標準で読み込める。
NEXT_PUBLIC_ が付いた値だけがブラウザ側で使える。
読み込み順序があるので、同じキーを複数ファイルへ書くと優先順位が効く。

envファイルが、アプリを安全に育てるための柵のように見えてきたら理解が深まったと考えて良いと思います。

参考文献

Next.js Documentation, Environment Variables.
Next.js Documentation, Self-Hosting.
Next.js Documentation, Missing Env Value.
Next.js Documentation, Composition Patterns.
Next.js Documentation, next.config.js / env.
Node.js Documentation, Environment Variables.
Node.js Documentation, process.env.