Gadget 50：.dev.vars を極める

run-local への環境変数注入の裏側と、環境切り替えを自在にする運用

.dev.vars を極める

run-local がどう .dev.vars を読み込むかを理解し、環境切替を自在にします。

目的

  • 注入のタイミング・優先順位を正確に理解する
  • 環境ごとに「どこで何を設定するか」を設計できる

前提条件

  • run-local の解剖（45）
  • 環境変数一覧（21）

注入の仕組み

  • run-local は起動時に .dev.vars（gitignored）を読み込み、各 Worker の設定へ注入
  • 起動時に反映されるため、編集後は再起動が必要
  • secret は .dev.vars だけでなく wrangler secret（本番デプロイ向け）もあり

環境切り替えの 3 段構え

層 例 用途
1 .dev.vars ローカル起動の設定
2 環境変数（シェル） 実行時の上書きや一時的値
3 wrangler secret put 本番デプロイの秘密 
# シェル変数でも一部上書きできる（プロセス環境）
VITE_BACKEND_HOST=localhost:9200 pnpm run-local

使い分けの設計

値の性質 置き場所 理由
ローカルのみの開発用 .dev.vars 起動ごとに読み込まれる
実行時の切替 シェル環境変数 一時的・インスタンス単位（49）
本番用秘密 wrangler secret リポジトリに残さない
公開してよい雛形 .env.example 値を入れないテンプレ

よくある失敗

症状 原因 対処
反映されない 再起動していない 編集→再起動
本番に漏れる 本番値を .dev.vars に記載 本番は secret で管理
変えたつもりが拾えない 誤った環境層で指定 層（dev.vars/env/secret）を確認
余白・引用符で壊れる パース誤り 不要な "/空白を入れない

確認

次に読む