跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

标头

最后更新 查看 MarkdownAgent 设置

默认标头

提供静态资产时,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 文件。但请注意,重定向先于标头应用,因此当请求同时匹配重定向和标头时,重定向优先。

Splats

匹配时,由星号(*)表示的 splat 模式会贪婪匹配所有字符。URL 中只能包含一个 splat。

匹配到的值可以在标头值中以 :splat 占位符引用。

占位符

占位符可以使用 :placeholder_name 定义。冒号(:)后跟字母表示占位符的开始,其后的占位符名称必须由字母数字字符和下划线组成(:[A-Za-z]\w*)。每个命名占位符只能引用一次。占位符匹配除分隔符之外的所有字符;当分隔符是主机的一部分时,分隔符是句点(.)或正斜杠(/),当分隔符是路径的一部分时,分隔符只能是正斜杠(/)。

同样,匹配的值可以在 header 值中使用 :placeholder_name。

/movies/:title
  x-movie-name: You are watching ":title"

示例

跨源资源共享(CORS)

要允许其他域从你的 Worker 获取每个静态资产,可以向 _headers 文件添加以下内容:

/*
  Access-Control-Allow-Origin: *

这会将 Access-Control-Allow-Origin 标头应用到任何传入 URL。请注意,CORS 规范仅允许 *、null 或精确 origin 作为有效的 Access-Control-Allow-Origin 值 — origin 内的通配符模式不受支持。要允许来自特定 Version URL 的 CORS,你需要在 Worker 代码中动态处理,而不是通过 _headers 文件。

防止 workers.dev URL 出现在搜索结果中

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';

Footnotes

  1. 由于我们未来希望解决的技术限制,CF-Cache-Status 标头并非始终完全准确,可能出现假阳性和假阴性,但应属少见。在此之前,可将此标头视为返回“概率性”结果。 ↩

这篇文档对您有帮助吗?