# Cloudflare Worker 基础堆栈 **生产测试**：cloudflare-worker-base-test () **最后更新**：2026-01-03 **状态**：生产就绪 ✅ **最新版本**：hono@4.11.3、@cloudflare/vite-plugin@1.17.1、 vite@7.2.4，wrangler@4.54.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 月**：本机集成从仪表板中删除（基于 CLI 的方法，带有牧马人秘密） * **2025 平台**：Workers VPC 服务、Durable Objects Data Studio、64 个环境变量（每个 5KB）、每个 Worker 无限 Cron 触发器、WebSocket 32 MiB 消息、node:fs/Web 文件系统 API * **2025 静态资产**：逐步推出资产不匹配问题、run_worker_first 的免费层 429 错误、Vite 插件自动检测 * **Hono 4.11.x** ：增强的 TypeScript RPC 类型推断、cloneRawRequest 实用程序、JWT aud 验证、auth 中间件改进 ** ** ## 快速入门（5 分钟） # 1. 脚手架项目 npm create cloudflare@latest my-worker -- --type hello-world --ts --git --deploy false --framework none # 2.安装依赖项 cd 我的工人 npm 安装 hono@4.11.3 npm install -D @cloudflare/vite-plugin@1.17.1 vite@7.2.4 # 3. 创建 wrangler.jsonc { “姓名”：“我的工人”， "main": "src/index.ts", "account_id": "YOUR_ACCOUNT_ID", “兼容性日期”：“2025-11-11”， “资产”：{ “目录”：“./public/”， “绑定”：“资产”， "not_found_handling": "单页应用程序", "run_worker_first": ["/api/*"] // 关键：防止 SPA 回退拦截 API 路由 } } # 4.创建vite.config.ts 从“vite”导入{defineConfig} 从 '@cloudflare/vite-plugin' 导入 { cloudflare } 导出默认的defineConfig({ 插件: [cloudflare()] }) # 5. 创建 src/index.ts 从 'hono' 导入 { Hono } 类型绑定 = { 资产：获取器 } const app = new Hono<{ 绑定: 绑定 }>() app.get('/api/hello', (c) => c.json({ message: '你好！' })) app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw)) 导出默认应用程序 // 关键：使用此模式（不是 { fetch: app.fetch }） # 6. 部署 npm run dev # 本地：http://localhost:8787 牧马人部署#生产 **关键配置**： * `run_worker_first: ["/api/*"]` \- 如果没有这个，SPA 后备会拦截返回 `index.html` 而不是 JSON 的 API 路由 ([workers-sdk #8879]()) * `export default app` \- 使用 `{ fetch: app.fetch }` 会导致“无法读取未定义的属性” ([honojs/hono #3955]()) ## 已知问题预防此技能可防止 **8 个已记录的问题**： ### 问题#1：导出语法错误 **错误**：“无法读取未定义的属性（读取'地图'）” **来源**：[honojs/hono #3955]（） **预防**：使用 `export default app` （不是 `{ fetch: app.fetch }`） ### 问题#2：静态资产路由冲突 **错误**：API 路由返回 `index.html` 而不是 JSON **来源**：[workers-sdk #8879]() **预防**：将 `"run_worker_first": ["/api/*"]` 添加到 wrangler.jsonc ### 问题#3：计划/Cron 未导出 **错误**：“处理程序不导出预定（）函数” **来源**：[honojs/vite-plugins #275]（） **预防**：在需要时使用模块工作器格式：导出默认值{ 获取：app.fetch，已安排： async (event, env, ctx) => { /* ... */ } } ### 问题 #4：HMR 竞争条件 **错误**：开发过程中“悬置的 Promise 被取消” **来源**：[workers-sdk #9518]() **预防**：使用 `@cloudflare/vite-plugin@1.13.13` 或更高版本 ### 问题 #5：静态资产上传竞赛 **错误**：CI/CD 中的非确定性部署失败 **来源**：[workers-sdk #7555]() **预防**：使用带有重试逻辑的 Wrangler 4.x+（在最新版本中修复） ### 问题#6：Service Worker 格式混乱 **错误**：使用已弃用的 Service Worker 格式 **来源**：Cloudflare 迁移指南 **预防**：始终使用 ES 模块格式 ### 问题#7：逐步推出资产不匹配（2025） **错误**：逐步部署期间指纹资产出现 404 错误 **来源**：[Cloudflare 静态资产文档]() **为什么会发生**：现代框架（React/Vue/Angular 和 Vite）生成指纹文件名（例如， `index-a1b2c3d4.js`)。在版本之间逐步推出的过程中，用户的初始请求可能会转到版本 A（HTML 引用“index-a1b2c3d4.js”），但后续资产请求会路由到版本 B（只有“index-m3n4o5p6.js”），从而导致 404s **预防**： * 避免使用指纹资产进行渐进式部署 * 对静态站点使用即时切换部署 * 或者使用自定义逻辑实现版本感知路由 ### 问题 #8：run_worker_first 的免费 Tier 429 错误 (2025) **错误**：超过免费套餐限制时，资产请求有 429 个（请求过多）响应 **来源**：[Cloudflare 静态资产计费文档]() **发生原因**：使用 `run_worker_first` 时，匹配指定模式的请求始终会调用您的 Worker 脚本（计入免费套餐）限制）。超出限制后，这些请求会收到 429，而不是回退到免费静态资产服务**预防**： * 升级到工人付费计划（5 美元/月），无限制请求 * 使用负模式（`!/pattern`）从 Worker 调用中排除路径 * 将“run_worker_first”模式最小化为仅重要的 API 路由 ## 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 后备） **静态资源缓存**：自动边缘缓存。缓存查询字符串：`` **免费套餐警告** (2025)：“run_worker_first”模式计入免费套餐限制。超出后，请求会得到 429，而不是回退到释放静态资源。使用否定模式（`!/pattern`）或升级到付费计划。 ## 自动配置（Wrangler 4.45+） **默认行为**：Wrangler 在部署时自动配置 R2 存储桶、D1 数据库和 KV 命名空间。这消除了手动资源创建步骤。 **它是如何工作的**： // wrangler.jsonc - 只需定义绑定，资源在部署时自动创建 { “d1_databases”：[{“绑定”：“DB”，“database_name”：“my-app-db”}]， “r2_buckets”：[{“绑定”：“存储”，“bucket_name”：“我的应用程序文件”}]， “kv_namespaces”：[{“绑定”：“缓存”，“标题”：“我的应用程序缓存”}] } # 部署 - 如果资源不存在则自动配置牧马人部署 # 禁用自动配置（仅使用现有资源）牧马人部署--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），这些 Worker 使用类型安全的方法相互调用。 **定义 RPC 服务**：从 'cloudflare:workers' 导入 { WorkerEntrypoint } 导出类 AuthService 扩展 WorkerEntrypoint { async verifyToken(token: string): Promise<{ userId: string;有效：布尔值 }> { // 通过 this.env 访问绑定 const session = wait this.env.SESSIONS.get(token) 返回会话？ { userId: session.userId, valid: true } : { userId: '', valid: false } } 异步 createSession(userId: string): Promise { const 令牌 = crypto.randomUUID() 等待 this.env.SESSIONS.put(token, JSON.stringify({ userId }), {expirationTtl: 3600 }) 返回令牌 } } // 默认导出仍然处理 HTTP 请求导出默认值 { 获取：... } **另一名工人的来电**： // 牧马人.jsonc { “服务”：[ {“绑定”：“AUTH”，“服务”：“auth-worker”，“入口点”：“AuthService”} ] } // 在你的主 Worker 中 const { valid, userId } = wait env.AUTH.verifyToken(authHeader) **要点**： * **零延迟**：同一帐户上的工作人员通常在同一线程中运行 * **类型安全** ：对方法签名的完整 TypeScript 支持 * **32 MiB 限制**：最大序列化 RPC 消息大小 * **自绑定** ：在“wrangler dev”中，对于同一个 Worker 调用显示为“[connected]” ## 捆绑资源 **Templates** ： `templates/` 目录中的完整设置文件（wrangler.jsonc、vite.config.ts、package.json、tsconfig.json、src/index.ts、public/index.html、styles.css、script.js） ## 官方文档 * **Cloudflare Workers** ： * **静态资产**： * **Vite 插件** : * **牧马人**： * **Hono** ： * **MCP 工具** ：使用 `mcp__cloudflare-docs__search_cloudflare_documentation` 获取最新文档 ** ** ## 依赖项（最新验证2026-01-03） { “依赖项”：{ “荣誉”：“^4.11.3” }, “开发依赖项”：{ "@cloudflare/vite-plugin": "^1.17.1", "@cloudflare/workers-types": "^4.20260103.0", "vite": "^7.2.4", "牧马人": "^4.54.0", “打字稿”：“^5.9.3” } } ** ** ## 生产验证 **实时示例**：（构建时间：45 分钟，0 个错误，所有 8 个问题均被阻止）

Cloudflare 工人基地

包含技能