リクルーティングサイト
テックブログ

環境変数とは？APIキーや設定値をコードに書かない基本

環境変数とは？APIキーや設定値をコードに書かない基本

環境変数は、APIキーやDB接続情報、環境ごとに変わる設定値をコードの外で管理するための仕組みです。コードに秘密情報を直接書かないことで、Gitへ誤って公開するリスクを減らし、開発環境・テスト環境・本番環境で設定を安全に切り替えやすくなります。大切なのは、環境変数を単なる“隠し場所”ではなく、“設定を外から渡すための基本ルール”として理解することです。

1. 環境変数とは何か

1-1. 環境変数の定義：コードの外から設定を渡す仕組み

環境変数とは、プログラムの外から設定値を渡すための仕組みです。アプリのソースコードに値を直接書かず、実行する環境側が「この値を使ってください」と渡します。

プログラムには、APIキー、DB接続先、ポート番号、外部サービスのURLなど、実行する場所によって変わる設定があります。これらを全部コードへ埋め込むと、環境が変わるたびにソースを直す必要が出てきます。環境変数を使えば、コードは同じままで、実行環境だけ切り替えれば値を変えられます。

たとえば、開発中はローカルのDB、本番ではクラウドのDBを使うようなケースでは、接続先を環境変数から読む形にすると管理しやすいです。環境変数は「秘密情報を隠す道具」というより、まずは「設定をコードから分離する道具」と考えると理解しやすくなります。

1-2. なぜコードに直接書かないのか

APIキーや接続情報をコードに直接書かない理由は、セキュリティと運用の両方で困るからです。単に“見た目が悪い”という話ではありません。

まずセキュリティ面では、コードに秘密情報を書くと、Gitの履歴、レビュー画面、画面共有、公開リポジトリなど、いろいろな場所に漏れやすくなります。運用面では、開発環境と本番環境で値が違うたびにコードを書き換える必要が出て、ミスの原因になります。つまり、直書きは「漏れやすく、変えにくい」という二重の問題を持っています。

初心者のうちは、「個人開発だから大丈夫」と考えがちですが、練習用のコードでもGitHubへ上げることは多いです。あとからキーを消しても、履歴に残ることがあります。環境変数を使うのは、最初から危ない運用を避けるための基本習慣だと考えるとよいです。

1-3. APIキー、DB接続情報、環境別URLの例

環境変数へ入れる代表例は、APIキー、DB接続情報、環境ごとに変わるURLです。特に「環境で変わるもの」「外へ漏らしたくないもの」は候補になりやすいです。

たとえば、OpenAIやGoogle MapsなどのAPIキー、PostgreSQLやMySQLの接続文字列、開発用と本番用で異なるAPIのURLなどが典型です。反対に、アプリ名のようにどの環境でも同じで、漏れても問題になりにくい値は、必ずしも環境変数である必要はありません。大事なのは、全部を入れることではなく、性質で分けることです。

API_KEY=xxxxxxxxxxxxxxxx
DATABASE_URL=postgres://user:password@localhost:5432/app_db
API_BASE_URL=https://api.example.com
PORT=3000

この例では、秘密情報と環境依存の設定が混ざっています。注意点は、API_KEY や DATABASE_URL のような値をサンプルのまま本物で共有しないことです。また、フロントエンドでは「見えてよい値」と「見えてはいけない値」の区別が必要になるため、後の章でその落とし穴も整理します。

2. .envファイルと環境変数の違い

2-1. .envはローカル開発で使いやすくするためのファイル

.env ファイルは、ローカル開発で環境変数を扱いやすくするための補助的なファイルです。.envそのものが本体というより、環境変数を読み込みやすくするための入り口です。

本来、環境変数はOSや実行環境が持つ仕組みですが、毎回ターミナルで手入力するのは大変です。そこで、ローカル開発では .env に KEY=VALUE 形式で書いておき、アプリ起動時にまとめて読み込むことが多いです。これにより、開発者は設定を揃えやすくなります。

ただし、.env は「ローカルで便利に使うための方法のひとつ」であって、環境変数そのものと同じではありません。初心者が混同しやすいですが、「環境変数という仕組み」が先にあり、「.envはその管理を楽にするための手段」と考えると整理しやすいです。

2-2. 本番環境ではOSやクラウド側に設定する

本番環境では、.env ファイルを置くより、OSやクラウドの設定機能で環境変数を渡すことが多いです。ローカル開発と本番では、設定の置き方が違うことを理解しておくのが大切です。

たとえば、Linuxサーバ、Docker、GitHub Actions、Vercel、Render、AWS、GCPなどでは、それぞれ環境変数を設定する方法が用意されています。これらを使うと、秘密情報をアプリのファイルとしてサーバへ置かずに済むため、管理しやすくなります。また、デプロイ先ごとに設定を変えやすいのも利点です。

よくある誤解は、「ローカルで .env を使っているから、本番でもそのまま置けばよい」と考えることです。もちろん構成によっては可能ですが、初心者のうちは「本番は実行環境側で設定するのが基本」と覚えておくほうが安全です。特にクラウド環境では、管理画面やSecret管理機能を使うほうが一般的です。

2-3. dotenv系ライブラリの役割

dotenv のようなライブラリは、.env の内容を環境変数として読み込む役割を持ちます。つまり、「.envを書いただけで自動で使えるようになる」のではなく、読み込む仕組みが必要です。

Node.js系では、アプリ起動時に dotenv を読み込んで、process.env から値を参照する形がよく使われます。これにより、ローカル開発中でも環境変数を簡単に扱えます。ただし、フレームワークによっては最初から読み込み機能が入っていることもあるため、毎回同じやり方とは限りません。

import dotenv from 'dotenv';

dotenv.config();

const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;

このコードでは、.env の値を読み込んでから環境変数を参照しています。注意点は、process.env.API_KEY が必ず入っているとは限らないことです。設定漏れがあると undefined になるため、読み込めなかったときにどうするかを後の章で考える必要があります。

3. Gitに含めてはいけないもの

3-1. .envを.gitignoreに入れる理由

.env を .gitignore に入れる理由は、秘密情報や環境依存の値をGitへ入れないためです。ここを忘れると、個人開発でも簡単に漏えい事故につながります。

Gitへコミットされた情報は、チームメンバー全員に見えるだけでなく、履歴にも残ります。もしリポジトリを公開していたら、APIキーやDB接続情報がそのまま第三者に見えることもあります。たとえあとからファイルを消しても、過去の履歴に残っている限り、情報漏えいは完全には消えません。

# .gitignore
.env
.env.local
.env.production

この例では、秘密情報を含みやすい.env系ファイルをGit管理から外しています。注意点は、.gitignore に書く前にすでにコミットしていた場合、その後追記しても過去の追跡は止まらないことです。最初にプロジェクトを作った段階で、先に .gitignore を整える習慣を付けると安全です。

3-2. .env.exampleを用意する意味

.env をGitへ入れないなら、代わりに .env.example を用意して、必要な環境変数名だけ共有するのが実務でよく使われる方法です。これにより、秘密情報を出さずにセットアップしやすくなります。

.env.example には、実際のキーやパスワードは書かず、「どんな環境変数が必要か」だけを書きます。新しくプロジェクトに入った人は、それを見て自分のローカル用 .env を作れます。つまり、.env.example は秘密情報を共有するファイルではなく、設定項目の一覧表です。

API_KEY=your_api_key_here
DATABASE_URL=your_database_url_here
API_BASE_URL=http://localhost:3000
PORT=3000

この例では、必要なキー名は分かるが、本物の値は入っていません。注意点は、.env.example にも本番の実値を書いてしまわないことです。また、実際に必要な変数が増えたら、このファイルも更新しないと、新しい開発者や別環境で「何が足りないか分からない」状態になります。

3-3. うっかりコミットしたときの初動

もしAPIキーや秘密情報をうっかりGitへコミットしたら、まずやるべきことは、その値を無効化・再発行することです。ファイルを削除するだけでは不十分です。

一度Gitに載った秘密情報は、履歴、fork、ローカルクローン、CIログなどへ広がっている可能性があります。そのため、「最新コミットから消したから大丈夫」とは言えません。まずは流出したキーを使えない状態にし、その後で履歴整理や再発防止を考えるのが安全です。

初動の順番としては、「1. キーを失効または再発行する」「2. リポジトリから削除する」「3. 必要なら履歴の除去を検討する」「4. .gitignoreやシークレットスキャン設定を見直す」が基本です。初心者のうちは消すことだけに意識が向きやすいですが、本当に重要なのは“もう使えない状態にすること”です。

4. 開発環境と本番環境を分ける考え方

4-1. API URLやDB接続先を環境ごとに変える

環境変数の大きな役割のひとつは、開発環境と本番環境で違う設定を安全に切り替えることです。ここをコードの外へ出しておくと、同じアプリを別環境で動かしやすくなります。

たとえば、開発中はローカルAPIへ接続し、本番では公開APIへ接続するような場面があります。DBも同様で、ローカルのテストDBと本番DBは別であるべきです。これをコードの書き換えで切り替えると、うっかり本番情報を開発用へ使ってしまう事故が起きやすくなります。

環境変数を使えば、API_BASE_URL や DATABASE_URL を実行環境ごとに差し替えるだけで済みます。チェックポイントとしては、「この値は環境によって変わるか」「コード変更なしで切り替えたいか」で判断すると整理しやすいです。

4-2. デフォルト値を置くべきもの、置くべきでないもの

環境変数には、デフォルト値を置いてよいものと、絶対に置くべきでないものがあります。全部に初期値を付ければ便利、とは限りません。

たとえば、PORT=3000 のような開発用ポート番号や、ログレベルのような値はデフォルトを置きやすいです。一方で、APIキーや本番DB接続情報のような秘密情報は、デフォルトで埋めてはいけません。デフォルトがあることで「設定漏れに気づけない」状態になると、危険な接続先へ誤ってつながることがあります。

実務では、「漏れて困るもの」「環境によって厳密に変わるもの」は必須設定にし、それ以外は安全な範囲でデフォルトを使うとバランスが取りやすいです。判断に迷ったら、「この値が空でも安全に起動してよいか」で考えると整理しやすいです。

4-3. 環境変数が足りないときのエラー設計

環境変数が足りないなら、アプリはできるだけ早い段階で分かりやすく失敗するほうが安全です。足りないまま曖昧に動くほうが、本番では危険です。

たとえば、APIキーが未設定なのに起動だけできてしまうと、実際に機能を使うまで問題に気づかないことがあります。本番環境では、それが障害や設定漏れの見逃しにつながります。そのため、起動時に必要な環境変数をチェックして、足りなければ明示的にエラーを出す設計がよく使われます。

const requiredEnv = ['API_KEY', 'DATABASE_URL'];

for (const key of requiredEnv) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
}

このコードでは、必須の環境変数がない場合に起動時点で止めています。注意点は、エラーメッセージへ秘密の実値を出さないことです。「何が足りないか」だけを示し、「今入っている値」まではログに出さないほうが安全です。

5. よくある落とし穴

5-1. フロントエンドに秘密情報を置いてしまう

初心者が特に注意したいのは、フロントエンドの環境変数へ秘密情報を入れても、安全になるわけではないことです。ブラウザで動くコードに渡した時点で、基本的には利用者から見える前提で考える必要があります。

たとえば、ReactやNext.js、Viteなどでは環境変数をフロントで使える仕組みがありますが、それは「公開してよい設定値」を扱うためのものです。APIキーでも、公開前提のものと、サーバだけが持つべき秘密鍵は意味が違います。ここを混同すると、「環境変数だから安全」と誤解しやすいです。

判断基準としては、「ブラウザへ配られてもよいか」を考えると分かりやすいです。もし見られて困るなら、それはフロントエンドへ置くべきではなく、バックエンドで扱うべきです。環境変数は隠す魔法ではなく、どこで管理するかを分ける仕組みだと覚えておくと事故を減らせます。

5-2. 環境変数名がバラバラで管理できなくなる

環境変数運用で地味に困るのが、名前の付け方がバラバラになって管理しにくくなることです。意味が似た変数が増えると、どれを使うべきか分からなくなります。

たとえば、API_URL、BASE_API_URL、BACKEND_URL のように似た名前が混在すると、新しい人はもちろん、書いた本人でも後から迷いやすいです。環境変数はコードの外にあるぶん、IDEの補完や型の助けを受けにくいので、命名の整え方がかなり重要になります。

対策としては、接頭辞や用途を揃えることです。たとえば、DB_、API_、AUTH_ のように分けると読みやすくなります。チェック観点としては、「この名前だけで用途が分かるか」「似たものが複数ないか」を見ると、管理しやすい状態を保ちやすいです。

5-3. 本番だけ動かない原因になる設定漏れ

環境変数まわりでよくある障害は、ローカルでは動くのに本番だけ動かないことです。原因の多くは、本番側の設定漏れや値の違いです。

ローカルでは .env が読み込まれているのに、本番ではクラウド側の設定が足りない、変数名が少し違う、余分な空白が入っている、といったミスはかなり起きます。コードの問題に見えても、実際には設定ミスであることが少なくありません。環境変数は便利ですが、外に出したぶん、設定ミスもコード外で起こります。

対策としては、必須変数チェックを起動時に入れること、.env.example を最新に保つこと、本番環境の設定項目を一覧で管理することが有効です。特に「ローカルだけ動く」を減らすには、必要な環境変数名を人の記憶に頼らず、見える形で残すことが大切です。

6. まとめ

6-1. 環境変数で守れるもの

環境変数で守れるのは、秘密情報をコードへ直書きしないことと、環境ごとの設定を安全に切り替えることです。これだけでも、開発と運用のミスをかなり減らせます。

環境変数は、APIキーを完全に魔法のように守る仕組みではありません。しかし、Gitやコードレビューへ秘密情報を混ぜにくくし、開発環境と本番環境の差をコード変更なしで扱えるようにしてくれます。つまり、セキュリティと運用の両方を支える基本ルールです。

大事なのは、「秘密情報だから.envに入れる」だけで終わらず、「この値はどこで管理するべきか」「誰に見えてよいか」「環境ごとに変わるか」で分けて考えることです。環境変数は、小さな個人開発でも早めに身に付けておく価値のある習慣です。

6-2. 最低限のチェックリスト

最後に、初心者がまず押さえたい最低限のチェックポイントをまとめます。全部を完璧にやるより、この基本を外さないことが重要です。

チェック項目としては、「APIキーやDB接続情報をコードへ直書きしていないか」「.envを.gitignoreへ入れているか」「.env.exampleで必要な変数名を共有しているか」「本番は実行環境側で設定しているか」「必須環境変数が足りないときに起動時に分かるか」の5つをまず見るとよいです。

もし今のコードで不安があるなら、まずは秘密情報の直書きをやめて、.gitignoreと .env.example を整えるところから始めるのがおすすめです。環境変数は難しい仕組みではなく、最初に正しい形を覚えておくほど後で困りにくい基本です。

7. 参考リンク

関連記事