【React】環境ごとの環境変数管理（.env）

JavaScript
2024.08.16

こんにちは、かつコーチです。

前回はVercelを使ったReactアプリのデプロイ手順を解説しました。

デプロイができるようになると次にぶつかるのが、「開発中と本番で、APIの向き先やキーを切り替えたい」という悩みです。

今回は、Reactアプリで環境変数を扱う.envファイルの使い方と、開発・本番で値を切り替える方法を解説します。

環境変数とは？なぜコードに直接書いてはいけないのか

環境変数の定義

環境変数とは、プログラムの外側で管理し、実行環境ごとに値を切り替えられる設定値のことです。

APIのエンドポイントURL、外部サービスのAPIキー、機能フラグなど、「環境によって変えたいけれど、コード自体は変えたくない」情報を扱うのに使います。

コードに直接書いた場合のリスク

APIキーのような秘匿情報をソースコードに直接書いてしまうと、GitHubなどにコードを公開したり、ビルド後のファイルを誰かが調べたりしたときに、値がそのまま漏えいしてしまいます。

とくにReactのようなフロントエンドのコードは、ビルドしてもブラウザ側で最終的に読み込まれるため、「サーバー専用の秘密鍵」のような扱いには本質的に向いていません。

環境変数の仕組みを正しく理解しておくことは、セキュリティ事故を防ぐうえでも欠かせない知識です。

.envファイルの基本

ファイルの命名ルール

Vite製のReactプロジェクトでは、プロジェクト直下に.envファイルを置くことで環境変数を定義できます。

# .env（すべての環境で共通の値）
VITE_APP_NAME=かつコーチ学習アプリ

# .env.development（開発環境専用）
VITE_API_BASE_URL=http://localhost:8000/api

# .env.production（本番環境専用）
VITE_API_BASE_URL=https://api.example.com/api

npm run devを実行すると.env.developmentが、npm run buildを実行すると.env.productionが、それぞれ.envと合わせて読み込まれます。

ファイル名だけで自動的に環境が切り替わるので、コード側でif文を使って向き先を出し分ける必要がありません。

VITE_プレフィックスが必要な理由

Viteでは、VITE_から始まる名前の変数だけが、ビルド後のフロントエンドコードに埋め込まれる仕組みになっています。

// コード側での読み込み方
const apiUrl = import.meta.env.VITE_API_BASE_URL;
const appName = import.meta.env.VITE_APP_NAME;

console.log(apiUrl); // 開発中なら http://localhost:8000/api

逆に言うと、VITE_が付いていない変数はビルド時に自動で除外され、import.meta.envからはundefinedしか取得できません。

これは事故ではなく、サーバー専用の秘密情報を誤ってフロントエンドに埋め込まないための、意図的な安全装置です。

.envファイルをGit管理から除外する

.gitignoreへの追加

.envファイルは、開発者ごとに異なる値を持つことが多いうえ、うっかり秘匿情報を書いてしまうリスクもあるため、基本的にGitの管理対象から外します。

# .gitignore
.env
.env.local
.env.*.local

代わりに、値の名前だけを共有するための.env.exampleをリポジトリに含めておくのが定番の運用です。

# .env.example（値は空、または仮の値にしておく）
VITE_API_BASE_URL=
VITE_APP_NAME=

新しくプロジェクトに参加したメンバーは、.env.exampleをコピーして.envを作り、自分の環境に合わせて値を埋めるだけで開発を始められます。

つまずきやすいポイント：VITE_プレフィックスの付け忘れ

かつコーチが実際にハマった「値が読めない」トラブル

私が最初にViteで環境変数を扱ったとき、外部APIのキーを.envに書いたのに、コード側でundefinedしか取得できず、原因が分からず1時間ほど悩んだことがあります。

原因は単純で、VITE_のプレフィックスを付け忘れていたことでした。

❌ Before：VITE_プレフィックスを付けずに定義してしまう

# .env
API_KEY=abcdefg12345

function fetchData() {
  // ビルド時に除外され、常にundefinedになる
  const apiKey = import.meta.env.API_KEY;

  console.log(apiKey); // undefined
}

Node.js（サーバーサイド）のprocess.envに慣れていると、プレフィックスなしで書く癖がついていて、Viteでも同じ感覚で書いてしまいがちです。

エラーメッセージが出るわけではなく、静かにundefinedが返るだけなので、しばらく気づけませんでした。

✅ After：VITE_プレフィックスを付けて定義する

# .env
VITE_API_KEY=abcdefg12345

function fetchData() {
  const apiKey = import.meta.env.VITE_API_KEY;

  console.log(apiKey); // abcdefg12345
}

Viteで環境変数がうまく読めないときは、まずVITE_が付いているかを確認する、という順番で調べると、原因にたどり着くのが早くなります。

なお、サーバー専用の秘密鍵などフロントエンドに出したくない値は、そもそもVITE_を付けずにビルドプロセス側（サーバーサイドの処理）だけで扱うのが正しい使い方です。

Vercel側での環境変数設定

ダッシュボードからの設定

.env.productionをGit管理から外している場合、本番用の値はVercelダッシュボードの「Settings」→「Environment Variables」から個別に登録します。

  • Key：VITE_API_BASE_URL
  • Value：https://api.example.com/api
  • Environment：Production / Preview / Developmentから選択

環境ごとにチェックボックスで適用範囲を選べるため、「本番だけ本物のAPI、プレビュー環境はステージング用のAPI」といった細かい出し分けも可能です。

設定変更後は再デプロイが必要

環境変数を追加・変更した場合、すでにデプロイ済みのビルドには反映されません。

Vercelダッシュボードから手動で「Redeploy」を実行するか、新しいコミットをプッシュして再ビルドを走らせる必要があります。

私も「値を変えたのに反映されない」と焦った経験がありますが、たいていはこの再デプロイ忘れが原因でした。

まとめ

この記事のポイント

  • 環境変数は「環境によって変えたい値」をコードから切り離して管理する仕組み
  • Viteでは.env / .env.development / .env.productionでファイルを使い分ける
  • フロントエンドに埋め込みたい値には必ずVITE_プレフィックスを付ける
  • .envはGit管理から除外し、代わりに.env.exampleで共有する
  • Vercelでは本番用の値をダッシュボードから設定し、変更後は再デプロイが必要

次に読むべき記事

次回は、公開後のパフォーマンスにも直結する「ビルド最適化」を扱います。

→ 次の記事：ビルド最適化：バンドルサイズを小さくする方法

タイトルとURLをコピーしました