提供静态资产时,Workers 会默认在响应中附加一些标头,包括:
-
Content-Type若在资产上传过程中提供了
Content-Type标头,响应会附加该标头。Wrangler 会根据文件扩展名自动确定 MIME 类型。 -
Cache-Control: public, max-age=0, must-revalidate当请求不含
Authorization或Range标头时发送,此响应标头告知浏览器可以缓存资产,但每次使用前都应重新验证内容是否仍有效。该默认行为在静态页面性能与避免提供过期内容之间取得平衡。 -
ETag此标头与默认
Cache-Control标头配合使用。其值为静态资产文件的哈希,浏览器可在后续请求中使用If-None-Match标头检查 freshness,匹配时无需重新下载整个文件。 -
CF-Cache-Status此标头表示资产是否从缓存提供(
HIT)或未命中(MISS)。1
Cloudflare 保留随时为静态资产响应附加新标头的权利,以提升性能或加强 Worker 应用的安全性。
可以通过在项目静态资产目录中创建无文件扩展名的纯文本文件 _headers,覆盖、移除或向静态资产响应的默认响应标头添加内容。该文件本身不会作为静态资产提供,而是由 Workers 解析,并将其规则应用到静态资产响应。
如果使用框架,通常会有一个名为 public/ 或 static/ 的目录,其中包含可直接部署的资源,例如网站图标、robots.txt 文件和站点清单。这些文件会在构建时复制到最终输出目录,因此适合在此编写 _headers 文件。如果不使用框架,可以将 _headers 文件直接放入静态资源目录。
_headers 文件中定义的标头会覆盖 Cloudflare 通常发送的标头。
标头规则以多行块定义。块的第一行是应应用该规则标头的 URL 或 URL 模式。下一行必须写入缩进的标头名称和标头值列表:
[url]
[name]: [value]支持使用绝对 URL,但请注意绝对 URL 必须以 https 开头,且不支持指定端口。_headers 规则在与传入请求匹配时会忽略传入请求的端口和协议。例如,类似 https://example.com/path 的规则会匹配到 other://example.com:1234/path 的请求。
你可以在后续行定义任意数量的 [name]: [value] 对。例如:
# This is a comment
/secure/page
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
/static/*
Access-Control-Allow-Origin: *
X-Robots-Tag: nosnippet
https://myworker.mysubdomain.workers.dev/*
X-Robots-Tag: noindex匹配多个规则 URL 模式的传入请求会继承所有规则的标头。使用上一个 _headers 文件时,以下请求会应用以下标头:
| 请求 URL | 标头 |
|---|---|
https://custom.domain/secure/page |
X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: no-referrer |
https://custom.domain/static/image.jpg |
Access-Control-Allow-Origin: * X-Robots-Tag: nosnippet |
https://myworker.mysubdomain.workers.dev/home ↗ |
X-Robots-Tag: noindex |
https://myworker.mysubdomain.workers.dev/secure/page ↗ |
X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: no-referrer X-Robots-Tag: noindex |
https://myworker.mysubdomain.workers.dev/static/styles.css ↗ |
Access-Control-Allow-Origin: * X-Robots-Tag: nosnippet, noindex |
最多可定义 100 条标头规则。_headers 文件中每一行有 2,000 个字符的限制。整行(包括空格、标头名称和值)都计入此限制。
如果同一标头在 _headers 文件中应用两次,值会用逗号分隔符连接。
你可能希望移除默认标头,或由更广泛规则添加的标头。可以在标头名称前加上感叹号和空格(! )来实现。
/*
Content-Security-Policy: default-src 'self';
/*.jpg
! Content-Security-Policy_redirects 提供的相同 URL 匹配功能也适用于 _headers 文件。但请注意,重定向先于标头应用,因此当请求同时匹配重定向和标头时,重定向优先。
匹配时,由星号(*)表示的 splat 模式会贪婪匹配所有字符。URL 中只能包含一个 splat。
匹配到的值可以在标头值中以 :splat 占位符引用。
占位符可以使用 :placeholder_name 定义。冒号(:)后跟字母表示占位符的开始,其后的占位符名称必须由字母数字字符和下划线组成(:[A-Za-z]\w*)。每个命名占位符只能引用一次。占位符匹配除分隔符之外的所有字符;当分隔符是主机的一部分时,分隔符是句点(.)或正斜杠(/),当分隔符是路径的一部分时,分隔符只能是正斜杠(/)。
同样,匹配的值可以在 header 值中使用 :placeholder_name。
/movies/:title
x-movie-name: You are watching ":title"要允许其他域从你的 Worker 获取每个静态资产,可以向 _headers 文件添加以下内容:
/*
Access-Control-Allow-Origin: *这会将 Access-Control-Allow-Origin 标头应用到任何传入 URL。请注意,CORS 规范仅允许 *、null 或精确 origin 作为有效的 Access-Control-Allow-Origin 值 — origin 内的通配符模式不受支持。要允许来自特定 Version URL 的 CORS,你需要在 Worker 代码中动态处理,而不是通过 _headers 文件。
Google ↗ 和其他搜索引擎通常支持 X-Robots-Tag 标头,以指示爬虫如何索引你的网站。
例如,要防止 *.*.workers.dev URL 被索引,请向 _headers 文件添加以下内容:
https://:version.:subdomain.workers.dev/*
X-Robots-Tag: noindex如果你有指纹化资源文件夹(文件名中包含哈希的资源),可以在浏览器中配置更积极的缓存行为,以提升回访访客的性能:
/static/*
Cache-Control: public, max-age=31556952, immutable你可以通过 X-Frame-Options ↗ 标头告知浏览器不要将应用嵌入到另一个页面中(例如使用 <iframe>),以防止点击劫持。
X-Content-Type-Options: nosniff ↗ 可防止浏览器将响应解释为 Content-Type 标头定义之外的任何其他内容类型。
Referrer-Policy ↗ 允许你自定义访问者离开页面时提供多少来源信息。
可以使用最近从 Feature-Policy 重命名的 Permissions-Policy ↗ 标头,在不同程度上禁用浏览器功能。
如果你需要对应用内容进行细粒度控制,Content-Security-Policy ↗ 标头允许你配置多项安全设置,包括与 X-Frame-Options 标头类似的控制。
/app/*
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Permissions-Policy: document-domain=()
Content-Security-Policy: script-src 'self'; frame-ancestors 'none';-
由于我们未来希望解决的技术限制,
CF-Cache-Status标头并非始终完全准确,可能出现假阳性和假阴性,但应属少见。在此之前,可将此标头视为返回“概率性”结果。 ↩