.envファイルとは?書き方、作り方、APIキーを置くときの注意点

.envファイルは、KEY=value の行を並べただけのテキストファイルです。アプリの起動時にライブラリが読み込んで、環境変数として使えるようにします。設定をコードから切り離せるので便利ですが、本物のAPIキーを書けば、中身を平文のまま読めるファイルがコードのすぐ隣にあることになります。ポート番号のような設定なら問題ありません。危ないのは秘密の値を入れたときです。

最初にお断りしておくと、私たちはfideliusというMacアプリを開発しています。iCloudキーチェーンの上に作ったアプリで、独自の保管庫や同期の仕組みは持っていません。APIキーをシェルやプロジェクトのファイルに置かずに済むようにするためのものです。最後に紹介しますが、それまでの内容はfideliusを使わなくてもそのまま役に立ちます。

.envファイルの書き方

# 開発用の設定
PORT=3000
LOG_LEVEL=debug
DATABASE_URL=postgres://localhost/myapp
GREETING="hello world"
  • 1行に1つ、変数名=値 の形で書きます。変数名は英大文字とアンダースコアにするのが一般的です。
  • # で始まる行はコメントです。
  • 値に空白や # を含めるときは、引用符で囲みます。
  • = の前後には空白を入れないのが無難です。dotenvなら空白があっても読めますが、シェルで source .env すると、変数名がコマンドとして実行されてエラーになります。

考え方のもとになっているのは、The Twelve-Factor Appの「設定を環境変数に格納する」という原則です。判断の基準は、コードをいつ公開しても認証情報が漏れない状態になっているかどうかです。.envファイルは、その環境変数を手元のマシンで手軽に設定するための手段です。

.envファイルの作り方と置き場所

置き場所はプロジェクトのルート、つまり package.json や pyproject.toml と同じフォルダです。キーを書く前に .gitignore に追加しておけば、うっかりコミットせずに済みます。

$ cd ~/projects/myapp$ touch .env$ printf '\n.env\n' >> .gitignore$ ls -a

ドットで始まるファイルはFinderでは隠れています。Command + Shift + .(ピリオド)で表示と非表示を切り替えられます。それでも見つからないときは、ターミナルで ls -a を実行してください。

ツールごとの読み込み方

ツール読み込み方設定済みの環境変数が優先?
dotenv(Node.js)require("dotenv").config()はい(override: true のときを除く)
Node.jsnode --env-file=.env app.js。v20.6.0で追加され、v24.10.0とv22.21.0で安定版になりましたはい
python-dotenvload_dotenv()はい(override=True のときを除く)
Next.js自動で .env.$(NODE_ENV).local、.env.local、.env.$(NODE_ENV)、.env の順に探します(NODE_ENV=test のときは .env.local を読みません)はい(process.env が先)
Vite自動で .env、.env.local、.env.[mode]、.env.[mode].local を読みますはい

注目してほしいのは右の列です。デフォルトでは、すでに設定されている環境変数がファイルより優先されます。なので、コマンドの起動時に環境変数を渡すツールを使えば、たいていはコードを変えずに .envファイルをやめられます。ただし override を設定している箇所や、--env-file のようにファイルがある前提で書かれたコードやオプションがないかは確認してください。

ブラウザに漏れる変数

次の2つの接頭辞が付いた変数は、値がブラウザまで届きます。Next.jsは NEXT_PUBLIC_ で始まる変数をブラウザ向けのJavaScriptに埋め込みます。Viteは VITE_ で始まる変数をクライアントのコードから読めるようにします。どのファイルに書いたかは関係なく、この接頭辞が付いた値は公開されます。Viteのドキュメントでも、これらの変数にAPIキーのような機密情報を入れないよう注意を促しています。

Gitにコミットしていい?

平文のままならコミットしないでください。dotenvのREADMEには「.envファイルをコミットすべきか」という問いがあり、答えは「No」です。例外はdotenvxで暗号化したファイルだけです。Next.jsのドキュメントも、これらのファイルをリポジトリにコミットすべき場面はほとんどないとしています。代わりに、変数名とダミーの値だけを書いた .env.example をコミットして、何を設定すればいいかを共有します。もうコミットしてしまったなら、まずそのファイルにあったキーを無効にして、新しいキーを発行してください。

APIキーを書いたままにすると困る場面

ポート番号やログレベル、ローカルのURLなら .envファイルで十分です。ところが本物のAPIキーとなると、ファイルそのものが弱点になります。

  • AIコーディングエージェントは、いちいち確認せずにプロジェクトのファイルを読みます。Gemini CLIのように、自分で .env を読み込むものもあります。詳しくは「Claude Codeは.envファイルを読めるのか」(英語)に書きました。
  • ファイルはバックアップやzip、スクリーンショットに入り込み、このプロジェクトをコピーして始めた次のプロジェクトにまで付いていきます。
  • .gitignore がGitから守ってくれるのは、誰かが git add -f を実行するか、その行が消えるまでです。

環境変数そのものをやめる必要はありません。やめるのは、キーを書いたファイルのほうです。キーはキーチェーンやパスワードマネージャー、シークレット管理サービスに置いて、コマンドを起動するときに渡します。AIエージェントがコマンドの出力を読むなら、キーの値を伏せてくれるツールを使います。accio は、Claude CodeとCodexでは出力に出たキーの値を自動で伏せます。ほかのエージェントでは FIDELIUS_MASK=1 を設定すると有効になります。伏せる処理は確実ではありません。あくまで、うっかり表示されてしまったときの備えです。

$ accio myapp npm run dev