header

操作 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]
}

• <field> 是头字段的名称。

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

  以 + 为前缀，表示添加该字段，而不是在该字段已存在时覆盖（设置）该字段；头字段可以在请求中出现多次。

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

  以 ? 为前缀，表示为该字段设置默认值。该字段仅在它不存在时写入。

  以 > 为前缀，表示设置该字段并启用 defer，作为快捷方式。

• <value> 是头字段值，用于添加或设置字段。

• <find> 是要搜索的子字符串或正则表达式。

• <replace> 是替换值；如果执行搜索和替换，则需要此值。

• defer 将强制头操作延迟到响应被写入客户端时。如果任何头字段被删除（使用 -）、设置默认值（使用 ?）或使用 > 前缀，则会自动启用此选项。

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

当使用 ? 前缀设置默认头值时，建议将其分离到自己的 header 指令中。 在幕后，使用 ? 配置一个响应匹配器，该匹配器应用于指令的整个处理程序，该处理程序仅在该字段尚未设置时才应用头操作。例如，在同一个指令中，您有以下两个操作：-Hidden 和 ?Foo default，那么 Hidden 头 仅 在 Foo 为空时被删除，这通常不是预期效果。

示例

在所有请求上设置自定义头字段

header Custom-Header "My value"

删除 "Hidden" 头字段

header -Hidden

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

header Location http:// https://

在所有页面上设置安全和隐私头：（警告： 仅在您了解其含义时使用！）

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

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

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

要对 Set-Cookie 头进行延迟更新以添加 SameSite=None；使用正则表达式捕获来获取现有值，并使用 $1 将其重新插入开头，并附加额外的选项

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