第17章 静态资源(Static Assets)
文档:静态资源
静态资源用于提供目录中的文件,既可以配合 Worker 运行,也可以独立运行。`celld deploy` 会将该目录上传到集群存储桶(fleet bucket)中,节点在首次提供某文件时,会将该文件缓存到本地磁盘。标准行为请参阅 Cloudflare 静态资源文档。
示例
静态资源示例从 public 目录提供 HTML 文件,无需 Worker。`_headers` 文件用于添加响应头,`_redirects` 文件则将 /home 重定向到 /。
``` public/_headers /* X-Served-By: celld ```
``` public/_redirects /home / 301 ```
```html public/index.html
``` wrangler.jsonc { "name": "static-assets", "compatibility_date": "2026-01-01", "assets": { "directory": "./public" } } ```
API
assets 配置块用于设置目录和路由规则:
directory 指定要上传的目录。 binding 向 Worker 暴露 env.ASSETS.fetch()。 html_handling 将路径映射到 HTML 文件。 not_found_handling 选择单页应用(single-page-application)或 404 页面(404-page)。 run_worker_first 优先将匹配的请求发送给 Worker。 目录中的 _headers 和 _redirects 文件用于设置请求头和重定向规则。
部署
assets 配置块接受 directory、binding、html_handling、not_found_handling 和 run_worker_first 这些键。若包含其他键,部署将终止。若项目配置了 assets 但未设置 main(入口),则不能设置 run_worker_first 或声明 binding。
celld deploy 将每个文件体(file body)存储一次,并以其 SHA-256 摘要为键。重新部署时,仅上传发生变化的文件体。对于扩展名未知的文件,不会生成 Content-Type 头,这与 Wrangler 的行为一致。
路由
celld 仅针对 GET 或 HEAD 请求查找静态资源,其他所有方法均交由 Worker 处理。run_worker_first 可设为 true,或设置为最多 100 条路由模式列表,其中以 ! 开头的模式用于排除特定路径。匹配到的请求会优先发送给 Worker。精确的 / 模式仅匹配根路径。
celld 如何决定由静态资源还是 Worker 响应
请求到达节点后,会依次通过一系列测试。若方法不是 GET 或 HEAD,立即交由 Worker 响应。若路径匹配 run_worker_first 规则,也立即交由 Worker 响应,且不会进行资源查找。
接下来运行 _redirects 规则,按文件顺序执行,首个匹配项生效:状态码 301、302、303、307 或 308 会返回带 Location 头的响应且无响应体;状态码 200 会在目标路径处重新开始路由。
随后 html_handling 查找文件:若路径精确匹配,返回 200 及文件体;若为其他拼写形式,则重定向 307 至规范路径。
查找失败后,节点会重新读取部署指针,频率最多为每 5 秒一次,以便新部署也能提供响应。not_found_handling 生成最终响应,但仅适用于导航请求或无 Worker 的部署:single-page-application 返回 /index.html 并附带 200 状态码;404-page 返回最近的 404.html 并附带 404 状态码。若所有规则均未匹配,则由 Worker 响应;若部署中无 Worker,则返回 404。绿色结果来自资源层,灰色结果来自 Worker。此外,若资源文件体缺失或损坏,返回 502,绝不会回退到 Worker。
一个请求到达节点,由谁响应,结果是什么
* 方法非 GET 或 HEAD:由 Worker 响应 * run_worker_first 设为 true 或最多 100 条模式:由 Worker 响应,不进行资源查找 * _redirects 按文件顺序,首个匹配生效: * 301 302 303 307 308:返回 Location 头,无响应体 * 200:在目标处重新开始 * html_handling 为 auto、force、drop 或 none: * 规范路径:返回 200 及响应体 * 其他拼写:307 重定向至规范路径 * 未匹配:重新读取指针,每 5 秒最多一次 * 新部署包含该资源:返回 200 及响应体 * not_found_handling 适用于导航请求或无 Worker 的情况: * single-page-application:/index.html,200 * 404-page:最近的 404.html,404 * 所有规则均未匹配:由 Worker 响应;若无 Worker,则返回 404 * 资源文件体缺失或损坏返回 502。请求绝不会回退到 Worker。
_redirects 规则在任何文件查找之前运行,且首个匹配项生效。状态码为 301、302、303、307 或 308 的规则会返回带 Location 头的响应。状态码为 200 的规则会在本地路径处重新开始路由,并保留原始 URL。
html_handling 默认为 auto-trailing-slash,将 /about 映射到 /about.html,将 /about/ 映射到 /about/index.html。其他模式包括 force-trailing-slash、drop-trailing-slash 和 none。非规范拼写会 307 重定向至规范路径,并保留查询字符串。
查找失败后,节点每 5 秒最多重新读取一次部署指针。在滚动重启期间,新索引因此可以处理已升级节点引用的文件。
not_found_handling 设为 single-page-application 时,返回 /index.html 并附带 200 状态码;设为 404-page 时,返回最近的 404.html 并附带 404 状态码。若存在 Worker,celld 仅对导航请求应用此逻辑,Worker 会处理其他所有未匹配请求。若无 Worker 且无匹配,节点返回 404。若集群存储桶无法提供文件体,则返回 502,且绝不会到达 Worker。
响应
磁盘缓存默认为 512 MiB,可通过 CELLD_ASSET_CACHE_BYTES 修改。缓存策略为淘汰最近最少使用的文件。
ETag 是文件体的 SHA-256 强摘要,因此 If-None-Match 头会触发 304 响应。Range 头触发 206,无效的 Range 触发 416,HEAD 响应保留真实的 Content-Length。普通响应附带 Cache-Control: public, max-age=0, must-revalidate。可使用 _headers 规则为内容哈希文件设置较长的 Cache-Control。
binding 暴露 env.ASSETS.fetch(),接受 Request、URL 或字符串作为参数。若方法非 GET 或 HEAD,则返回 405;始终应用 not_found_handling。
与 Cloudflare 的区别
celld 不会压缩静态资源响应。若客户端需要 gzip 或 brotli,请使用支持压缩的入口代理。 celld 没有边缘缓存。每个节点维护 512 MiB 的磁盘缓存(由 CELLD_ASSET_CACHE_BYTES 配置),并要求浏览器重新验证。 节点在资源查找失败后,每 5 秒最多检查一次部署指针。 celld 读取 If-None-Match 和 If-Range 头。它不发送 Last-Modified 头,也不读取 If-Modified-Since 头。 _headers 文件无法更改 connection、content-length 或 transfer-encoding。 单个部署最多包含 20,000 个资源,总大小 1 GiB。单个文件最大 25 MiB。CELLD_MAX_ASSET_FILE_BYTES 可修改单文件限制,该值必须在部署构建器、托管部署代理和提供服务的节点上保持一致。进程仅在启动时读取一次该变量,因此修改后需重启进程。若文件过大,错误信息会报告该文件的路径、大小及限制值。每个 _headers 或 _redirects 文件限制为 100 KiB。 celld deploy 的 assets 配置块仅接受 directory、binding、html_handling、not_found_handling 和 run_worker_first。 celld deploy 会拒绝 .assetsignore 文件,并因此终止部署而非忽略该文件。它同样拒绝符号链接、特殊文件、非 UTF-8 命名、不安全的解码路径以及 _worker.js 条目。 assets binding 仅包含一个方法:fetch()。celld 不提供 unstable_ 辅助工具。
Cloudflare 兼容性页面列出了运行时 API 及不支持的服务。