header (Caddyfile directive) — Caddy v2中文文档

操作 HTTP 响应标头字段。它可以设置、添加和删除标头值，或使用正则表达式执行替换。

默认情况下，除非删除任何标头（-前缀）或设置默认值（?前缀），否则立即执行标头操作。在这些情况下，标头操作会自动推迟，直到将它们写入客户端为止。

要操作 HTTP 请求标头，您可以使用request_header指令。

语法

header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
	# Add
	+<field> <value>

	# Set
	<field> <value>

	# Set with defer
	><field> <value>

	# Delete
	-<field>

	# Replace
	<field> <find> <replace>

	# Replace with defer
	><field> <find> <replace>

	# Default
	?<field> <value>

	[defer]

	match <inline_response_matcher>
}

<field> 是头字段的名称。

如果没有前缀，该字段将被设置（覆盖）。

以+为前缀来添加该字段，而不是覆盖（设置）该字段（如果该字段已存在）；标头字段可以在响应中出现多次。

前缀为-即可删除该字段。该字段可以使用前缀或后缀*通配符来删除所有匹配的字段。

以?为前缀来设置该字段的默认值。仅当该字段尚不存在时才会写入。

以>为前缀设置该字段，并启用defer作为快捷方式。
<value> 是添加或设置字段时的标头字段值。
<find> 是要搜索的正则表达式。占位符可用于动态输入搜索模式。使用的正则表达式语言是 RE2，包含在 Go 中。请参阅RE2 语法参考和Go regexp 语法概述。
<replace> 为重置值；如果执行搜索和替换，则需要。使用$1或$2等从搜索模式引用捕获组。如果替换值为""，则将从该值中删除匹配的文本。详情请见Go documentation。
defer 推迟标头操作的执行，直到响应发送到客户端。该选项在以下条件下自动启用：
- 使用-删除任何标头字段时。
- 使用?设置默认值时。
- 在设置或替换操作中使用>前缀时。
- 当存在一个或多个match条件时。
match是内联响应匹配器。标头操作仅适用于满足指定条件的响应。

对于多个标头操作，您可以打开一个块并以相同的方式为每行指定一个操作。

当使用?前缀设置默认标头值时，如果它位于具有多个标头操作的header块中，它会自动分离到自己的header处理程序中。在底层，使用?配置一个响应匹配器，它应用于指令的整个处理程序，它仅应用标头操作（如defer），但前提是该字段尚未设置。

示例

在所有响应上设置自定义标头字段：

header Custom-Header "My value"

删除“隐藏”标头字段：

header -Hidden

在任何 Location 标头中将http://替换为https://：

header Location http:// https://

在所有页面上设置安全和隐私标题：（**WARNING:**仅在您了解其含义时使用！）

header {
	# disable FLoC tracking
	Permissions-Policy interest-cohort=()

	# enable HSTS
	Strict-Transport-Security max-age=31536000;

	# disable clients from sniffing the media type
	X-Content-Type-Options nosniff

	# clickjacking protection
	X-Frame-Options DENY
}

旨在互斥的多个标头指令：

route {
	header           Cache-Control max-age=3600
	header /static/* Cache-Control max-age=31536000
}

如果上游未定义缓存过期时间，则设置默认缓存过期时间：

header ?Cache-Control "max-age=3600"
reverse_proxy upstream:443

将所有对 GET 请求的成功响应标记为可缓存长达一个小时：

@GET method GET
header @GET Cache-Control "max-age=3600" {
	match status 2xx
}
reverse_proxy upstream:443

防止在上游服务器发生异常时缓存错误响应：

header {
	-Cache-Control
	-CDN-Cache-Control
	match status 500
}
reverse_proxy upstream:443

如果上游服务器支持客户端提示，则将浅色模式响应标记为可与深色模式响应单独缓存：

header {
	Cache-Control "max-age=3600"
	Vary "Sec-CH-Prefers-Color-Scheme"
	match {
		header Accept-CH "*Sec-CH-Prefers-Color-Scheme*"
		header Critical-CH "Sec-CH-Prefers-Color-Scheme"
	}
}
reverse_proxy upstream:443

通过用特定域替换通配符值来防止过度宽松的 CORS 标头：

header >Access-Control-Allow-Origin "\*" "allowed-partner.com"
reverse_proxy upstream:443

Note：在替换操作中，<find>值被解释为正则表达式。要匹配*字符，必须使用反斜杠对其进行转义，如上例所示。

或者，您可以使用响应匹配器逐字匹配标头值：

header Access-Control-Allow-Origin "allowed-partner.com" {
	match header Access-Control-Allow-Origin *
}
reverse_proxy upstream:443

覆盖代理上游为以/no-cache开头的路径设置的缓存过期时间；启用defer是必要的，以确保在代理写入其标头之后设置标头：

header /no-cache* >Cache-Control no-cache
reverse_proxy upstream:443

执行Set-Cookie标头的延迟更新以添加SameSite=None；正则表达式捕获用于获取现有值，$1在开头重新插入它并附加附加选项：

header >Set-Cookie (.*) "$1; SameSite=None;"