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 年第一季度）
• 2025 年 6 月：从控制面板移除 Native Integrations（改用基于 CLI 的方式，通过 wrangler secrets 配置）
• 2025 年平台更新：Workers VPC Services、Durable Objects Data Studio、64 个环境变量（每个 5KB）、每个 Worker 的 Cron Triggers 数量不受限制、32 MiB 的 WebSocket 消息、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 路由并返回 index.html，而不是 JSON（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 路由返回 index.html，而不是 JSON 来源：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 格式

问题 #7：渐进式发布时资源不匹配（2025）

错误：渐进式部署期间，带指纹的资源出现 404 错误 来源：Cloudflare 静态资源文档 原因：现代框架（使用 Vite 的 React/Vue/Angular）会生成带指纹的文件名（例如 index-a1b2c3d4.js）。在不同版本之间渐进式发布时，用户的初始请求可能会路由到版本 A（HTML 引用了 index-a1b2c3d4.js），但后续资源请求会路由到版本 B（仅包含 index-m3n4o5p6.js），从而导致 404 错误 预防措施：

• 避免对带指纹的资源进行渐进式部署
• 对静态网站使用即时切换部署
• 或通过自定义逻辑实现版本感知路由

问题 #8：使用 run_worker_first 时免费套餐出现 429 错误（2025）

错误：超过免费套餐限制后，资源请求收到 429（请求过多）响应 来源：Cloudflare 静态资源计费文档 原因：使用 run_worker_first 时，匹配指定模式的请求始终会调用你的 Worker 脚本（计入免费套餐限制）。超过限制后，这些请求会收到 429，而不会回退到免费的静态资源服务 预防措施：

• 升级到 Workers 付费套餐（每月 $5），以获得无限请求
• 使用负向模式（!/pattern）将路径排除在 Worker 调用之外
• 将 run_worker_first 模式限制在必要的 API 路由

问题 #9：Vite 8 导致 nodejs_compat 无法使用 require()

错误：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）。

问题 #10：Vite 的 base 选项导致 SPA 路由失效（1.13.8+）

错误：curl http://localhost:5173/prefix 返回 404，而不是 index.html 来源：workers-sdk #11857 受影响版本：@cloudflare/vite-plugin 1.13.8+ 原因：插件现在会将包含 base 路径的完整 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);
}

状态：这是为了让开发环境与生产环境保持一致而做出的有意变更。平台计划于 2026 年第 1 季度推出 assets.base 功能（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. / → 静态资源服务返回 index.html
3. /styles.css → 静态资源服务返回 styles.css
4. /unknown → 静态资源服务返回 index.html（SPA 回退）

静态资源缓存：自动进行边缘缓存。使用查询字符串使缓存失效：<link href="/styles.css?v=1.0.0">

免费套餐警告（2025）：run_worker_first 模式会计入免费套餐限制。超过限制后，请求会收到 429，而不会回退到免费的静态资源。使用负向模式（!/pattern）或升级到付费套餐。

自动配置（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]

故障排查

开发时随机出现“响应已发送”错误

症状：运行 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”错误。

适用范围：使用 TypeScript 路径别名进行 React SSR 的项目

使用 crypto.randomUUID() 代替 uuid 包

来源：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. 提交并推送：暂存变更、生成符合约定式提交规范的提交消息，并推送到远程
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 变通方案（问题 #9）、Vite base 选项回归问题（问题 #10）、自动配置的边缘情况警告、缓存损坏故障排除部分，以及关于 vite-tsconfig-paths v6 和 uuid 软件包替代方案的社区技巧。研究由 skill-researcher Agent 开展，涵盖 2025 年 5 月之后 Workers SDK 的更新。