Bunが.envファイルを自動で読み込む順番と優先される値
Bun は、.env ファイルを何も設定しなくても読み込みます。.env のほかに .env.development や .env.local なども読み、同じ名前の変数があれば、決まった順番であとから読んだファイルの値が使われます。
開発用と本番用で API キーやデータベースの接続先を分けたい、.env に書いたのに環境変数が反映されない、というときは、この順番と例外を知っておくと原因を絞り込めます。すべてのファイルに同じ変数を書いて、どの値が残るかを実際に確かめました。
検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。Node.js のスクリプトは Node.js 22 で動かしました。シェルの環境変数が結果に混ざらないよう、env -i で環境変数をほぼ空にしてから実行しました。Windows と macOS、bun install での読み込み、bun --bun で Node.js として動かす場合は試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。
読む順番は4段階で、あとのファイルの値が残る
公式ドキュメントの環境変数のページには、自動で読むファイルが、優先度の低い順に次のように書かれています。
.env.env.production、.env.development、.env.test(NODE_ENVの値によって1つ).env.local(NODE_ENV=testのときは読まない).env.production.local、.env.development.local、.env.test.local(NODE_ENVの値によって1つ)
これを確かめるため、8つのファイルすべてに WHO=ファイル名 を書き、読む段階ごとに別の変数(IN_ENV、IN_MODE、IN_LOCAL、IN_MODE_LOCAL)も書きました。たとえば .env.development の中身は次のとおりです。
WHO=.env.development
IN_MODE=development
値を表示するだけの show.ts を用意しました。
const keys = ["NODE_ENV", "WHO", "IN_ENV", "IN_MODE", "IN_LOCAL", "IN_MODE_LOCAL"];
for (const k of keys) console.log(`${k}=${process.env[k] ?? "(なし)"}`);
NODE_ENV を付けずに実行すると、WHO には .env.development.local の値が残りました。ほかの変数を見ると、4つのファイルをすべて読んでいることが分かります。
$ bun show.ts
NODE_ENV=(なし)
WHO=.env.development.local
IN_ENV=yes
IN_MODE=development
IN_LOCAL=yes
IN_MODE_LOCAL=development
.env.development.local、.env.local、.env.development の順に1つずつファイルを消していくと、WHO の値は .env.local、.env.development、.env の順に移りました。ドキュメントの順番どおりです。

NODE_ENV の値で読むファイルが変わり、付けないと development を読む
NODE_ENV の値を変えて同じ show.ts を実行した結果をまとめると、次のようになりました。
| 実行のしかた | WHO の値 |
.env.local |
|---|---|---|
bun show.ts |
.env.development.local |
読む |
NODE_ENV=production bun show.ts |
.env.production.local |
読む |
NODE_ENV=test bun show.ts |
.env.test.local |
読まない |
NODE_ENV=staging bun show.ts |
.env.development.local |
読む |
NODE_ENV を付けないときは、development 用のファイルを読みました。このとき process.env.NODE_ENV は設定されないままで、development という値は入りません。対応するファイルのない staging を指定したときも、development 用のファイルを読んでいます。
本番用の値を .env.production に書いた場合は、起動するときに NODE_ENV=production を付けないと読まれません。
.env に書いた NODE_ENV では、読むファイルは変わらない
.env の最後に NODE_ENV=production を書き足して、NODE_ENV を付けずに実行しました。
$ bun show.ts
NODE_ENV=production
WHO=.env.development.local
IN_ENV=yes
IN_MODE=development
IN_LOCAL=yes
IN_MODE_LOCAL=development
process.env.NODE_ENV は production になりましたが、読んだのは development 用のファイルでした。どのファイルを読むかは、Bun を起動したときの NODE_ENV で決まります。
シェルで渡した値は、.env の値より優先される
コマンドの前に WHO=shell を付けて実行すると、.env.development.local の値ではなく shell が使われました。WHO= のように空の値を渡したときも、.env の値で埋められることはなく、空のままでした。
$ WHO=shell bun show.ts
NODE_ENV=(なし)
WHO=shell
IN_ENV=yes
IN_MODE=development
IN_LOCAL=yes
IN_MODE_LOCAL=development
$ WHO= bun show.ts
NODE_ENV=(なし)
WHO=
IN_ENV=yes
IN_MODE=development
IN_LOCAL=yes
IN_MODE_LOCAL=development
CI やサーバーで環境変数を設定している場合、同じ名前の変数が .env にあっても上書きされません。逆に、シェルに古い値が残っていると、.env を書き換えても反映されないように見えます。
bun test は .env.test を読み、.env.local は読まない
bun test の中から同じ変数を表示すると、NODE_ENV は test になり、.env.test と .env.test.local を読んでいました。.env.local の値(IN_LOCAL)は入っていません。
$ bun test env.test.ts
bun test v1.4.4 (38afee6c8)
env.test.ts:
NODE_ENV=test
WHO=.env.test.local
IN_MODE=test
IN_LOCAL=(なし)
IN_MODE_LOCAL=test
手元の開発用の値を .env.local に書いておけば、テストには混ざりません。テストだけで使う値は .env.test に書きます。
テストの実行時の動きを説明したページには、NODE_ENV が環境変数か .env ファイルで設定されていれば、bun test はそれを test に変えない、と書かれています。ところが、.env に NODE_ENV=development を書き足して bun test を実行しても、結果は上と同じで、NODE_ENV は test のままでした。コマンドの前に NODE_ENV=development や NODE_ENV=production を付けて bun test を実行すると、process.env.NODE_ENV はその値になりました。ただし、読んだファイルはどちらも .env.test と .env.test.local のままでした。
$ NODE_ENV=development bun test env.test.ts
bun test v1.4.4 (38afee6c8)
env.test.ts:
NODE_ENV=development
WHO=.env.test.local
IN_MODE=test
IN_LOCAL=(なし)
IN_MODE_LOCAL=test
読むのは、コマンドを実行したフォルダの .env
.env を探す場所は、スクリプトのファイルがあるフォルダではなく、bun を実行したフォルダでした。プロジェクトのフォルダに sub というフォルダを作り、WHO=sub/.env だけを書いた .env と show.ts の写しを置いて試しました。
| 実行したフォルダ | コマンド | WHO の値 |
|---|---|---|
| プロジェクトのフォルダ | bun sub/show.ts |
.env.development.local |
sub |
bun show.ts |
sub/.env |
sub |
bun ../show.ts |
sub/.env |
| プロジェクトのフォルダ | bun --cwd sub show.ts |
sub/.env |
sub で実行したときは、1つ上のフォルダにある .env.local などは読まれず、IN_ENV などの変数は「(なし)」になりました。親のフォルダまでさかのぼって探すことはありません。別のフォルダから実行するときは、--cwd でプロジェクトのフォルダを指定します。
package.json のスクリプトには、.env の値が渡らなかった
package.json に次の3つのスクリプトを書いて、bun run で実行しました。
{
"name": "env-demo",
"private": true,
"scripts": {
"show": "bun show.ts",
"print": "printenv WHO || echo 'WHO はありません'",
"node-print": "node print-env.mjs"
}
}
print-env.mjs は、process.env.WHO を表示するだけの Node.js のスクリプトです。
console.log(`WHO=${process.env.WHO}`);
bun run show は、中で起動した bun show.ts が自分で .env を読むので、これまでと同じ値が表示されました。一方、シェルのコマンドで環境変数を表示する bun run print と、Node.js で動かす bun run node-print には、.env の値が渡っていませんでした。--env-file を付けたときは、指定したファイルの値が渡りました。
$ bun run print
$ printenv WHO || echo 'WHO はありません'
WHO はありません
$ bun --env-file=.env.local run print
$ printenv WHO || echo 'WHO はありません'
.env.local
$ bun run node-print
$ node print-env.mjs
WHO=undefined
$ bun --env-file=.env.local run node-print
$ node print-env.mjs
WHO=.env.local
公式ドキュメントの --env-file の説明にも、このオプションは package.json のスクリプトの実行に使えると書かれています。Bun 以外のコマンド(シェルのコマンドや Node.js のスクリプト)に .env の値を渡したいときは、--env-file で明示します。
–env-file を付けると、決まったファイルは読まなくなる
--env-file を付けると、上の4段階のファイルは読まれず、指定したファイルだけを読みました。複数を指定したときは、あとに書いたファイルの値が残ります。シェルで渡した値が優先されるのは、このときも同じでした。
show2.ts は、show.ts と同じように WHO、IN_ENV、IN_MODE、IN_LOCAL、IN_CUSTOM を表示するだけのファイルです。custom.env には WHO=custom.env と IN_CUSTOM=yes、second.env には WHO=second.env だけを書きました。
$ bun --env-file=custom.env show2.ts
WHO=custom.env
IN_ENV=(なし)
IN_MODE=(なし)
IN_LOCAL=(なし)
IN_CUSTOM=yes
$ bun --env-file=custom.env --env-file=second.env show2.ts
WHO=second.env
IN_ENV=(なし)
IN_MODE=(なし)
IN_LOCAL=(なし)
IN_CUSTOM=yes
存在しないファイルを --env-file=nothing.env で指定しても、エラーにはならず、終了コードは 0 でした。このとき、どの .env ファイルの値も入りません。ファイル名を打ち間違えると、設定がないまま気づかずに動くことになります。
自動の読み込みをすべて止めるには、--no-env-file を付けるか、bunfig.toml に env = false と書きます。どちらの場合も、.env の値は1つも入りませんでした。--no-env-file と --env-file=custom.env を一緒に付けたときは、custom.env だけを読みました(自動の読み込みを止める方法の説明)。
.env の値に書いた $ 付きの変数は、ほかの値に置き換わる
.env の値に $HOST のように書くと、ほかの変数の値で置き換えられます(公式ドキュメントにある、変数の展開の説明)。データベースの接続先 URL のように、いくつかの値を組み合わせるときに使えます。次の .env で試しました。LOCAL_ONLY は .env.local のほうに書いています。
HOST=localhost
PORT=5432
DB_URL=postgres://$HOST:$PORT/app
BRACE=${HOST}_db
ESCAPED=price\$HOST
SINGLE='$HOST'
DOUBLE="$HOST"
LATER=$DEFINED_LATER
DEFINED_LATER=yes
FROM_LOCAL=$LOCAL_ONLY
PASSWORD=pa$sword
PASSWORD_ESCAPED=pa\$sword
結果は次のとおりです(値は JSON.stringify で表示しています)。
$ bun expand.ts
DB_URL="postgres://localhost:5432/app"
BRACE="localhost_db"
ESCAPED="price$HOST"
SINGLE="localhost"
DOUBLE="localhost"
LATER="yes"
FROM_LOCAL="from-local"
PASSWORD="pa"
PASSWORD_ESCAPED="pa$sword"
\$ と書いたところだけが、$HOST という文字のまま残りました。シングルクォートで囲んでも展開されます。また、公式ドキュメントでは「前に定義した変数」を参照できると説明されていますが、後ろの行で定義した変数(LATER)や、別のファイルで定義した変数(FROM_LOCAL)も参照できました。
シェルで HOST=example.com を付けて実行すると、DB_URL は postgres://example.com:5432/app になりました。展開にも、シェルで渡した値が使われます。
PASSWORD のように、$ を含む値をそのまま書くと、$sword が定義されていない変数として空の文字列に置き換わり、値は pa だけになりました。パスワードやトークンに $ が入っているときは、PASSWORD_ESCAPED のように \$ と書きます。
ここまでの値は、process.env のほかに Bun.env と import.meta.env からも読めます。検証環境では、3つとも同じオブジェクトでした(Bun.env === process.env が true)。





