Gadget 53：workerd ランタイム素振り

Cloudflare の worker ランタイム workerd を単体で触って内部を理解する

workerd ランタイム素振り

pnpm run-local が裏で使う workerd を単体で動かし、ランタイムの挙動を体感します。

目的

  • workerd とは何か、Cloudflare OS がどう使っているかを理解する
  • Worker 単体の挙動を「最小構成」で再現する

前提条件

workerd とは

  • Cloudflare Workers ランタイムの本体（オープンソース）
  • wrangler dev の「裏」で動いているプロセス
  • run-local は workerd 上に Router + backend + 各 Gatekeeper をまとめて 起動する
# 起動中のプロセスを確認
ps aux | grep -E "workerd|wrangler" | grep -v grep

手順（最小の触り）

1. プロセスとフラグを観察

run-local 起動中に、workerd が受けている引数を確認します（構造理解のため）。

ps -o command -p <pid>   # コマンドラインを表示

2. Worker 単体で wrangler dev

# 自作の最小 Worker を別ディレクトリで
mkdir tiny && cd tiny && npx wrangler init
npx wrangler dev        # workerd 上で単体起動
  • 単体と run-local（マルチコンフィグ）の違いを体感
  • ポートが 8787 と衝突しないよう、別ポートで試す

3. 挙動を確認する

  • リクエストを投げて応答・エラーを見る
  • workerd のログ出力・リスタート挙動を観察

よくある失敗

症状 原因 対処
ポート衝突 8787 と競合 別ポート（例: 9797）へ
「workerd が見つからない」 PATH が小さい環境 wrangler 経由・node_modules 経由で起動
behavior が違う run-local 特有のマルチ構成 単体は単体、本番は本番で評価
壊れて戻すのが困難 実験で .wrangler を汚染 実験は別ディレクトリ（49）

確認

次に読む