Git/開発 Study Note：環境変数と .env ―― 機密情報の流出防止と環境別設定の切り替え

AIが「.envに接続先を設定してください」と言う。手元では動いていたアプリが、公開先では外部サービスにつながらない。設定ファイルを変更したのに、画面の動きが変わらない。

こうした場面では、ソースコードだけでなく、アプリや開発の道具に渡す設定を確認します。どこにつなぐか、どの値を使うか、どのように動かすかを、コードの外で指定する仕組みがあります。

前回は、パッケージマネージャーで必要な部品を取りそろえる話でした。今回は、その部品やコードを動かすときの「設定ファイル・環境変数・.env」を整理します。JavaScriptやTypeScriptのWebアプリを例に、役割の違い、読み込み、公開先の設定、秘密情報の扱いまで説明します。ファイル名や設定値は説明用の例です。

1. 処理の内容と、動かすための設定を分ける

たとえば、外部サービスから記事の一覧を取得するアプリを考えます。

「一覧を取得し、画面に表示する」という処理は同じでも、開発中は練習用の接続先を、本番では実際の接続先を使いたいことがあります。接続先をコードに直接書くと、切り替えるたびにコードを編集する必要があります。

そこで、接続先などを設定として外に置き、処理の中から読み込む方法を使います。

料理でいえば、作り方の手順と、「今日は何人分作るか」という指示を分けるイメージです。基本の手順を毎回書き直さず、渡す条件を変えて使います。

ただし、設定をすべて外に出す必要はありません。環境によって変わるもの、道具の動作を調整するもの、秘密として扱うものなど、目的に合った置き場所を選びます。

2. 設定ファイルは、アプリや道具への指示をまとめる場所

設定ファイルは、アプリや開発の道具が読み込む設定を、ファイルとしてまとめたものです。書式はJSON、YAML、JavaScript、TypeScriptなど、使う道具によって異なります。

たとえばViteでは、プロジェクトの設定をvite.config.jsなどに記述できます。ファイル名や書き方、利用できる設定項目は、Viteのルールで決まっています。Vite公式：設定ファイル

自作アプリでも、説明用に次のような設定ファイルを設けることが考えられます。

{
  "appTitle": "記事一覧",
  "itemsPerPage": 20
}

この例は、表示する名前と、1ページに表示する件数を指定しています。ただし、任意の名前でファイルを保存するだけでは、アプリに反映されません。そのファイルを読み込み、各項目を使う処理が必要です。

「設定ファイルを作った」と「その設定が使われた」は別です。道具が自動で読み込むファイルなのか、アプリ側で読み込む必要があるのかを確認しましょう。

また、設定ファイルは秘密情報専用の保管場所ではありません。チームで共有したい設定と、共有してはいけない値を分けて扱います。

3. 環境変数は、プログラムへ渡される名前付きの値

環境変数は、プログラムが動く環境から渡される、名前と値の組み合わせです。ファイルそのものの名前ではありません。

たとえば、API_BASE_URLという名前に接続先のURLを設定し、アプリがその名前で値を読み取ります。Node.jsでは、環境変数をprocess.envから参照できます。Node.js公式：環境変数

const apiBaseUrl = process.env.API_BASE_URL;

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

これはNode.jsで動く処理の説明用の例です。必要な値がなければ、その名前を示して止めています。値そのものをログに表示する必要はありません。

同じコードを使いながら、手元では練習用のURL、公開先では本番用のURLを渡すことができます。

環境変数は、ターミナルから指定したり、公開サービスの設定画面に登録したりして用意します。特定のアプリに必要な値が、どの場所から渡されているかを把握することが大切です。

なお、Node.jsで参照する環境変数の値は基本的に文字列です。falseや20という値を設定しても、真偽値や数値として使うなら、コード側で変換や確認が必要です。名前の表記も、コードと設定でそろえます。Node.js公式：process.env

4. .envは、環境変数を用意するためのファイル

環境変数を毎回入力する代わりに、名前と値をファイルに記述しておく方法があります。そのためによく使われるのが、.envファイルです。

API_BASE_URL=https://api.example.com
EXTERNAL_API_TOKEN=replace_with_your_token

=の左側が名前、右側が値です。URLとトークンは説明用であり、実際の接続や認証には使えません。

.envは、こうした値を読み込んで環境変数として利用するためのファイルです。環境変数と.envは同じものではなく、「渡す値」と「その値を記録する方法」の関係にあります。Node.js公式：.envファイル

広い意味では、.envも設定を記録したファイルです。この3つは、互いに完全に別の分類というわけではありません。

そして、.envを置けば、どのアプリでも自動で読み込まれるわけではありません。 フレームワークの機能、読み込み用のライブラリ、Node.jsの起動オプションなど、値を取り込む仕組みが必要です。Node.js公式：.envの読み込み方法

使うファイルの名前、置く場所、複数ファイルがあるときの優先順位も、道具によって変わります。まず、そのプロジェクトのREADMEや公式の手順を確認します。

5. ブラウザに渡す値と、サーバーだけで使う値を分ける

Webアプリでは、ユーザーのブラウザで動く処理と、サーバー側で動く処理があります。設定を考えるときも、この境界が重要です。

ブラウザへ配られるコードに含まれた値は、利用者が確認できる前提で扱います。サーバー用の秘密のトークンを、画面側のコードで使うために埋め込んではいけません。

Next.jsでは、NEXT_PUBLIC_で始まる環境変数を、ブラウザ向けのコードに埋め込む仕組みがあります。通常、その値はビルド時に取り込まれます。Next.js公式：ブラウザ向けの環境変数

Viteでも、標準の設定ではVITE_で始まる値がクライアント側のコードに公開されます。これらの接頭辞は、「秘密にする印」ではなく、ブラウザへ渡す対象を示すルールです。Vite公式：環境変数

すべてのAPIキーが同じ性質とは限りません。公開を前提にしたキーもありますが、使える範囲や制限はサービスごとに確認します。

また、接頭辞を付けなければ何をしても安全、という意味でもありません。サーバーの処理が秘密の値を画面やAPIの応答、ログに出してしまえば、漏れる可能性があります。保存先だけでなく、どこへ渡すかまで確認します。

6. 手元と公開先には、それぞれ設定が必要

手元の.envで動作していても、その値が自動で公開先に登録されるとは限りません。

たとえば、秘密の値を含む.envをGitの管理対象から外していれば、GitHubからソースコードを取得する公開先にも、そのファイルは届きません。コードと部品がそろっていても、必要な設定がなければ処理が止まることがあります。

公開サービスでは、環境変数を設定画面などに登録する方法が一般的です。たとえばVercelでは、開発・プレビュー・本番など、適用する環境を指定できます。設定の変更は、すでに公開済みのものへ自動で反映されるわけではなく、新しいデプロイに適用されます。Vercel公式：環境変数

公開前には、次を確認します。

1. 必要な環境変数の名前を一覧にする。
2. 値を、使う環境に合わせて用意する。
3. 公開先で、その環境に登録する。
4. 値が必要になるタイミングに合わせ、ビルドや起動を行う。
5. 公開先で、対象の機能が動くことを確認する。

ここで気を付けたいのは、設定を読み取るタイミングです。

たとえばNext.jsのブラウザ向け環境変数は、ビルド時の値が成果物に入ります。公開先で値を変更しただけでは、その成果物に入った値は変わりません。Next.js公式：ビルド時と実行時の環境変数

「設定を直したのに変わらない」ときは、ファイルの中身だけでなく、どのタイミングで読み込まれるかを見ましょう。

7. 秘密の値を共有せず、必要な設定の形を共有する

チームや別のパソコンで動かすためには、「何を設定すればよいか」が分かる必要があります。ただし、秘密のトークンやパスワードを、そのまま共有用の原稿やGitHubに載せる必要はありません。

そこで、実際の値を入れるファイルと、必要な項目を示す見本を分ける方法があります。

# .env.example：必要な項目を示す見本
API_BASE_URL=https://api.example.com
EXTERNAL_API_TOKEN=

.env.exampleという名前は、この例の運用上の約束です。置けば自動で設定されるファイルという意味ではありません。READMEには、見本を基にどの名前のファイルを作り、どこで値を用意するかを書きます。

秘密の値を含むファイルをGitで管理しない場合は、プロジェクトの.gitignoreを確認します。たとえば、次は.envを除外する指定です。

.env

ただし、この指定だけでは.env.localなど別名のファイルは除外されません。実際に使うファイル名に合わせて確認します。また、.gitignoreは、すでにGitで追跡されているファイルには効きません。Git公式：gitignore

.env自体に暗号化の機能があるわけでもありません。ファイルを読める人や処理は、その値を読めます。AIへの依頼やエラーの相談でも、秘密の値をそのまま貼り付けず、変数名や値を伏せたログで確認を進めます。

もし秘密の値を誤って公開した場合は、現在のファイルから消すだけでは不十分です。まず該当する認証情報の失効・再発行を行い、履歴などに残った情報への対応を検討します。GitHub公式：リポジトリから機密情報を削除する

8. 設定で止まったときは、名前・読み込み・環境を確認する

設定に関するエラーは、「値を書き忘れた」だけとは限りません。ファイルの場所や名前、読み込み方、適用先が違っている場合もあります。

値が存在することと、その値で接続・認証できることも別です。名前が合っていても、別の環境用の値を使っていることがあります。

AIには、次のように依頼できます。

必要な環境変数の名前、読み込むファイル、利用する場所、読み込むタイミングを確認してください。秘密の値は表示せず、未設定かどうかと、手元・公開先のどちらに設定が必要かを整理してください。

値を一度にすべて変えるのではなく、どこまで正常に読めているかを確認すると、原因を切り分けやすくなります。

9. まとめと理解度確認

設定ファイルは、アプリや道具への指示をまとめるファイルです。環境変数は、プログラムへ渡される名前付きの値です。.envは、その値を用意するためによく使われるファイルです。

ファイルを作ること、値が読み込まれること、目的の処理が動くことは、それぞれ確認が必要です。手元と公開先、ブラウザとサーバー、ビルド時と実行時を分けて考えると、設定の行き先を追いやすくなります。

自分の言葉で説明してみる

1. 環境変数と.envは、何が違いますか？
2. .envを置けば、どのアプリでも自動で読み込まれますか？
3. 手元で動いたアプリが、公開先で設定不足になることがあるのはなぜですか？
4. NEXT_PUBLIC_や、標準設定でのVITE_を、秘密のトークンに付けてよいでしょうか？
5. ビルド時に埋め込んだ値は、公開先の環境変数を変えるだけで更新されますか？
6. .gitignoreに追記すれば、すでに公開した秘密の値も消えますか？

解答例

1. 環境変数はプログラムへ渡される名前付きの値、.envはその名前と値を記述するファイルです。
2. 読み込まれません。フレームワークの機能や、明示的な読み込みの仕組みが必要です。
3. 手元の設定は、公開先へ自動で引き継がれるとは限らないからです。公開先にも、その環境に合った設定を用意します。
4. 付けてはいけません。ブラウザ向けのコードへ公開される対象を示すルールなので、秘密の値を入れません。
5. 更新されません。新しい値で成果物を作り直す必要があります。
6. 消えません。すでに追跡されたファイルや過去の履歴は別に扱います。漏れた認証情報は、まず失効・再発行が必要です。

参考資料

• Vite公式：設定ファイル
• Node.js公式：環境変数と.env
• Node.js公式：process.env
• Next.js公式：環境変数
• Vite公式：環境変数とモード
• Vercel公式：環境変数
• Git公式：gitignore
• GitHub公式：リポジトリから機密情報を削除する

資料確認日：2026年10月12日