.env ファイル

定義

.env ファイルは、環境変数を KEY=VALUE の形で 1 行ずつ書いたテキストファイル。
接続文字列や API キーなど、環境ごとに変わる値をコードの外に置くために使う。
OS やシェルが自動で読むものではなく、読み込むのは dotenv ライブラリや各フレームワーク・ツールである。

詳細

Node.js では dotenv ライブラリが .env を読んで process.env に流し込む。
Node.js 20.6.0 以降は node --env-file=.env app.js のように、ライブラリ無しでも読める。
Next.js や Vite は .env.local や .env.production など複数のファイルを決まった順で読み、ブラウザへ渡す変数には NEXT_PUBLIC_ や VITE_ の接頭辞を求める。
書式は # 以降がコメントになり、値に # を含めるときは引用符で囲む。

よくある誤解

• .env の値が一番強い: dotenv・--env-file・Vite・Next.js・Docker Compose のいずれも、起動時に既に設定されている環境変数を優先し、.env では上書きしない。
• Docker Compose の .env はコンテナに渡る: プロジェクト直下の .env は compose ファイル内の ${VAR} を展開するためのもの。
  コンテナの中で使うには environment: や env_file: で渡す（docker compose で env_file が読み込まれない）。

関連

値が読めないときの切り分けは Node.js で dotenv の値が読み込めない を参照。
秘密情報を含むため、.env は .gitignore でコミットから外しておく。