Static Assets 常见陷阱

## 最佳实践 ### 1. 使用选择性的 Worker 优先路由 不要使用 `run_worker_first = true`，应使用数组模式： c { "assets": { "run_worker_first": [ "/api/*", // API 路由 "/admin/*", // 管理后台 "!/admin/assets/*" // 除了管理后台资源 ] } } **优势:** - 减少 Worker 调用次数 - 降低成本 - 提升资源交付性能 ### 2. 利用导航请求优化 对于 SPA，使用 `compatibility_date = "2025-04-01"` 或更高版本： c { "compatibility_date": "2025-04-01", "assets": { "not_found_handling": "single-page-application" } } 导航请求将跳过 Worker 调用，从而降低成本。 ### 3. 绑定的类型安全 始终为环境定义类型： typescript interface Env { ASSETS: Fetcher; } ## 常见错误 ### "Asset not found" (资源未找到) **原因:** 资源不在资源目录中、路径错误或资源未部署 **解决方案:** 验证资源是否存在，检查路径大小写敏感性，必要时重新部署 ### "Worker not invoked for asset" (资源未触发 Worker) **原因:** 资源被直接服务，未配置 `run_worker_first` **解决方案:** 配置 `run_worker_first` 模式以包含资源路由 (参见 configuration.md:66-106) ### "429 Too Many Requests on free tier" (免费层级请求过多) **原因:** `run_worker_first` 模式导致大量请求触发 Worker，达到免费额度限制 (10 万次请求/天) **解决方案:** 使用更具选择性的模式（带排除项），或升级到付费计划 ### "Smart Placement increases latency" (智能放置增加延迟) **原因:** `run_worker_first=true` + 智能放置将所有请求路由到单个智能放置位置 **解决方案:** 使用选择性模式（数组语法），或为资源密集型应用禁用智能放置 ### "CF-Cache-Status header unreliable" (CF-Cache-Status 响应头不可靠) **原因:** 出于隐私原因，该响应头是概率性添加的 **解决方案:** 不要依赖 `CF-Cache-Status` 进行关键路由逻辑。使用其他信号 (ETag, age)。 ### "JWT expired during deployment" (部署期间 JWT 过期) **原因:** 大规模资源部署超过了 JWT 令牌有效期 **解决方案:** 更新至 Wrangler 4.34.0+ (自动令牌刷新)，或减少资源数量 ### "Cannot use 'assets' with 'site'" (不能同时使用 'assets' 和 'site') **原因:** 旧版 `site` 配置与新的 `assets` 配置冲突 **解决方案:** 从 `site` 迁移到 `assets` (参见 configuration.md)。从 wrangler.jsonc 中移除 `site` 键。 ### "Assets not updating after deployment" (部署后资源未更新) **原因:** 浏览器或 CDN 缓存了旧资源 **解决方案:** - 强制刷新