Cloudflare Workers Static Assets 静态资源部署避坑指南最佳实践、常见错误与限额解析【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare Workers 的 Static Assets 功能允许开发者将静态资源HTML、CSS、JS、图片等与 Worker 代码一起部署实现静态资源 动态 API混合架构。本文以本仓库cloudflare-deploy技能中的 Static Assets 避坑文档 为主体结合同目录下的 configuration.md、api.md 与 patterns.md 展开系统梳理部署 Workers Static Assets 时必须掌握的最佳实践、高频报错与排查方案、平台限额与版本要求以及四类可落地的性能优化技巧。读完本文你将能够针对 SPA、静态站点与全栈应用正确配置run_worker_first、规避免费额度超限与缓存失效等常见陷阱并写出更省成本、更快的资源投递方案。一、三大最佳实践从源头规避多数问题1. 选择性 Worker-First 路由Selective Worker-First Routing核心结论不要全局开启run_worker_first true应改用数组模式array patterns按路径精确指定哪些路由需要先经过 Worker。{ assets: { run_worker_first: [ /api/*, // API routes /admin/*, // Admin area !/admin/assets/* // Except admin assets ] } }收益文档原文明确列出减少 Worker 调用次数Reduces Worker invocations降低调用成本Lowers costs提升资源投递性能Improves asset delivery performance其底层原理在于 Static Assets 的路由模型run_worker_first决定哪些请求先进入 Worker 再查静态资源。若全局设为true所有静态资源请求包括本可直接由边缘缓存命中的 HTML、CSS、JS都会被塞进 Worker白白消耗免费额度并引入额外延迟而数组语法通过正向匹配/api/*与负向排除!/admin/assets/*的组合只把真正需要动态逻辑的路径交给 Worker其余请求由 Cloudflare 边缘直接服务。关于数组语法的完整规则见 configuration.md正向匹配*匹配任意字符**匹配任意路径段负向匹配以!前缀排除负向模式优先级高于正向模式默认值false资源直接投递不经过 Worker。决策指引官方建议API 优先的应用静态资源很少→ 用true混合应用API 静态资源→ 用数组模式静态优先的站点动态路由极少→ 用false2. 利用导航请求优化Navigation Request Optimization对于 SPA单页应用将compatibility_date设为2025-04-01或更新并配合not_found_handling: single-page-application{ compatibility_date: 2025-04-01, assets: { not_found_handling: single-page-application } }该兼容性日期启用后导航请求navigation requests会跳过 Worker 调用直接由静态资源层响应从而降低成本。这里的机制与not_found_handling直接相关SPA 模式下非资源路径如/about、/dashboard会回落到/index.html返回 200此时若再让每次导航都经过 Worker 就纯属浪费。此项能力有版本门槛——需要Wrangler 4.0.0 且 compatibility_date 为2025-04-01或之后见下文版本要求表。3. 使用绑定保证类型安全Type Safety with Bindings在 TypeScript 中始终为环境Environment声明显式类型interface Env { ASSETS: Fetcher; }这与 api.md 中定义的ASSETS绑定接口完全对应Fetcher.fetch(input: RequestInfo | URL, init?: RequestInit): PromiseResponse。绑定名默认即ASSETS可在配置中通过assets.binding自定义类型声明能让你在编写env.ASSETS.fetch(...)时获得 IDE 补全与静态检查。二、常见错误速查八类高频报错与解决方案以下错误均来自 gotchas.md按现象 → 原因 → 解决组织可作运维排障手册使用。1. Asset not found资源找不到原因资源不在 assets 目录中、路径写错、或资源尚未部署上线。解决确认资源确实存在检查路径大小写文件系统/URL 大小写敏感必要时重新部署。2. Worker not invoked for asset资源未经过 Worker原因资源被直接投递run_worker_first未配置。解决在run_worker_first模式中把需要经 Worker 的资源路由包含进来详见 configuration.md 中数组语法的配置说明。3. 429 Too Many Requests on free tier免费版请求超限原因run_worker_first模式让大量请求触发 Worker 调用撞上免费版每日 10 万次100k req/day的调用上限。解决改用更精准的选择性模式并配合负向排除!前缀或者升级到付费套餐。这是全局true滥用最直接的代价与最佳实践 1 互为印证。4. Smart Placement increases latencySmart Placement 反而增加延迟原因run_worker_first true与 Smart Placement 叠加时所有请求都会被路由到单一智能放置位置静态资源远离了用户边缘节点。解决改用数组语法做选择性路由或在资源密集型应用中关闭 Smart Placement{ placement: { mode: off } }。该问题在 smart-placement/gotchas.md 中有更详细的量化说明当 Smart Placement 与run_worker_first true同时启用时静态资源加载可能慢2~5 倍因为静态内容本应永远从离用户最近的边缘节点提供。正确做法是拆分前端 Worker无 placement 字段留在边缘 后端 API Worker启用 Smart Placement。在 static-assets/gotchas.md 中也强调资源型应用应在选择性数组模式与关闭 Smart Placement之间二选一。5. CF-Cache-Status header unreliable缓存状态头不可靠原因出于隐私考虑CF-Cache-Status头是概率性添加的probabilistically added并非每个响应都带。解决不要将CF-Cache-Status用于关键路由判断逻辑改用其他信号如ETag、age作为缓存状态依据。6. JWT expired during deployment部署时 JWT 过期原因超大体积的资源部署耗时超过了 JWT token 的有效期。解决升级到Wrangler 4.34.0支持自动刷新 token或者减少资源数量/体积。这与版本要求一节中 4.34.0 的里程碑10 万文件上限、JWT 自动刷新一致。7. Cannot use assets with siteassets 与 site 冲突原因旧的site配置与新的assets配置互相冲突。解决从site迁移到assets详见 configuration.md并从wrangler.jsonc中移除site键。8. Assets not updating after deployment部署后资源不更新原因浏览器或 CDN 缓存仍在提供旧资源。解决浏览器硬刷新CmdShiftR/CtrlF5使用缓存破坏cache-busting如内容哈希文件名用wrangler tail确认部署是否真正完成。三、限额表与版本要求部署前先对齐门槛平台限额下表来自 gotchas.md是免费版与付费版的硬性资源边界资源/限额免费版付费版说明单个资源最大体积25 MiB25 MiB按文件计算per file资源总数量20,000100,000需 Wrangler 4.34.02025 年 9 月起Worker 调用次数100k/天1000 万/月用run_worker_first模式优化调用量资源存储空间无限无限已包含在套餐内版本要求功能最低 Wrangler 版本10 万文件上限付费版4.34.0Vite 插件4.0.0 cloudflare/vite-plugin 1.0.0导航请求优化4.0.0 compatibility_date: 2025-04-01注意两点关联JWT 自动刷新与10 万文件上限都落在 Wrangler 4.34.0 这一版本里程碑上而导航请求优化需要同时满足 Wrangler 4.0.0 与兼容性日期两个条件。部署前先执行npx wrangler --version核对版本可避免配置写了却不生效的困惑。四、性能优化四招让资源投递更快更省1. 使用内容哈希文件名Hashed Filenames为长期缓存long-term caching启用内容哈希文件名app.a3b2c1d4.js styles.e5f6g7h8.css文件名随内容变化而变化内容不变则 URL 不变可安全地设置超长max-age。大多数打包器Vite、Webpack、Parcel会自动完成这一行为无需手写。2. 最小化 Worker 调用Minimize Worker Invocations尽可能让资源直接投递只在必要时才进入 Worker{ assets: { // Only invoke Worker for dynamic routes run_worker_first: [/api/*, /auth/*] } }这与最佳实践 1 是同一条原则的两个侧面免费版 100k/天的 Worker 调用额度在全局true的配置下被静态资源请求吃掉的速度极快缩小run_worker_first的匹配面就是在直接省钱。3. 充分利用浏览器缓存Leverage Browser Cache为不同类型的资源设置恰当的Cache-Control头// Versioned assets Cache-Control: public, max-age31536000, immutable // HTML (revalidate often) Cache-Control: public, max-age0, must-revalidate带哈希的版本化资源用一年 immutable永不回源校验HTML 文档则用must-revalidate频繁校验。具体到 Worker 代码里如何给响应改写缓存头见 patterns.md 的 Cache Control Override 模式它用正则/\.[a-f0-9]{8,}\.(js|css|png|jpg)$/识别哈希文件名命中后改写为public, max-age31536000, immutable。补充Static Assets 服务本身默认的缓存策略是Cache-Control: public, max-age36001 小时且响应默认带内容哈希型ETag可用于If-None-Match条件请求返回 304。如需覆盖默认值必须经由 Worker 响应变换见 api.md。4. 使用 .assetsignore 文件通过.assetsignore语法与.gitignore相同排除无需上传的文件缩短上传时间*.map *.md .DS_Store node_modules/常见排除项详见 configuration.md 的 .assetsignore 小节_worker.js—— 排除 Worker 代码混入资源目录*.map—— 排除 source map*.md—— 排除 markdown 文档各类开发期产物。五、附与最佳实践配套的配置与代码模式为了让上述避坑方案可以直接落地这里补上同技能文档中的两个关键配套完整配置选项与 ASSETS 绑定用法。完整配置项一览wrangler.jsonc中assets块的完整选项来源configuration.md{ name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, assets: { directory: ./dist, binding: ASSETS, not_found_handling: single-page-application, html_handling: auto-trailing-slash, run_worker_first: [/api/*, !/api/docs/*] } }directorystring必填资源目录路径如./dist、./public、./buildbindingstring可选Worker 代码中访问资源的绑定名默认ASSETSnot_found_handlingstring可选资源未命中时的行为——single-page-application非资源路径回落到/index.htmlSPA 默认、404-page有/404.html则返回之否则 404、none直接 404html_handlingstring可选HTML 的尾斜杠行为默认auto-trailing-slashrun_worker_firstboolean | string[]可选指定先经 Worker 的路由模式。此外还支持wrangler.jsonc环境级配置env.staging/env.production各自覆盖not_found_handling等部署时用wrangler deploy --env staging指定环境便于预发/生产采用不同的回退策略。ASSETS 绑定Worker 中操作资源的方式api.md 给出了env.ASSETS.fetch()的四种调用形态整体转发请求、字符串路径忽略 hostname 仅取路径、URL 对象、构造的 Request 对象。关键行为是字符串/URL 输入时主机名被忽略只有路径参与解析且仅支持 GET/HEAD其余方法返回 405请求头Accept-Encoding、Range、If-None-Match、If-Modified-Since会透传并影响响应压缩、206 分片、304 条件请求等。在 Worker 中配合run_worker_first的最典型形态是 patterns.md 的 SPA API 模式export default { async fetch(request: Request, env: Env): PromiseResponse { const url new URL(request.url); if (url.pathname.startsWith(/api/)) { return handleAPI(request, env); // 动态接口 } return env.ASSETS.fetch(request); // 静态资源 } };配置上只需run_worker_first: [/api/*]——API 请求先经 Worker 处理其余资源请求直接命中静态资源层。类似地认证拦截/admin/*校验会话后放行、OAuth 回调、基于 Cookie 的 A/B 测试、基于 Accept-Language 的本地化路由等模式都遵循配置里用数组模式圈定动态路径 代码里用env.ASSETS.fetch兜底静态资源的同一套骨架完整可复制的实现见 patterns.md。六、总结上线前的自检清单把本文内容浓缩成一份部署前检查表路由run_worker_first是否用了数组模式而非全局true负向排除是否覆盖了静态子路径SPA是否设置compatibility_date: 2025-04-01或更新 not_found_handling: single-page-application以享受导航请求跳过 Worker 的优化Smart Placement资源类应用是否已关闭 Smart Placement或将前后端拆分为两个 Worker前端留在边缘、后端开 Smart Placement版本Wrangler 是否 ≥ 4.34.0100k 文件上限与 JWT 自动刷新Vite 项目是否满足 4.0.0 cloudflare/vite-plugin1.0.0配额免费版 Worker 调用是否控制在 100k/天以内、资源数量是否在 20,000 以内单文件是否 ≤ 25 MiB缓存是否已用哈希文件名 长缓存头并避免依赖不可靠的CF-Cache-Status做关键判断上传体量.assetsignore是否排除了.map、node_modules等冗余文件以上全部结论与配置示例均可在本仓库 cloudflare-deploy 技能目录 下的 static-assets 参考文档configuration / api / patterns / gotchas 四篇与 smart-placement/gotchas.md、wrangler/gotchas.md 中溯源验证。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考