cloudflare-worker-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Worker Builder

Cloudflare Worker 构建工具

Scaffold a working Cloudflare Worker project from a brief description. Produces a deployable project with Hono routing, Vite dev server, and Static Assets.

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

Workflow

工作流程

Step 1: Understand the Project

步骤1：理解项目需求

Ask about the project to choose the right bindings and structure:

What does the app do? (API only, SPA + API, landing page)
What data storage? (D1 database, R2 files, KV cache, none)
Auth needed? (Clerk, better-auth, none)
Custom domain or workers.dev subdomain?

A brief like "todo app with database" is enough to proceed.

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

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

类似「带数据库的待办事项应用」这样的简短描述即可开始操作。

Step 2: Scaffold the Project

步骤2：搭建项目结构

bash

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

Copy and customise the asset files from this skill's

assets/

directory:

```
wrangler.jsonc
```
— Worker configuration
```
vite.config.ts
```
— Vite + Cloudflare plugin
```
src/index.ts
```
— Hono app with Static Assets fallback
```
package.json
```
— Scripts and dependencies
```
tsconfig.json
```
— TypeScript config
```
public/index.html
```
— SPA entry point

bash

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入口文件

Step 3: Configure Bindings

步骤3：配置绑定

Add bindings to

wrangler.jsonc

based on project needs. Wrangler 4.45+ auto-provisions resources on first deploy — always specify explicit names:

jsonc

{
  "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" }]
}

根据项目需求在

wrangler.jsonc

中添加绑定。Wrangler 4.45+版本会在首次部署时自动创建资源——请务必指定明确的名称：

jsonc

{
  "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/*"]
  },
  // 根据需要添加：
  "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" }]
}

Step 4: Deploy

步骤4：部署

bash

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

bash

npm run dev           # 本地开发地址：http://localhost:8787
wrangler deploy       # 生产环境部署

Critical Patterns

关键配置模式

Export Syntax

导出语法

typescript

// CORRECT — use this pattern
export default app

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

Source: honojs/hono #3955

typescript

// 正确写法 — 使用该模式
export default app

// 错误写法 — 会导致「Cannot read properties of undefined」错误
export default { fetch: app.fetch }

来源：honojs/hono #3955

Static Assets + API Routes

静态资源 + API路由

Without

run_worker_first

, SPA fallback intercepts API routes and returns

index.html

instead of JSON:

jsonc

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

Source: workers-sdk #8879

如果不设置

run_worker_first

，SPA回退会拦截API路由并返回

index.html

而非JSON数据：

jsonc

"assets": {
  "not_found_handling": "single-page-application",
  "run_worker_first": ["/api/*"]  // 关键配置
}

来源：workers-sdk #8879

Vite Config

Vite配置

typescript

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

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

Always set the

main

field in wrangler.jsonc — the Vite plugin needs it.

typescript

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

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

务必在wrangler.jsonc中设置

main

字段——Vite插件需要该配置。

Scheduled/Cron Handlers

定时任务/Cron处理器

When adding cron triggers, switch to explicit export:

typescript

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

添加Cron触发器时，需切换为显式导出模式：

typescript

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

Reference Files

参考文档

Read these for detailed troubleshooting:

```
references/common-issues.md
```
— 10 documented issues with sources and fixes
```
references/architecture.md
```
— Route priority, caching, Workers RPC
```
references/deployment.md
```
— CI/CD, auto-provisioning, gradual rollouts

如需详细排查问题，请阅读以下文件：

```
references/common-issues.md
```
— 10个已记录的问题及对应的来源和修复方案
```
references/architecture.md
```
— 路由优先级、缓存、Workers RPC
```
references/deployment.md
```
— CI/CD、自动资源创建、灰度发布