Next.jsにおける環境変数（`.env`）の基本と実践的な使い方

私はNext.jsとtailwindcssを使用し、フロントエンド開発を行っている初心者です。開発を進める中で、APIキーなどのセキュリティ上重要な情報の管理に悩まされることがありました。これらの情報をソースコードから分離し、安全に管理する方法について、環境変数の基本的な設定方法と実践的な使い方についてまとめます。

もくじ

はじめに
envファイルとは？
envファイルの作成方法
envファイルの書き方
NEXT_PUBLIC_の使い方
環境変数の使い方
TypeScriptでの環境変数の使用
envファイルの種類と使い分け
読み込みの優先順位（上位にあるものが上書きする）
個人開発での推奨設定
チーム開発での推奨設定
envファイルを使う時の注意点
よくある問題と解決方法
まとめ

はじめに

Next.jsでWebサイトを開発する際、APIキーなどのセキュリティ上重要な情報を、ソースコードから分離して管理することができます。しかし、Next.jsの環境変数には独自の仕様があり、特にNEXT_PUBLIC_プレフィックスの使い方や、開発環境と本番環境での違いなど、初心者には分かりにくい部分が多く存在します。
また、GitHubなどでソースコードを公開する際に、誤って機密情報を公開してしまうリスクも考慮する必要があります。この記事では、Next.jsにおける環境変数の基本的な概念を説明していきます。

なお、この記事は2部構成の第1部として、環境変数の基本に焦点を当てています。第2部では、Vercelへのデプロイ時の環境変数の設定方法について詳しく解説します。
実際のデプロイ時の設定方法や注意点を知りたい方は、第2部もぜひご覧ください。
【保存版】Vercelデプロイで失敗しない！ 🚀 環境変数の正しい設定方法と注意点

envファイルとは？

envファイルは、パスワードやAPIキーなど、公開したくない情報を安全に管理するための設定ファイルです。

envファイルの作成方法

通常のファイルと同様の手順（VSCodeのファイル作成ボタン）で作成できます。

コマンドから作成する場合

Unix系（Mac/Linux）

# .env.local ファイルの作成
touch .env.local

Windows PowerShell

ni .env.local

※ niはNew-Itemのエイリアス（省略形）

envファイルの書き方

# コメントを書くときは#を使います
# 変数名=値 の形式で書きます
DATABASE_URL=http://example.com
API_KEY=取得したAPIキー

# スペースは入れないようにします
# ❌ DATABASE_URL = http://example.com  (×)
console.log(process.env.DATABASE_URL)
// 出力: "  http://example.com"  （前後の空白が含まれてしまう）

# ⭕️ DATABASE_URL=http://example.com   (○)
console.log(process.env.DATABASE_URL)
// 出力: "http://example.com"    （意図した値が取得できる）

# 値にスペースを含んでいてもクォーテーションで囲む必要はない
MESSAGE=Hello World

値の設定について

`NEXT_PUBLIC_`の使い方

Next.jsでは、環境変数を使う場所によって、名前の付け方を変える必要があります。
ブラウザ側（クライアントサイド）で使用する場合はNEXT_PUBLIC_プレフィックスが必須です。

ブラウザ側で使う場合（NEXT_PUBLIC_を付ける）

# Webサイトの名前など、公開しても問題ない情報
NEXT_PUBLIC_WEBSITE_NAME=My Website
NEXT_PUBLIC_API_URL=http://localhost:3000

サーバー側でのみ使う場合（NEXT_PUBLIC_を付けない）

# パスワードやAPIキーなど、秘密にしたい情報
API_KEY=secret_key_123
DATABASE_PASSWORD=db_password

環境変数の使い方

環境変数はprocess.envを使って参照します。ブラウザ側ではNEXT_PUBLIC_が付いた変数のみが使用可能で、サーバー側ではすべての環境変数を使用できます。

ブラウザ側での使用例

// ブラウザ側で環境変数を使う場合は、NEXT_PUBLIC_が付いた変数のみ使えます
// Webサイトの名前を表示する場合
const websiteName = process.env.NEXT_PUBLIC_WEBSITE_NAME
// 例: console.log(websiteName) → "My Website"

// APIのURLを使用する場合
const apiUrl = process.env.NEXT_PUBLIC_API_URL
// 例: console.log(apiUrl) → "http://localhost:3000"

サーバー側での使用例

// サーバー側の処理（APIルートやgetServerSidePropsなど）
// APIキーを使用する場合（NEXT_PUBLIC_が付いていない秘密情報）
const apiKey = process.env.API_KEY
// 例: console.log(apiKey) → "secret_key_123"

//データベースのパスワードを使用する場合
const dbPassword = process.env.DATABASE_PASSWORD
// console.log(dbPassword) // → "db_password"

TypeScriptでの環境変数の使用

TypeScriptを使用している場合、環境変数の後ろに!（エクスクラメーションマーク）を付けることがあります。これは、その変数が必ず存在することをTypeScriptに伝えるためです。

基本的な使い方

// エクスクラメーションマークなしの場合
// TypeScriptは「この変数が存在しないかもしれない」と警告を出すことがあります
const websiteName = process.env.NEXT_PUBLIC_WEBSITE_NAME
// エディタで赤い波線が出る可能性があります

// エクスクラメーションマークありの場合
// 「この変数は必ず存在する」とTypeScriptに伝えています
const websiteName = process.env.NEXT_PUBLIC_WEBSITE_NAME!
// エディタの警告が消えます

エクスクラメーションマークを使う時の注意点

必ず存在する環境変数の場合のみ使用する
環境変数が設定されていない場合、エラーが発生する可能性がある
TypeScriptの警告を消すためだけに使うのは避ける

エクスクラメーションマークを使う前の環境変数チェック

最初は環境変数が正しく設定されているか確認してから!を使う
エディタで警告が出ても、環境変数が正しく設定されていれば動作に問題はない
環境変数の存在チェックを行うと良い

例：環境変数の存在チェック

// 安全な環境変数の使用方法
const websiteName = process.env.NEXT_PUBLIC_WEBSITE_NAME
if (!websiteName) {
  throw new Error('NEXT_PUBLIC_WEBSITE_NAME is not defined')
}

envファイルの種類と使い分け

1. `.env.local`（最も一般的）

使う場面：個人開発時の通常の開発作業
特徴：
- GitHubに上げない個人用の設定
- 開発中のテスト用APIキーなど
- パスワードなどの秘密情報

例

# WebサイトがAPIにアクセスするためのURL
NEXT_PUBLIC_API_URL=http://localhost:3000

# 外部サービスにアクセスするための認証キー
API_KEY=your_secret_key_123

# データベースに接続するためのURL
DATABASE_URL=http://localhost:5432

2. `.env`

使う場面：チームで共有する基本設定
特徴：
- GitHubにコミットして共有することもある
- 全環境で共通の設定
- 本番環境でも使用可能な設定

例

# Webサイトの名前
NEXT_PUBLIC_WEBSITE_NAME=My Amazing Website

# 問い合わせ用のメールアドレス
NEXT_PUBLIC_CONTACT_EMAIL=contact@example.com

3. `.env.development`

使う場面：開発環境専用の設定
特徴：
- 開発時のみ使用する設定
- 開発用のAPIエンドポイント

例

# 開発環境でのAPIのURL
NEXT_PUBLIC_API_URL=http://dev-api.example.com

# 開発環境でのWebサイトのURL
NEXT_PUBLIC_WEBSITE_URL=http://localhost:3000

4. `.env.production`

使う場面：本番環境専用の設定
特徴：
- 本番環境でのみ使用する設定
- 本番用のAPIエンドポイント

例

# 本番環境でのAPIのURL
NEXT_PUBLIC_API_URL=https://api.example.com

# 本番環境でのWebサイトのURL
NEXT_PUBLIC_WEBSITE_URL=https://www.example.com

envファイルの種類と特徴一覧

ファイル名	主な用途	特徴
`.env.local`	個人開発時	・GitHubに非公開の個人設定・APIキーや秘密情報・ローカル環境固有の設定
`.env`	チーム共有用	・GitHubでの共有が可能・全環境共通の基本設定・公開可能な設定値
`.env.development`	開発環境用	・開発時専用の設定・開発用APIエンドポイント・デバッグ関連の設定
`.env.production`	本番環境用	・本番環境専用の設定・本番用APIエンドポイント・セキュリティ関連の設定

読み込みの優先順位（上位にあるものが上書きする）

.env.local（最優先）
.env.developmentまたは.env.production（環境による）
.env（最後）

個人開発での推奨設定

基本は.env.localを使用
- ローカルでの開発用の設定すべて
- APIキーなどの秘密情報
Vercel管理画面で本番環境の設定
- 本番用のAPIキー
- 本番用のデータベース接続情報

チーム開発での推奨設定

.envでチーム共通の設定を管理
- プロジェクト名
- 共通の接続先URL（エンドポイント）
.env.localで個人の開発環境を設定
- 各自のAPIキー
- ローカルのデータベース設定
Vercel管理画面で本番環境を設定
- 本番用の各種設定
- セキュリティ要素の高い情報

envファイルを使う時の注意点

GitHubに上げない設定
- 最初は.env.localだけを使うところから始める
- .gitignoreファイルに.env.localを追加する
- パスワードやAPIキーが含まれるファイルは必ず非公開にする
ブラウザで使う変数の命名
- 変数名は分かりやすい名前をつける
- NEXT_PUBLIC_から始める
- 例：NEXT_PUBLIC_API_URL=https://api.example.com
機密情報の扱い
- パスワードやAPIキーは必ず.env.localに書く
- 本番環境ではVercelの管理画面で設定する
ファイル管理
- 複数のenvファイルは、必要になった時点で追加する
- envファイルは必ずプロジェクトの一番上の階層に作成する
- 迷ったら、より制限の厳しい方法を選ぶ
  （例：公開していいか迷ったら、公開しない）

よくある問題と解決方法

環境変数を使用する際によく遭遇する問題とその解決方法をまとめました。新しく環境変数を設定する際や、エラーが発生した時の参考にしてください。

1. 環境変数が undefined になる

// 問題のある例
// 環境変数が見つからずundefinedになってしまう
const apiKey = process.env.API_KEY
console.log(apiKey) // undefined

// 解決方法
// 環境変数が存在するか確認してから使用する
if (!process.env.API_KEY) {
  // 環境変数が見つからない場合はエラーメッセージを表示
  console.error('API_KEYが設定されていません')
} else {
  // 環境変数が見つかった場合は使用する
  const apiKey = process.env.API_KEY
  console.log(apiKey)
}

主な原因と対処法

.env.localファイルが正しい場所にない
- プロジェクトのルートフォルダに置いているか確認
- ファイル名が正しいか確認（タイポしていないか確認）
開発サーバーの再起動が必要
- ターミナル（コマンドプロンプト）上でCtrl + Cを押してサーバーを停止
- 環境変数を追加した後、以下のいずれかのコマンドでサーバーを再起動
  - npm run dev
  - yarn dev
NEXT_PUBLIC_の付け忘れ
- ブラウザで使用する場合はNEXT_PUBLIC_を付ける

2. 環境変数の値が正しく読み込まれない

# 問題のある例
# スペースが入っている
API_KEY = 123456

# 解決方法
# スペースを入れない
API_KEY=123456

主な原因と対処法

スペースの問題
- =の前後にスペースを入れない
- 行末にスペースがないか確認（見落としがち）

3. ブラウザでの環境変数アクセスエラー

// 問題のある例
// NEXT_PUBLIC_がないのでブラウザでアクセスできない
const siteUrl = process.env.SITE_URL

// 解決方法
// ブラウザで使用する環境変数には必ずNEXT_PUBLIC_を付ける
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL

主な原因と対処法

NEXT_PUBLIC_プレフィックスの未使用
- ブラウザで使用する場合は必ず付ける
- サーバー側でのみ使用する場合は不要
環境変数の使用場所の確認
- src/components/フォルダ内のファイル（コンポーネントファイル）で使用する場合はNEXT_PUBLIC_が必要
- src/app/api/フォルダ内のファイル（APIルート）ではNEXT_PUBLIC_なしで使用可能

4. GitHubに環境変数が公開される

# .gitignoreファイルに以下を追加して、環境変数ファイルを除外する
.env
.env.local
.env*.local

主な原因と対処法

.gitignoreに未記載
- .gitignoreファイルに環境変数ファイルを追加

まとめ

Next.jsにおける環境変数の設定は、開発フローの重要な部分を占めています。ローカル開発環境では.env.localファイルを使用し、本番環境では適切な方法で設定を行うという基本的な流れを押さえることが重要です。特に、環境変数の命名規則やファイル管理に注意を払うことで、多くの一般的なトラブルを回避することができます。

第2部では、これらの環境変数をVercelにデプロイする際の具体的な設定方法や、実際の開発現場でよく遭遇するトラブルとその解決方法について詳しく解説していきます。
【保存版】Vercelデプロイで失敗しない！ 🚀 環境変数の正しい設定方法と注意点

もし記事の内容に間違いがあれば、コメントでご指摘いただけますと幸いです。また、より良い方法や代替手段をご存知の方がいらっしゃいましたら、ぜひ共有していただければと存じます。