用途
cloudflare-worker-base 用于在 Cloudflare Workers 上搭建一个集成 Hono 路由、Vite 插件与静态资源的基础项目结构。资料将其定位为“生产验证过”的初始配置方案，适合需要同时提供 API 路由与静态页面（含 SPA 回退）的 Worker 应用。
主要能力
- 提供 5 分钟快速开始流程：创建项目脚手架、安装依赖、创建 wrangler.jsonc、vite.config.ts 与 src/index.ts、本地运行与部署。
- 集成 Hono 处理路由，Vite 插件负责构建，静态资源通过 ASSETS 绑定提供，未知路由可回退到 index.html 以支持 React Router / Vue Router。
- 针对 10 个已记录问题给出预防措施，包括：导出语法错误、静态资源路由冲突、scheduled() 未导出、HMR 竞态、静态资源上传竞态、Service Worker 格式混淆、渐进发布资源不匹配、免费额度 429、Vite 8 破坏 nodejs_compat 的 require()、Vite base 选项破坏 SPA 路由。
- 介绍 Wrangler 4.45+ 的自动供给能力（R2、D1、KV 绑定默认自动创建），并提示始终显式指定 database_name / bucket_name / title。
- 介绍 Workers RPC（服务绑定）：使用 WorkerEntrypoint 类定义服务方法，并通过 services 绑定从其他 Worker 调用。
- 提供 /deploy 命令：执行提交、推送与 wrengler deploy 的一键部署流程。
- 附带模板文件（wrangler.jsonc、vite.config.ts、package.json、tsconfig.json、src/index.ts、public/index.html 等）与官方文档链接。
使用方式
资料给出的核心步骤为：
- 使用 npm create cloudflare@latest 创建项目，参数为 --type hello-world --ts --git --deploy false --framework none。
- 安装依赖：hono@4.11.3，以及开发依赖 @cloudflare/vite-plugin@1.17.1 与 vite@7.3.1。
- 创建 wrangler.jsonc，配置 name、main、account_id、compatibility_date、assets（directory、binding、not_found_handling: single-page-application、run_worker_first: ["/api/*"]）。
- 创建 vite.config.ts，引入 @cloudflare/vite-plugin 的 cloudflare()。
- 创建 src/index.ts，使用 Hono 实例处理 /api 路由，其余请求转发到 ASSETS，并用 export default app 导出。
- 本地运行 npm run dev（http://localhost:8787），生产部署使用 wrangler deploy。
资料强调两个关键配置：run_worker_first: ["/api/*"] 防止 SPA 回退拦截 API 路由；使用 export default app 而非 { fetch: app.fetch } 以避免“Cannot read properties of undefined”。
适用场景
- 需要在 Cloudflare Workers 上同时托管 API 与静态前端（含 SPA）的项目。
- 希望避免上述 10 类已知配置陷阱、减少调试成本的新项目。
- 需要将应用拆分为多个 Worker 并通过 RPC 服务绑定互相调用的场景。
- 使用 Wrangler 4.45+ 自动供给 R2、D1、KV 资源的部署流程。
限制与注意事项
- 免费额度警告：使用 run_worker_first 时，匹配的请求始终调用 Worker 脚本并计入免费额度，超限后返回 429 而不会回退到免费静态资源；可考虑升级到 Paid 计划（$5/月）或使用负向模式、缩小匹配范围。
- 渐进发布与带指纹文件名静态资源可能产生 404，建议静态站点使用即时切换部署。
- Vite 8 与 @cloudflare/vite-plugin 1.21.0+ 组合下 require() 问题需临时添加 esmExternalRequirePlugin 变通方案，资料称 Vite 团队正在修复。
- Vite base 选项在 @cloudflare/vite-plugin 1.13.8+ 下会破坏 SPA 路由，资料提供开发模式剥离 base 路径的变通方案，并称平台层的 assets.base 计划于 2026 年 Q1 提供。
- 社区建议：React SSR 配合 TypeScript 路径别名时，可固定 vite-tsconfig-paths@5.1.4；建议使用 crypto.randomUUID() 而非 uuid@11 包。
- 资料标注的最新验证版本与时间：hono@4.11.3、@cloudflare/vite-plugin@1.17.1、vite@7.3.1、wrangler@4.54.0，最后验证 2026-01-20，技能版本 3.1.0。
- 关于收费、价格、具体使用效果等未在资料中明确说明的信息，暂未提供。