環境変数と.envによる設定と秘密情報の管理
データベースのパスワードやAPIキーをソースに直接書くと、リポジトリを見られた時点で漏れます。接続先を本番と開発で変えるたびにコードを書き換えるのも筋が悪いやり方です。設定を外に出す置き場所として、環境変数が使われます。
設定をコードから切り離す
The Twelve-Factor Appは、デプロイごとに変わる値をコードから分けて環境変数に置くことを求めています。
設定：デプロイ環境によって変わる値。データベースの認証情報、外部サービスの鍵、ホスト名などが該当します。
この原則が効くのは、同じコードのまま環境だけを差し替えられるからです。設定をソースに埋めると、環境を変えるたびにビルドし直すことになり、鍵がリポジトリに残ります。Twelve-Factor Appは「development」「production」のような名前で設定をひとまとめにする方法を、環境が増えると破綻するとして退けています。設定はまとめて名付けるのではなく、デプロイ単位で独立して渡します。
.envはローカルの便宜であってコミットしない
開発機で環境変数を毎回手で設定するのは面倒なので、.envファイルに書いて読み込む慣習が広まりました。dotenvは.envを読んでprocess.envに流し込むだけのライブラリで、アプリの最上位で一度呼びます。
ここで守る点が2つあります。.envは.gitignoreに入れてコミットしません。代わりに、キー名とダミー値だけを書いた.env.exampleを共有し、必要な変数を他の開発者に伝えます。値の実体はリポジトリに残さず、名前と形だけを共有します。
Node.js自身が.envを読めるようになった
.envの読み込みは長くライブラリの仕事でしたが、Node.js本体が--env-fileフラグを備えました。
node --env-file=.env app.jsこの機能はNode.js 20.6.0で実験的に入り、v22.21.0とv24.10.0で安定版に昇格しました。現行のLTSではもう実験的ではありません。ファイルが無いときにエラーを避けたい場合は--env-file-if-existsを使います。すでに設定済みの環境変数があれば、.envの値で上書きはされず、外から渡した値が優先されます。
ブラウザに届く環境変数は秘密にできない
フロントエンドのフレームワークには、特定の接頭辞を付けた環境変数だけをクライアントへ渡す仕組みがあります。ここを誤解すると秘密が公開されます。
Next.jsはNEXT_PUBLIC_、ViteはVITE_で始まる変数を、ビルド時にソースへ書き写します。Next.jsの公式はこれを「inline」、Viteは「static replace」と表現しています。つまり実行時に環境変数を読むのではなく、ビルドした時点の値がリテラルとしてバンドルに埋め込まれ、そのままブラウザへ届きます。
// サーバーでのみ参照できる
const dbUrl = process.env.DATABASE_URL;
// ビルド時に値が埋め込まれ、ブラウザから読める
const api = process.env.NEXT_PUBLIC_API_BASE; // Next.js
const key = import.meta.env.VITE_PUBLIC_KEY; // Vite接頭辞付きの変数に入れた値は、ブラウザの開発者ツールやJSソースから誰でも読めます。Viteの公式は「VITE_*に機微な情報を入れてはならない」と明記しています。公開してよい識別子だけを接頭辞付きにして、鍵やトークンは接頭辞なしのサーバー専用変数に置きます。ビルド時に焼き込まれる以上、デプロイ後に値を変えてもバンドルには反映されない点にも注意してください。
環境変数は暗号化ではない
環境変数に入れた値は平文で、プロセスから素通しで読めます。「環境変数に入れたから安全」とは言えません。OSのプロセス環境はその名のとおり環境に展開された文字列で、暗号化の層はありません。OWASPは秘密をログに出さないよう求めており、エラー出力やデバッグログに値をそのまま書くと、そこから漏れます。
本番では.envファイルに頼らず、クラウドのシークレット管理サービスを使います。アクセス制御、監査ログ、自動ローテーションが備わり、ファイルの取り回しで漏らす事故を避けられます。OWASPは、失効までの寿命が短い秘密ほど望ましいとしています。
秘密がリポジトリに入ってしまったら
.envや鍵をコミットしてしまうと、その後のコミットで消してもGitの履歴から取り出せます。履歴から削除するだけでは元に戻らないので、漏れた鍵は無効化して作り直します。
事故を未然に防ぐには、コミット前に秘密の混入を検知する仕組みを挟みます。OWASPはpre-commitフックでの検知を勧めており、detect-secretsのようなツールをコミット時に走らせると、鍵らしい文字列を止められます。
Cookieやトークンをブラウザ側で扱う設計の注意は、Cookie・セッション・SameSite の基礎も合わせて読むとつながります。
