# Cloudflare Worker 基础堆栈 **生产测试**：cloudflare-worker-base-test () **最后更新**：2025-10-20 **状态**：生产就绪 ✅ ** ** ## 快速入门（5 分钟） ### 1\.脚手架工程 npm create cloudflare@latest my-worker -- \ --输入你好世界\ --ts\ --git \ --部署假\ --框架无 **为什么这些标志：** * `--type hello-world`：干净的起点 * `--ts`：TypeScript 支持 * `--git`: 初始化 git 仓库 * `--deploy false`: 暂不部署（先配置） * `--framework none`: 我们自己添加Vite ### 2\.安装依赖项 cd 我的工人 npm 安装 hono@4.10.1 npm install -D @cloudflare/vite-plugin@1.13.13 vite@latest **版本说明：** * `hono@4.10.1`：最新稳定版（2025-10-20 验证） * `@cloudflare/vite-plugin@1.13.13`：最新稳定版，修复了 HMR 竞争条件 * `vite`：与 Cloudflare 插件兼容的最新版本 ### 3\.配置牧马人创建或更新 `wrangler.jsonc`： { "$schema": "node_modules/wrangler/config-schema.json", “姓名”：“我的工人”， "main": "src/index.ts", "account_id": "YOUR_ACCOUNT_ID", “兼容性日期”：“2025-10-11”， “可观察性”：{ “启用”：真 }, “资产”：{ “目录”：“./public/”， “绑定”：“资产”， "not_found_handling": "单页应用程序", “run_worker_first”：[“/ api / *”] } } **关键：`run_worker_first` 配置** * 如果没有这个，SPA 后备会拦截 API 路由 * API 路由返回 `index.html` 而不是 JSON * 来源：[workers-sdk #8879]() ### 4\.配置Vite 创建`vite.config.ts`：从“vite”导入{defineConfig} 从 '@cloudflare/vite-plugin' 导入 { cloudflare } 导出默认的defineConfig({ 插件：[ 云耀（{ // 可选：如果需要，配置插件 }), ], }) **为什么@cloudflare/vite-plugin：** * Cloudflare 的官方插件 * 支持员工 HMR * 使用 Miniflare 实现本地开发 * 版本 1.13.13 修复了“挂起的 Promise 被取消”错误 ** ** ## 四步设置过程 ### 第 1 步：使用 API 路由创建 Hono 应用程序创建`src/index.ts`： /** * Cloudflare Worker 与 Hono * * 关键：导出模式以防止构建错误 * ✅ 正确：导出默认应用程序 * ❌ 错误：导出默认值 { fetch: app.fetch } */ 从 'hono' 导入 { Hono } // 类型安全的环境绑定类型绑定 = { 资产：获取器 } const app = new Hono<{ 绑定: 绑定 }>() /** * API 路由 * 由于 run_worker_first 配置，在静态资产之前处理 */ app.get('/api/hello', (c) => { 返回 c.json({ message: '来自 Cloudflare Workers 的问候！', 时间戳：new Date().toISOString(), }) }) app.get('/api/health', (c) => { 返回 c.json({ 状态：“好的”，版本：'1.0.0'，环境：c.env ？ '生产' : '开发', }) }) /** * 回退到静态资源 * 以上未匹配的任何路线均由 public/ 目录提供 */ app.all('*', (c) => { 返回 c.env.ASSETS.fetch(c.req.raw) }) /** * 直接导出Hono应用程序（ES模块格式） * 这是使用 Hono + Vite 的 Cloudflare Workers 的正确模式 */ 导出默认应用程序 **为什么采用这种导出模式：** * 来源：[honojs/hono #3955]() * 使用 `{ fetch: app.fetch }` 会导致：“无法读取未定义的属性（读取‘map’）” * 例外：如果您需要计划/尾部处理程序，请使用 Module Worker 格式：导出默认值{ 获取：app.fetch，已安排： async (event, env, ctx) => { /* ... */ } } ### 第 2 步：创建静态前端创建“public/index.html”： <头> <元字符集=“UTF-8”> 我的工人应用程序 <正文>

Cloudflare Worker + 静态资产

创建“public/script.js”：异步函数 testAPI() { const 响应 = 等待 fetch('/api/hello') const data = 等待response.json() document.getElementById('output').textContent = JSON.stringify(data, null, 2) } 创建`public/styles.css`：身体{ 字体系列：system-ui、-apple-system、sans-serif；最大宽度：800px；边距：40px 自动；内边距：20px； } 按钮{ 背景：#0070f3；颜色: 白色; 边框：无；内边距：12 像素 24 像素；边框半径：6px；光标：指针； } 预{ 背景：#f5f5f5；内边距：16px；边框半径：6px；溢出-x：自动； } ### 步骤 3：更新包脚本更新 `package.json`： { “脚本”：{ “dev”：“牧马人开发”， “部署”：“牧马人部署”， "cf-typegen": "牧马人类型" } } ### 第 4 步：测试和部署 # 生成绑定的 TypeScript 类型 npm 运行 cf-typegen # 启动本地开发服务器（http://localhost:8787） npm 运行开发 # 部署到生产环境 npm 运行部署 ** ** ## 已知问题预防此技能可防止 **6 个已记录的问题**： ### 问题#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 模块格式（如步骤 1 所示） ** ** ## 配置文件参考 ### wrangler.jsonc（完整示例） { "$schema": "node_modules/wrangler/config-schema.json", “姓名”：“我的工人”， "main": "src/index.ts", "account_id": "YOUR_ACCOUNT_ID", “兼容性日期”：“2025-10-11”， “可观察性”：{ “启用”：真 }, “资产”：{ “目录”：“./public/”， “绑定”：“资产”， "not_found_handling": "单页应用程序", “run_worker_first”：[“/ api / *”] } /* 可选：环境变量 */ // "vars": { "MY_VARIABLE": "生产值" } /* 可选：KV 命名空间绑定 */ // "kv_namespaces": [ // { "绑定": "MY_KV", "id": "YOUR_KV_ID" } //] /* 可选：D1 数据库绑定 */ //“d1_数据库”：[ // { “绑定”：“DB”，“database_name”：“my-db”，“database_id”：“YOUR_DB_ID” } //] /* 可选：R2 桶绑定 */ //“r2_buckets”：[ // { "绑定": "MY_BUCKET", "bucket_name": "我的桶" } //] } **为什么 wrangler.jsonc 而不是 wrangler.toml：** * 自 Wrangler v3.91.0 起首选 JSON 格式 * 更好的 IDE 支持 JSON 模式 * JSONC 允许评论 ### vite.config.ts（完整示例）从“vite”导入{defineConfig} 从 '@cloudflare/vite-plugin' 导入 { cloudflare } 导出默认的defineConfig({ 插件：[ 云耀（{ // 在 HMR 更新之间保持状态坚持：真实， }), ], // 可选：配置服务器服务器：{ 端口：8787， }, // 可选：构建优化构建：{ 目标：'esnext'，缩小：真实， }, }) ### tsconfig.json { “编译器选项”：{ “目标”：“ES2022”， “模块”：“ES2022”， “lib”：[“ES2022”]， "moduleResolution": "捆绑器", “类型”：[“@cloudflare/workers-types/2023-07-01”]， “resolveJsonModule”：true， “allowJs”：正确， “checkJs”：假， “严格”：真实， “esModuleInterop”：正确， “skipLibCheck”：正确， “forceConsistentCasingInFileNames”：true， “isolatedModules”：正确， “noEmit”：真 }, “包括”：[“src / ** / *”]， “排除”：[“node_modules”] } ** ** ## API 路由模式 ### 基本 JSON 响应 app.get('/api/users', (c) => { 返回 c.json({ 用户：[ { id: 1, 名称: '爱丽丝' }, { id: 2, 姓名: '鲍勃' } ] }) }) ### 带有请求正文的 POST app.post('/api/users', 异步 (c) => { const body = 等待 c.req.json() // 验证并处理主体返回 c.json({ 成功: true, 数据: body }, 201) }) ### 路由参数 app.get('/api/users/:id', (c) => { const id = c.req.param('id') 返回 c.json({ id, name: '用户' }) }) ### 查询参数 app.get('/api/search', (c) => { const 查询 = c.req.query('q') 返回 c.json({ 查询, 结果: [] }) }) ### 错误处理 app.get('/api/data', 异步 (c) => { 尝试{ // 你的逻辑在这里返回 c.json({ 成功: true }) } 捕获（错误）{ 返回 c.json({ 错误: error.message }, 500) } }) ### 使用绑定（KV、D1、R2）类型绑定 = { 资产：获取器 MY_KV：KV命名空间数据库：D1数据库 MY_BUCKET：R2Bucket } const app = new Hono<{ 绑定: 绑定 }>() app.get('/api/data', 异步 (c) => { // 电压 const value = 等待 c.env.MY_KV.get('key') // D1 const result = wait c.env.DB.prepare('SELECT * FROM users').all() // R2 const object = wait c.env.MY_BUCKET.get('file.txt') 返回 c.json({ 值, 结果, 对象 }) }) ** ** ## 静态资产最佳实践 ### 目录结构公共/ ├──index.html # 主入口点 ├── styles.css # 全局样式 ├── script.js # 客户端 JavaScript ├── favicon.ico # 网站图标 └── asset/ # 图片、字体等 ├── 标志.png └── 字体/ ### SPA 后备 `"not_found_handling": "single-page-application"` 配置意味着： * 未知路由返回`index.html` * 适用于 React Router、Vue Router 等。 * 但 API 路由需要 `run_worker_first`！ ### 路由优先级使用 `"run_worker_first": ["/api/*"]`： 1. `/api/hello` → Worker 处理它（返回 JSON） 2. `/` → 静态资源服务`index.html` 3. `/styles.css` → 静态资源服务于`styles.css` 4. `/unknown` → 静态资源服务 `index.html` （SPA 后备） ### 缓存静态资源静态资源自动缓存在边缘。清除缓存： ** ** ## 开发工作流程 ### 本地发展 npm 运行开发 * 服务器运行在 *启用HMR（文件更改自动重新加载） * 使用Miniflare进行本地模拟 * 所有绑定均在本地工作（KV、D1、R2） ### 测试 API 路由 # 测试 GET 端点卷曲 http://localhost:8787/api/hello # 测试 POST 端点卷曲 -X POST http://localhost:8787/api/echo \ -H“内容类型：application/json”\ -d '{"测试":"数据"}' ### 类型生成 npm 运行 cf-typegen 使用以下命令生成“worker-configuration.d.ts”： * 绑定类型（KV、D1、R2等） * 环境变量类型 * 在编辑器中自动完成 ### 部署 # 部署到生产环境 npm 运行部署 # 部署到特定环境牧马人部署--env staging # 生产中的尾部日志牧马人尾巴 # 检查部署状态牧马人部署列表 ** ** ## 完整设置清单 * 使用“npm create cloudflare@latest”搭建的项目 * 安装的依赖项：`hono@4.10.1`、`@cloudflare/vite-plugin@1.13.13` * `wrangler.jsonc` 创建为： * `account_id` 设置为您的 Cloudflare 帐户 * `assets.directory` 指向 `./public/` * `assets.run_worker_first` 包括 `/api/*` * `compatibility_date` 设置为最近的日期 * 使用 `@cloudflare/vite-plugin` 创建 `vite.config.ts` * 使用 Hono 应用程序创建的 `src/index.ts` * 使用“导出默认应用程序”（不是“{ fetch: app.fetch }”） * 包括资产绑定类型 * 有后备路由： `app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw))` * 使用静态文件创建的`public/`目录 * `npm run cf-typegen` 执行成功 * `npm run dev` 启动没有错误 * API路由在浏览器/curl中测试 * 静态资源正常使用 * HMR 工作时不会崩溃 * 准备使用“npm run deploy”进行部署 ** ** ## 高级主题 ### 添加中间件从 'hono' 导入 { Hono } 从 'hono/logger' 导入 { logger } 从 'hono/cors' 导入 { cors } const app = new Hono<{ 绑定: 绑定 }>() // 全局中间件 app.use('*', 记录器()) app.use('/api/*', cors()) // 特定于路由的中间件 app.use('/admin/*', async (c, next) => { // 授权检查等待下一个() }) ### 特定于环境的配置 // 牧马人.jsonc { “姓名”：“我的工人”， “环境”：{ “分期”：{ “vars”：{“ENV”：“分期”} }, “生产”：{ “vars”：{“ENV”：“生产”} } } } 部署：`wrangler部署--env staging` ### 自定义错误页面 app.onError((err, c) => { 控制台.错误（错误） return c.json({ error: '内部服务器错误' }, 500) }) app.notFound((c) => { 返回 c.json({ 错误: '未找到' }, 404) }) ### 使用 Vitest 进行测试 npm install -D vitest @cloudflare/vitest-pool-workers 创建`vitest.config.ts`：从'vitest/config'导入{defineConfig} 导出默认的defineConfig({ 测试：{ 池选项：{ 工人：{ 牧马人: { configPath: './wrangler.jsonc' }, }, }, }, }) 请参阅“reference/testing.md”以获取完整的测试指南。 ** ** ## 文件模板所有模板都可以在“templates/”目录中找到： * **wrangler.jsonc** \- 完整的 Worker 配置 * **vite.config.ts** \- Vite + Cloudflare 插件设置 * **package.json** \- 依赖项和脚本 * **tsconfig.json** \- TypeScript 配置 * **src/index.ts** \- 具有 API 路由的 Hono 应用程序 * **public/index.html** \- 静态前端示例 * **public/styles.css** \- 样式示例 * **public/script.js** \- API 测试函数将这些文件复制到您的项目并根据需要进行自定义。 ** ** ## 参考文档如需更深入的了解，请参阅： * **architecture.md** \- 深入研究导出模式、路由和静态资源 * **common-issues.md** \- 所有 6 个问题以及详细的故障排除 * **deployment.md** \- Wrangler 命令、CI/CD 模式和生产技巧 ** ** ## 官方文档 * **Cloudflare Workers** ： * **静态资产**： * **Vite 插件** : * **牧马人配置**： * **Hono** ： * **Context7 库 ID**：`/websites/developers_cloudflare-workers` ** ** ## 依赖项（最新验证2025-10-20） { “依赖项”：{ “荣誉”：“^4.10.1” }, “开发依赖项”：{ "@cloudflare/vite-plugin": "^1.13.13", "@cloudflare/workers-types": "^4.20251011.0", "vite": "^7.0.0", "牧马人": "^4.43.0", “打字稿”：“^5.9.0” } } ** ** ## 制作示例该技能基于 cloudflare-worker-base-test 项目： * **直播**： * **构建时间**：~45 分钟（实际） * **错误**：0（已阻止所有 6 个已知问题） * **验证**：✅ 本地开发、HMR、生产部署全部成功该技能中的所有模式都已在生产中得到验证。 * * * **问题？有问题吗？** 1. 首先检查 `reference/common-issues.md` 2. 验证 4 步设置过程中的所有步骤 3. 确保“导出默认应用程序”（而不是“{ fetch: app.fetch }”） 4. 确保配置了“run_worker_first” 5.查看官方文档：

Cloudflare 工人基地

包含技能