ToolNote
💡 Tips

Cloudflare Workersでprocess.envが使えない理由と環境変数の正しい扱い方

Node.js の感覚で Cloudflare Workers に process.env.API_KEY と書いたら undefined で詰まった——これは Workers では設計上の正しい挙動だ。結論から言うと、Workers の環境変数は process.env には載らず、リクエストごとに渡される env バインディング経由でアクセスする。この記事では、なぜそうなるのか、そして一番ハマりやすい「グローバル定数パターン」の回避策までを解説する。

なぜ process.env が使えないのか

Cloudflare Workers は Node.js ではなく、V8 isolate ベースの独自ランタイムで動く。Node.js のグローバルな process オブジェクトは標準では存在しない（互換フラグで部分的に補えるが、環境変数は別物）。

代わりに Workers では、設定した変数やシークレットが ハンドラの引数 env として渡ってくる。

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // ✅ 正しい: env 経由でアクセス
    const apiKey = env.API_KEY;
    return new Response('ok');
  },
};

一番ハマるのは「グローバル定数」パターン

実は単純な置き換えより厄介なのが、モジュールのトップレベルで環境変数を読もうとする書き方だ。

// ❌ 動かない: モジュール読み込み時には env が存在しない
const API_KEY = process.env.API_KEY;
const client = new SomeClient(API_KEY);

export default {
  async fetch(request: Request, env: Env) {
    return client.doSomething();
  },
};

Workers では、リクエストを受けて初めて env が手に入る。モジュールのトップレベル（＝コールドスタート時）には環境変数はまだ無い。そのためグローバル定数に環境変数を焼き込む設計そのものが破綻する。

回避策: リクエストごとに env を受け取って渡す

クライアントの生成を fetch の中に移すか、env を引数として引き回す設計にする。

function createClient(env: Env) {
  return new SomeClient(env.API_KEY);
}

export default {
  async fetch(request: Request, env: Env) {
    const client = createClient(env);
    return client.doSomething();
  },
};

「設定はグローバル定数で持つ」という Node.js 由来の癖を捨てて、env を関数の引数で受け渡す設計に切り替えるのがポイントだ。

公開情報とシークレットを分ける

Workers の変数には2種類ある。混同するとシークレットが漏れるので注意したい。

種類設定方法用途
平文変数 (vars)wrangler.jsonc の vars公開してよい設定値のみ
シークレットwrangler secret put KEYAPIキー等の機密情報
# シークレットの登録（Worker作成後に実行する）
npx wrangler secret put API_KEY

wrangler.jsonc の vars に書いた値はビルド成果物やダッシュボードから見えてしまうので、機密情報は必ず secret put を使うこと。

wrangler の環境設定でもう一つの落とし穴

wrangler.jsonc で env ブロック（本番・ステージング等）を切る場合、トップレベルの設定は自動継承されない。main・vars・assets などは各環境で明示的に書き直す必要がある。「本番だけ変数が空」というハマりはこれが原因のことが多い。

さらに学ぶなら

Workers をはじめとするエッジ/サーバーレスの設計思想を体系的に押さえておくと、こうした「ランタイムの前提が違う」系のハマりを一気に減らせる。基礎から手を動かして学ぶなら、オンラインのプログラミングスクールで体系立てて学ぶのも近道だ。

📚 おすすめ書籍

Cloudflare Workers&Pages実践ガイド

エッジコンピューティングを体系的に学ぶ一冊

Amazonで見る →
🔗 おすすめサービス 国内シェアNo.1のエックスサーバーが提供するVPSサーバー『XServer VPS』

まとめ

  • Workers では process.env は使えない。env バインディング経由でアクセスする
  • グローバル定数に環境変数を焼き込む設計は破綻する。env を引数で引き回す
  • 機密情報は vars ではなく wrangler secret put で登録する
  • env ブロックはトップレベル設定を継承しないので明示する
#Cloudflare #Workers #TypeScript #環境変数