header

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

默认情况下，头操作会立即执行，除非正在删除头（- 前缀）或设置默认值（? 前缀）。在这些情况下，头操作会自动延迟到写入客户端时执行。

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

语法

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

	# 设置
	<field> <value>

	# 延迟设置
	><field> <value>

	# 删除
	-<field>

	# 替换
	<field> <find> <replace>

	# 延迟替换
	><field> <find> <replace>

	# 默认值
	?<field> <value>

	[defer]
}

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

  无前缀时，字段会被设置（覆盖）。

  前缀为 + 时，如果字段已存在则添加而非覆盖（设置）；头字段可以在请求中出现多次。

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

  前缀为 ? 时，为字段设置默认值。仅当字段尚不存在时才写入。

  前缀为 > 时，设置字段并启用 defer，作为快捷方式。

• <value> 是添加或设置字段时的头字段值。

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

• <replace> 是替换值；执行搜索替换时必需。使用 $1 或 $2 等引用搜索模式中的捕获组。如果替换值为 ""，则从值中删除匹配的文本。详情请参阅 Go 文档。

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

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

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

示例

为所有请求设置自定义头字段：

header Custom-Header "My value"

删除 "Hidden" 头字段：

header -Hidden

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

header Location http:// https://

为所有页面设置安全和隐私头：（警告： 仅在你了解其影响时使用！）

header {
	# 禁用 FLoC 跟踪
	Permissions-Policy interest-cohort=()

	# 启用 HSTS
	Strict-Transport-Security max-age=31536000;

	# 禁止客户端嗅探媒体类型
	X-Content-Type-Options nosniff

	# 点击劫持保护
	X-Frame-Options DENY
}

多个互斥的 header 指令：

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