cloudflare-worker-builder

Cloudflare Worker 构建器

根据简短描述搭建可运行的 Cloudflare Worker 项目。生成可部署的项目，包含 Hono 路由、Vite 开发服务器和静态资源。

工作流

步骤 1：了解项目

询问项目相关信息，以选择合适的绑定和结构：

• 应用的功能是什么？（仅 API、SPA + API、落地页）
• 使用什么数据存储？（D1 数据库、R2 文件、KV 缓存、无）
• 是否需要身份验证？（Clerk、better-auth、无）
• 使用自定义域名还是 workers.dev 子域名？

像“带数据库的待办事项应用”这样的简短描述就足以开始。

步骤 2：搭建项目框架

npm create cloudflare@latest my-worker -- --type hello-world --ts --git --deploy false --framework none
cd my-worker
npm install hono
npm install -D @cloudflare/vite-plugin vite

从此技能的 assets/ 目录复制并自定义资源文件：

• wrangler.jsonc — Worker 配置
• vite.config.ts — Vite + Cloudflare 插件
• src/index.ts — 带有静态资源回退的 Hono 应用
• package.json — 脚本和依赖项
• tsconfig.json — TypeScript 配置
• public/index.html — SPA 入口点

步骤 3：配置绑定

根据项目需求向 wrangler.jsonc 添加绑定。Wrangler 4.45+ 会在首次部署时自动创建资源 — 始终指定明确的名称：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-11-11",
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]
  },
  // Add as needed:
  "d1_databases": [{ "binding": "DB", "database_name": "my-app-db" }],
  "r2_buckets": [{ "binding": "STORAGE", "bucket_name": "my-app-files" }],
  "kv_namespaces": [{ "binding": "CACHE", "title": "my-app-cache" }]
}

步骤 4：部署

npm run dev           # Local dev at http://localhost:8787
wrangler deploy       # Production deploy

---

关键模式

导出语法

// CORRECT — use this pattern
export default app

// WRONG — causes "Cannot read properties of undefined"
export default { fetch: app.fetch }

来源：honojs/hono #3955

静态资源 + API 路由

如果没有设置 run_worker_first，SPA 回退会拦截 API 路由，并返回 index.html 而不是 JSON：

"assets": {
  "not_found_handling": "single-page-application",
  "run_worker_first": ["/api/*"]  // CRITICAL
}

来源：workers-sdk #8879

Vite 配置

import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'

export default defineConfig({ plugins: [cloudflare()] })

务必在 wrangler.jsonc 中设置 main 字段 — Vite 插件需要该字段。

定时/ Cron 处理程序

添加 cron 触发器时，切换为显式导出：

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

---

参考文件

阅读以下文件以了解详细的故障排除信息：

• references/common-issues.md — 10 个有来源和解决方案的已记录问题
• references/architecture.md — 路由优先级、缓存、Workers RPC
• references/deployment.md — CI/CD、自动创建资源、渐进式发布