Cloudflare Workers の TypeScript デプロイエラーを4層に切り分けて直す手順

結論: エラーメッセージを「4層」に振り分ければ原因はほぼ一意に決まる

wrangler deploy が落ちたとき、闇雲に tsconfig.json をいじるのは遠回りだ。Workers のデプロイ失敗は次の4層のどれかに必ず属する。まずメッセージを見て層を確定させ、その層の定石だけを試す。これが最短ルートになる。

層	代表的なメッセージ	主因	打ち手
①型チェック	Property 'DB' does not exist on type 'Env'	型定義と設定ファイルの不一致	wrangler types で再生成
②バンドル	Could not resolve "node:crypto"	Node.js 組み込みモジュール参照	nodejs_compat を有効化
③バインディング	binding DB of type d1 not found	wrangler 設定の記述漏れ	設定ファイルとダッシュボードを照合
④実行時	デプロイは成功するが 1101 / 500	型が通っても実体がない	wrangler tail でログを見る

前提: wrangler deploy は型チェックをしていない

最初に押さえるべき事実がある。wrangler の内部バンドラ（esbuild）は型を落とすだけで検証しない。つまり any だらけの壊れたコードでもデプロイは通る。

逆に言えば、wrangler deploy が出すエラーの多くは型エラーではなく**解決エラー（バンドル層）**だ。ここを混同すると、型定義をいじり続けて何時間も溶かすことになる。型の担保は別途 tsc で行う。

// package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "predeploy": "npm run typecheck",
    "deploy": "wrangler deploy"
  }
}

predeploy を挟むだけで、型崩れしたコードが本番に出るのを防げる。

①型層: Env の型は手書きせず生成する

D1 や KV を追加したのに Env に生えていない、というのが最頻出だ。手書きの interface Env は設定ファイルとすぐ乖離する。wrangler の型生成コマンドを使うのが正解だ。

npx wrangler types

生成された worker-configuration.d.ts を tsconfig.json の include に入れ、自前の Env 定義は消す。バインディングを足したら再生成する、を習慣にする。

// tsconfig.json（要点のみ）
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "types": ["./worker-configuration.d.ts"],
    "strict": true,
    "noEmit": true
  },
  "include": ["src/**/*.ts", "worker-configuration.d.ts"]
}

注意点が2つある。

• types に node を混ぜると setTimeout の戻り値型などが Node 版で上書きされ、原因の分かりにくい型エラーになる
• lib に DOM を入れると Workers に無い API まで補完に出てくる。実行時に落ちる型エラーの温床になる

②バンドル層: Could not resolve は互換フラグを疑う

node:buffer や node:crypto、あるいはそれらに依存する npm パッケージを読むとバンドルで止まる。Workers はデフォルトで Node.js API を持たないためだ。

// wrangler.jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"]
}

ここで正直に書いておくと、nodejs_compat は Node.js の全 API を再現するものではない。ファイルシステムや子プロセスは動かない。フラグの挙動は compatibility_date の値によっても変わるため、対応 API 一覧と必要な日付の下限は Cloudflare 公式ドキュメントの最新情報を必ず確認してほしい。

そもそも Node.js 依存が深いライブラリは、Workers 対応の代替に置き換えたほうが早いことも多い。バンドルサイズにも上限があるので、重い依存を無理に持ち込むと別の壁に当たる。

常駐プロセスやファイル書き込みが本質的に必要な処理は、Workers に載せ替えるより VPS に置いたほうが素直だ。その手の逃げ道を1つ持っておくと設計判断が速くなる。

③バインディング層: 型が通っても実体は別

wrangler types は設定ファイルを読んで型を作る。だから設定ファイルに書いた時点で型は通る。実体のリソースが作られていなければ、デプロイ時か実行時に落ちる。

切り分け手順はこうだ。

1. npx wrangler d1 list などでリソースの実在を確認する
2. database_id や KV の id が設定ファイルの値と一致しているか確認する
3. Secrets は wrangler secret put で別途登録する（設定ファイルに書いても反映されない）
4. 環境ごとに分けているなら --env 指定と設定ブロックの対応を確認する

④実行時層: デプロイ成功後の 1101 はログで見る

ビルドが通って本番で落ちる場合、静的解析ではもう追えない。ストリーミングでログを見る。

npx wrangler tail --format pretty

env.DB が undefined、外部 fetch のタイムアウト、CPU 時間超過あたりが典型だ。ローカルの wrangler dev は本番と挙動が完全一致しないため、ローカルで動いた＝本番で動く、とは考えないほうがいい。

まとめ: 恒久対策は3点セット

• wrangler types の再生成をバインディング追加時のルーチンにする
• tsc --noEmit を predeploy と CI の両方に入れる
• compatibility_date を固定し、上げるときは単独のコミットにする

型エラーのメッセージ自体が読めないと切り分けの精度が落ちる。基礎を固め直すなら

のような一冊を手元に置いておくと、この手の調査が一気に速くなる。

なお wrangler はバージョンによってコマンド体系や設定キーが変わることがある。手順が噛み合わないと感じたら、まず npx wrangler --version を確認し、公式ドキュメントの該当バージョンを参照してほしい。