Apache 模块 mod_headers

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

Header 指令

描述	配置 HTTP 响应头
语法	Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note header [[expr=]value [replacement] [early|env=[!]varname|expr=expression]]
上下文	服务器配置、虚拟主机、目录、.htaccess
覆盖	FileInfo
状态	扩展
模块	mod_headers
兼容性	SetIfEmpty 在 2.4.7 及更高版本中可用，expr=value 在 2.4.10 及更高版本中可用

此指令可以替换、合并或删除 HTTP 响应头。头在内容处理程序和输出过滤器运行之后立即被修改，允许修改传出的头。

可选的 condition 参数决定此指令将针对哪个内部响应头表进行操作：onsuccess（默认，可以省略）或 always。这两个列表之间的区别在于，后者包含的头即使在错误情况下也会添加到响应中，并在内部重定向（例如，ErrorDocument 处理程序）中持久化。还要注意，在某些情况下，使用这两个条件重复此指令是有意义的，因为 always 对于现有头来说不是 onsuccess 的超集

• 您正在向本地生成的非成功（非 2xx）响应添加头，例如重定向，在这种情况下，最终响应中只使用与 always 对应的表。
• 您正在修改或删除由 CGI 脚本或 mod_proxy_fcgi 生成的头，在这种情况下，CGI 脚本的头位于与 always 对应的表中，而不是在默认表中。
• 您正在修改或删除由服务器的一部分生成的某个头，但该头在默认的 onsuccess 条件下没有找到。

onsuccess 和 always 之间的这种区别是一个特性，它是在 httpd 如何在内部存储 HTTP 响应的头时产生的结果，因为它不提供任何 "规范化" 的单个头列表。如果在编写配置时没有牢记以下概念，可能会出现的主要问题是，某些 HTTP 响应最终可能会包含重复的相同头（使用户或有时甚至 HTTP 客户端感到困惑）。例如，假设您有一个使用 mod_proxy_fcgi 的简单 PHP 代理设置，并且您的后端 PHP 脚本将 X-Foo: bar 头添加到每个 HTTP 响应中。如上所述，mod_proxy_fcgi 使用 always 表来存储头，因此以下配置最终会导致错误的结果，即头被重复，并且包含两个值

# X-Foo's value is set in the 'onsuccess' headers table
Header set X-Foo: baz

为了规避此限制，有一些已知的配置模式可以提供帮助，例如以下模式

# 'onsuccess' can be omitted since it is the default
Header onsuccess unset X-Foo
Header always set X-Foo "baz"

除了上面描述的 condition 参数之外，您还可以根据 HTTP 状态代码来限制操作，例如代理或 CGI 请求。请参阅上面部分中使用 %{REQUEST_STATUS} 的示例。

它执行的操作由第一个参数（如果指定了 condition，则为第二个参数）决定。这可以是以下值之一

add

响应头将被添加到现有的头集中，即使此头已经存在。这可能导致两个（或更多）头具有相同的名称。这可能导致不可预见的后果，通常应该使用 set、append 或 merge 代替。

append

响应头将被追加到任何具有相同名称的现有头。当将新值合并到现有头时，它将用逗号与现有头隔开。这是为头提供多个值的 HTTP 标准方法。

echo

具有此名称的请求头将在响应头中回显。 header 可以是 正则表达式。必须省略 value。

edit

edit*

如果此响应头存在，则其值将根据 正则表达式 搜索和替换进行转换。 value 参数是 正则表达式，而 replacement 是替换字符串，它可能包含反向引用或格式说明符。 edit 形式将在一个头值中精确匹配和替换一次，而 edit* 形式将替换搜索模式的所有实例，如果它出现不止一次。

merge

响应头将被追加到任何具有相同名称的现有头，除非要追加的值已出现在头的逗号分隔值列表中。当将新值合并到现有头时，它将用逗号与现有头隔开。这是为头提供多个值的 HTTP 标准方法。值以区分大小写的方式进行比较，并且在处理完所有格式说明符之后进行比较。用双引号括起来的值被认为与其他相同的未加引号的值不同。

set

设置响应头，用此名称替换任何先前存在的头。 value 可以是格式字符串。

setifempty

设置请求头，但前提是之前没有同名头。

Content-Type 头是一个特殊情况，因为它的值可能已经确定，但当评估 setifempty 时，该头并不在响应中。在这种情况下，使用 set 更安全，例如：

Header set Content-Type "text/plain" "expr=-z %{CONTENT_TYPE}"

unset

如果存在，则删除此名称的响应头。如果存在多个同名头，则全部删除。 value 必须省略。

note

将命名响应 header 的值复制到一个内部注释中，该注释的名称由 value 给出。如果由 CGI 或代理资源发送的头被配置为取消设置，但也要记录，这将很有用。
在 2.4.7 及更高版本中可用。

此参数后跟一个 header 名称，可以包含最后的冒号，但不是必需的。对于 set、append、merge、add、unset 和 edit，不区分大小写。echo 的 header 名称区分大小写，可以是 正则表达式。

对于 set、append、merge 和 add，value 指定为下一个参数。如果 value 包含空格，则应将其用双引号括起来。 value 可以是字符字符串、包含 mod_headers 特定格式说明符（和字符字面量）的字符串，或者以 expr= 为前缀的 ap_expr 表达式。

以下格式说明符在 value 中受支持。

格式	描述
%%	百分号
%t	自纪元（1970 年 1 月 1 日）以来的请求接收时间，以微秒为单位，以通用协调时间表示。该值以 t= 为前缀。
%D	从请求接收时间到头在网络上传输的时间。这是请求持续时间的度量。该值以 D= 为前缀。该值以微秒为单位。
%l	实际服务器本身的当前负载平均值。它旨在公开 getloadavg() 获得的值，它表示当前负载平均值、5 分钟平均值和 15 分钟平均值。该值以 l= 为前缀，每个平均值之间用 / 分隔。 在 2.4.4 及更高版本中可用。
%i	基于可用进程和线程的 httpd 的当前空闲百分比（0 到 100）。该值以 i= 为前缀。 在 2.4.4 及更高版本中可用。
%b	基于可用进程和线程的 httpd 的当前繁忙百分比（0 到 100）。该值以 b= 为前缀。 在 2.4.4 及更高版本中可用。
%{VARNAME}e	环境变量 VARNAME 的内容。
%{VARNAME}s	如果启用了 mod_ssl，则为 SSL 环境变量 VARNAME 的内容。

对于 edit，既有 value 参数，它是一个 正则表达式，还有一个额外的 replacement 字符串。从 2.4.7 版本开始，替换字符串也可以包含格式说明符。

Header 指令后可以跟一个额外的参数，它可以是以下任何一个：

early

指定 早期处理。

env=[!]varname

当且仅当环境变量 varname 存在时，才会应用该指令。varname 前面的 ! 反转测试，因此该指令仅在 varname 未设置时才应用。

expr=expression

当且仅当 expression 评估为真时，才会应用该指令。表达式语法和评估的详细信息在 ap_expr 文档中记录。

# This delays the evaluation of the condition clause compared to <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"

除了 早期 模式外，Header 指令在响应发送到网络之前处理。这意味着可以设置和/或覆盖大多数头，除了 HTTP 头过滤器添加的一些头。在 2.2.12 之前，无法使用此指令更改 Content-Type 头。

RequestHeader Directive

描述	配置 HTTP 请求头
语法	RequestHeader add|append|edit|edit*|merge|set|setifempty|unset header [[expr=]value [replacement] [early|env=[!]varname|expr=expression]]
上下文	服务器配置、虚拟主机、目录、.htaccess
覆盖	FileInfo
状态	扩展
模块	mod_headers
兼容性	SetIfEmpty 在 2.4.7 及更高版本中可用，expr=value 在 2.4.10 及更高版本中可用

此指令可以替换、合并、更改或删除 HTTP 请求头。头在内容处理程序运行之前修改，允许修改传入的头。它执行的操作由第一个参数决定。它可以是以下值之一：

add

将请求头添加到现有的头集中，即使该头已经存在。这会导致两个（或更多）头具有相同的名称。这会导致不可预见的后果，通常应使用 set、append 或 merge 代替。

append

将请求头追加到任何现有的同名头。当将新值合并到现有头时，它与现有头之间用逗号分隔。这是 HTTP 标准中为头提供多个值的规范方法。

edit

edit*

如果此请求头存在，则根据 正则表达式 搜索和替换对其值进行转换。 value 参数是一个 正则表达式，replacement 是一个替换字符串，它可以包含反向引用或格式说明符。edit 形式将在头值中匹配并替换一次，而 edit* 形式将替换搜索模式的每个实例，如果它出现不止一次。

merge

将请求头追加到任何现有的同名头，除非要追加的值已出现在现有头的逗号分隔值列表中。当将新值合并到现有头时，它与现有头之间用逗号分隔。这是 HTTP 标准中为头提供多个值的规范方法。值比较区分大小写，并且在处理完所有格式说明符后进行。双引号中的值与其他相同但未加引号的值不同。

set

设置请求头，用此名称替换任何先前存在的头。

setifempty

设置请求头，但前提是之前没有同名头。
在 2.4.7 及更高版本中可用。

unset

如果存在，则删除此名称的请求头。如果存在多个同名头，则全部删除。 value 必须省略。

此参数后跟一个头名称，可以包含最后的冒号，但不是必需的。不区分大小写。对于 set、append、merge 和 add，第三个参数是 value。如果 value 包含空格，则应将其用双引号括起来。对于 unset，不应给出 value。 value 可以是字符字符串、包含格式说明符的字符串或两者的组合。支持的格式说明符与 Header 相同，请查看那里以了解详细信息。对于 edit，需要 value 和 replacement，它们分别是 正则表达式 和替换字符串。

RequestHeader 指令后可以跟一个额外的参数，它可以是以下任何一个：

early

指定 早期处理。

env=[!]varname

当且仅当环境变量 varname 存在时，才会应用该指令。varname 前面的 ! 反转测试，因此该指令仅在 varname 未设置时才应用。

expr=expression

当且仅当 expression 评估为真时，才会应用该指令。表达式语法和评估的详细信息在 ap_expr 文档中记录。

除了 早期 模式外，RequestHeader 指令在请求由其处理程序在修复阶段运行之前处理。这应该允许覆盖或修改由浏览器或 Apache 输入过滤器生成的标头。