cloudflare-worker-base

Cloudflare Worker ベーススタック

本番環境でテスト済み：cloudflare-worker-base-test (https://cloudflare-worker-base-test.webfonts.workers.dev) 最終更新日：2026-01-20 ステータス：本番環境で使用可能 ✅ 最新バージョン：[email protected], @cloudflare/[email protected], [email protected], [email protected] スキルバージョン：3.1.0

最近の更新（2025-2026）：

• Wrangler 4.55+：フレームワークの自動設定（wrangler deploy --x-autoconfig）
• Wrangler 4.45+：R2、D1、KV バインディングの自動プロビジョニング（デフォルトで有効）
• Workers RPC：サービスバインディング向けの WorkerEntrypoint クラスによる JavaScript ネイティブ RPC
• 2025年3月：Wrangler v4 リリース（破壊的変更は最小限、v3 は 2027年第1四半期までサポート）
• 2025年6月：ダッシュボードからネイティブインテグレーションを削除（wrangler secrets を使う CLI ベースの方法に移行）
• 2025年のプラットフォーム：Workers VPC Services、Durable Objects Data Studio、環境変数 64 個（各 5KB）、Worker ごとの Cron Trigger 数が無制限、WebSocket メッセージ 32 MiB、node:fs/Web File System API
• 2025年の静的アセット：段階的ロールアウト時のアセット不一致の問題、run_worker_first 使用時に無料プランで発生する 429 エラー、Vite プラグインの自動検出
• Hono 4.11.x：TypeScript RPC の型推論強化、cloneRawRequest ユーティリティ、JWT aud 検証、認証ミドルウェアの改善

---

クイックスタート（5分）

# 1. Scaffold project
npm create cloudflare@latest my-worker -- --type hello-world --ts --git --deploy false --framework none

# 2. Install dependencies
cd my-worker
npm install [email protected]
npm install -D @cloudflare/[email protected] [email protected]

# 3. Create wrangler.jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "account_id": "YOUR_ACCOUNT_ID",
  "compatibility_date": "2025-11-11",
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]  // CRITICAL: Prevents SPA fallback from intercepting API routes
  }
}

# 4. Create vite.config.ts
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
export default defineConfig({ plugins: [cloudflare()] })

# 5. Create src/index.ts
import { Hono } from 'hono'
type Bindings = { ASSETS: Fetcher }
const app = new Hono<{ Bindings: Bindings }>()
app.get('/api/hello', (c) => c.json({ message: 'Hello!' }))
app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw))
export default app  // CRITICAL: Use this pattern (NOT { fetch: app.fetch })

# 6. Deploy
npm run dev              # Local: http://localhost:8787
wrangler deploy          # Production

重要な設定：

• run_worker_first: ["/api/*"] — これがないと SPA フォールバックが API ルートを横取りし、JSON の代わりに index.html を返します（workers-sdk #8879）
• export default app — { fetch: app.fetch } を使うと「Cannot read properties of undefined」が発生します（honojs/hono #3955）

既知の問題の予防

このスキルでは、文書化されている10件の問題を予防します。

問題 #1：エクスポート構文エラー

エラー：「Cannot read properties of undefined (reading 'map')」 出典：honojs/hono #3955 予防策：export default app を使用します（{ fetch: app.fetch } は使用しないでください）

問題 #2：静的アセットのルーティング競合

エラー：API ルートが JSON の代わりに index.html を返す 出典：workers-sdk #8879 予防策：wrangler.jsonc に "run_worker_first": ["/api/*"] を追加します

問題 #3：Scheduled/Cron がエクスポートされない

エラー：「Handler does not export a scheduled() function」 出典：honojs/vite-plugins #275 予防策：必要に応じて Module Worker 形式を使用します：

export default {
  fetch: app.fetch,
  scheduled: async (event, env, ctx) => { /* ... */ }
}

問題 #4：HMR の競合状態

エラー：開発中に「A hanging Promise was canceled」 出典：workers-sdk #9518 予防策：@cloudflare/[email protected] 以降を使用します

問題 #5：静的アセットのアップロード競合

エラー：CI/CD でデプロイに非決定的な失敗が発生する 出典：workers-sdk #7555 予防策：リトライロジックを備えた Wrangler 4.x 以降を使用します（最近のバージョンで修正済み）

問題 #6：Service Worker 形式の混乱

エラー：非推奨の Service Worker 形式を使用している 出典：Cloudflare 移行ガイド 予防策：常に ES Module 形式を使用します

Issue #7: 段階的ロールアウト時のアセット不一致 (2025)

エラー: 段階的デプロイ中のフィンガープリント付きアセットに対する 404 エラー 出典: Cloudflare Static Assets Docs 発生理由: モダンなフレームワーク（Vite を使用した React/Vue/Angular）はフィンガープリント付きのファイル名（例: index-a1b2c3d4.js）を生成します。バージョン間の段階的ロールアウト中に、ユーザーの最初のリクエストがバージョン A に到達し（HTML は index-a1b2c3d4.js を参照）、その後のアセットリクエストがバージョン B にルーティングされる（index-m3n4o5p6.js しか存在しない）と、404 が発生します 防止策:

• フィンガープリント付きアセットを使用する場合は段階的デプロイを避ける
• 静的サイトには即時切り替えデプロイを使用する
• またはカスタムロジックによるバージョン対応ルーティングを実装する

Issue #8: 無料枠での run_worker_first による 429 エラー (2025)

エラー: 無料枠の制限を超過した際のアセットリクエストに対する 429 (Too Many Requests) レスポンス 出典: Cloudflare Static Assets Billing Docs 発生理由: run_worker_first を使用すると、指定したパターンに一致するリクエストは常に Worker スクリプトを呼び出します（無料枠の制限にカウントされます）。制限を超過すると、これらのリクエストは無料の静的アセット配信にフォールバックせず、429 を受け取ります 防止策:

• 無制限のリクエストには Workers Paid プラン（月額 $5）にアップグレードする
• ネガティブパターン（!/pattern）を使用して Worker 呼び出しからパスを除外する
• run_worker_first のパターンを必須の API ルートのみに最小化する

Issue #9: Vite 8 が require() で nodejs_compat を壊す

エラー: Calling require for "buffer" in an environment that doesn't expose the require function 出典: workers-sdk #11948 影響を受けるバージョン: Vite 8.x と @cloudflare/vite-plugin 1.21.0 以降 発生理由: Vite 8 は Rolldown バンドラーを使用しており、外部モジュールに対して require() を import に変換しません。Workers は require() 関数を公開していないため、Node 組み込みモジュールのインポートが実行時に失敗します。 防止策:

// vite.config.ts - Add esmExternalRequirePlugin
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import { esmExternalRequirePlugin } from 'vite'
import { builtinModules } from 'node:module'

export default defineConfig({
  plugins: [
    cloudflare(),
    esmExternalRequirePlugin({
      external: [/^node:/, ...builtinModules],
    }),
  ],
})

ステータス: 回避策あり。Vite チームが修正に取り組んでいます (vitejs/vite#21452)。

Issue #10: Vite の base オプションが SPA ルーティングを壊す (1.13.8 以降)

エラー: curl http://localhost:5173/prefix が index.html ではなく 404 を返す 出典: workers-sdk #11857 影響を受けるバージョン: @cloudflare/vite-plugin 1.13.8 以降 発生理由: プラグインがベースパスを含む完全な URL を Asset Worker に渡すようになりました（本番環境の動作に合わせています）。assets.base のプラットフォームサポートはまだ利用できません。 防止策（開発モードでの回避策）:

// worker.ts - Strip base path in development
if (import.meta.env.DEV) {
  url.pathname = url.pathname.replace(import.meta.env.BASE_URL, '');
  if (url.pathname === '/') {
    return this.env.ASSETS.fetch(request);
  }
  request = new Request(url, request);
}

ステータス: 開発環境を本番環境に合わせるための意図的な変更です。プラットフォーム機能 assets.base は 2026 年第 1 四半期に予定されています (workers-sdk #9885)。

run_worker_first によるルートの優先順位

重要な理解: "not_found_handling": "single-page-application" は未知のルートに対して index.html を返します（React Router、Vue Router を有効にします）。run_worker_first がない場合、これが API ルートを横取りしてしまいます！

run_worker_first: ["/api/*"] を使用したリクエストルーティング:

1. /api/hello → Worker が処理（JSON を返す）
2. / → Static Assets が index.html を配信
3. /styles.css → Static Assets が styles.css を配信
4. /unknown → Static Assets が index.html を配信（SPA フォールバック）

Static Assets のキャッシュ: 自動エッジキャッシュ。クエリ文字列でキャッシュを無効化: <link href="/styles.css?v=1.0.0">

無料枠の警告 (2025): run_worker_first のパターンは無料枠の制限にカウントされます。超過後は、無料の静的アセットにフォールバックせず、リクエストが 429 を受け取ります。ネガティブパターン（!/pattern）を使用するか、Paid プランにアップグレードしてください。

自動プロビジョニング（Wrangler 4.45+）

デフォルトの動作：デプロイ時に、Wrangler は R2 バケット、D1 データベース、KV 名前空間を自動的にプロビジョニングします。これにより、リソースを手動で作成する手順が不要になります。

重要：リソース名は必ず指定してください

⚠️ エッジケース（workers-sdk #11870）：binding のみを指定し、database_name／bucket_name を指定しない場合、Wrangler はバインディング名をリソース名として使用します。その結果、wrangler dev やサブコマンドで動作が分かりにくくなることがあります。これらは database_id → database_name → binding の順に優先します。

// ❌ DON'T: Binding-only creates database named "DB"
{
  "d1_databases": [{ "binding": "DB" }]
}

// ✅ DO: Explicit names prevent confusion
{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-app-db"  // Always specify!
    }
  ],
  "r2_buckets": [
    {
      "binding": "STORAGE",
      "bucket_name": "my-app-files"  // Always specify!
    }
  ],
  "kv_namespaces": [
    {
      "binding": "CACHE",
      "title": "my-app-cache"  // Always specify!
    }
  ]
}

# Deploy - resources auto-provisioned if they don't exist
wrangler deploy

# Disable auto-provisioning (use existing resources only)
wrangler deploy --no-x-provision

メリット：

• wrangler d1 create／wrangler r2 create の個別実行が不要です
• 冪等性があります。既存のリソースが使用され、再作成されません
• ローカル開発でも動作します（wrangler dev がエミュレートされたローカルリソースを作成します）

Workers RPC（サービスバインディング）

概要：Workers 間でメソッドを呼び出すための、JavaScript ネイティブの RPC システムです。内部では Cap'n Proto を使用し、ゼロコピーのメッセージパッシングを実現します。

用途：アプリケーションを複数の Worker（例：API Worker + Auth Worker + Email Worker）に分割し、型安全なメソッドで相互に呼び出せるようにします。

RPC サービスの定義：

import { WorkerEntrypoint } from 'cloudflare:workers'

export class AuthService extends WorkerEntrypoint<Env> {
  async verifyToken(token: string): Promise<{ userId: string; valid: boolean }> {
    // Access bindings via this.env
    const session = await this.env.SESSIONS.get(token)
    return session ? { userId: session.userId, valid: true } : { userId: '', valid: false }
  }

  async createSession(userId: string): Promise<string> {
    const token = crypto.randomUUID()
    await this.env.SESSIONS.put(token, JSON.stringify({ userId }), { expirationTtl: 3600 })
    return token
  }
}

// Default export still handles HTTP requests
export default { fetch: ... }

別の Worker からの呼び出し：

// wrangler.jsonc
{
  "services": [
    { "binding": "AUTH", "service": "auth-worker", "entrypoint": "AuthService" }
  ]
}

// In your main Worker
const { valid, userId } = await env.AUTH.verifyToken(authHeader)

要点：

• 遅延ゼロ：同じアカウント上の Workers は通常、同じスレッドで実行されます
• 型安全：メソッドシグネチャを完全に TypeScript でサポートします
• 32 MiB の上限：シリアライズされた RPC メッセージの最大サイズです
• セルフバインディング：wrangler dev では、同一 Worker の呼び出しに対して [connected] と表示されます

トラブルシューティング

開発中に「Response Already Sent」エラーがランダムに発生する

症状：wrangler dev の実行中に、ResponseSentError: The response has already been sent to the browser and cannot be altered が断続的に発生します 参照元：workers-sdk #11932 原因：.wrangler ディレクトリ内のキャッシュ破損、または古い Vite キャッシュ

解決方法：

# Clear all caches
rm -rf .wrangler dist node_modules/.vite

# Rebuild
npm run build

# Recreate local D1 databases if needed
wrangler d1 execute DB --local --file schema.sql

対象：Wrangler 4.x のフル Workers モード（Cloudflare Pages は対象外）

コミュニティのヒント

注：これらのヒントはコミュニティでの議論に基づいています。ご利用のバージョンで確認してください。

React SSR では vite-tsconfig-paths v6 を避ける

参照元：workers-sdk #11825（コミュニティ提供）

@cloudflare/vite-plugin で React SSR を使用する場合は、[email protected] に固定してください：

npm install [email protected]

理由：バージョン 6.x は依存関係のスキャン中にパスエイリアスを処理しないため、React のインスタンスが重複し、「Invalid hook call」エラーが発生します。

対象：React SSR で TypeScript のパスエイリアスを使用するプロジェクト

uuid パッケージではなく crypto.randomUUID() を使用する

参照元：workers-sdk #11957

uuid@11 パッケージ（ESM）は、Workers で「fileURLToPath undefined」という実行時クラッシュを引き起こすことがあります。代わりに、ネイティブの Web Crypto API を使用してください：

// ✅ Native Workers API (recommended)
const uuid = crypto.randomUUID();

// ❌ Avoid uuid package in Workers
import { v4 as uuidv4 } from 'uuid';  // May crash

対象：UUID が必要なすべての Workers プロジェクト

コマンド

/deploy - ワンコマンドのデプロイパイプライン

使用するタイミング：Cloudflare Worker のコミット、プッシュ、デプロイを一度に行う準備ができたときに使用します。

実行内容：

1. 事前確認：wrangler の設定を検証し、変更を確認して、ビルドと TypeScript チェックを実行します
2. コミットとプッシュ：変更をステージングし、Conventional Commits 形式のコミットメッセージを生成して、リモートにプッシュします
3. デプロイ：wrangler deploy を実行し、Worker の URL を取得します
4. レポート：コミットハッシュ、ブランチ、デプロイされた URL、警告を表示します

所要時間の短縮：デプロイサイクルごとに 2～3 分

処理されるエッジケース：

• コミットする変更がない場合 → デプロイに進みます
• ビルドスクリプトがない場合 → 警告を表示して続行します
• リモートが設定されていない場合 → 提案とともにエラーを報告します
• TypeScript エラーがある場合 → 停止して報告します

---

同梱リソース

テンプレート：templates/ ディレクトリにセットアップファイル一式を用意しています（wrangler.jsonc、vite.config.ts、package.json、tsconfig.json、src/index.ts、public/index.html、styles.css、script.js）

公式ドキュメント

• Cloudflare Workers: https://developers.cloudflare.com/workers/
• 静的アセット: https://developers.cloudflare.com/workers/static-assets/
• Vite プラグイン: https://developers.cloudflare.com/workers/vite-plugin/
• Wrangler: https://developers.cloudflare.com/workers/wrangler/
• Hono: https://hono.dev/docs/getting-started/cloudflare-workers
• MCP ツール: 最新のドキュメントには mcp__cloudflare-docs__search_cloudflare_documentation を使用してください

---

依存関係（2026-01-03 時点で確認済み）

{
  "dependencies": {
    "hono": "^4.11.3"
  },
  "devDependencies": {
    "@cloudflare/vite-plugin": "^1.17.1",
    "@cloudflare/workers-types": "^4.20260103.0",
    "vite": "^7.3.1",
    "wrangler": "^4.54.0",
    "typescript": "^5.9.3"
  }
}

---

本番環境での検証

ライブサンプル: https://cloudflare-worker-base-test.webfonts.workers.dev（ビルド時間：45 分、エラー 0 件、10 件すべての問題を防止）

---

最終確認日: 2026-01-20 | スキルのバージョン: 3.1.0 | 変更点: Vite 8 の nodejs_compat 回避策（Issue #9）、Vite の base オプションのリグレッション（Issue #10）、自動プロビジョニングのエッジケースに関する警告、キャッシュ破損のトラブルシューティングセクション、vite-tsconfig-paths v6 と uuid パッケージの代替案に関するコミュニティのヒントを追加しました。skill-researcher エージェントが、2025 年 5 月以降の Workers SDK の更新を対象に調査を実施しました。