Apache 模块 mod_include

启用服务器端包含

服务器端包含由 INCLUDES 过滤器 实现。如果包含服务器端包含指令的文档被赋予扩展名 .shtml，则以下指令将使 Apache 解析它们并将生成的文档分配为 text/html 的 MIME 类型

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

以下指令必须为包含 shtml 文件的目录提供（通常在 <Directory> 部分中，但此指令在 .htaccess 文件中也有效，如果 AllowOverride Options 已设置）

Options +Includes

为了向后兼容，server-parsed 处理程序 也会激活 INCLUDES 过滤器。同样，Apache 会为任何 MIME 类型为 text/x-server-parsed-html 或 text/x-server-parsed-html3 的文档激活 INCLUDES 过滤器（生成的输出将具有 MIME 类型 text/html）。

有关更多信息，请参阅我们的 服务器端包含教程。

PATH_INFO 与服务器端包含

默认情况下，处理服务器端包含的文件不再接受带有 PATH_INFO（尾随路径信息）的请求。您可以使用 AcceptPathInfo 指令配置服务器以接受带有 PATH_INFO 的请求。

可用元素

文档被解析为 HTML 文档，其中嵌入特殊命令作为 SGML 注释。命令的语法为

值通常用双引号括起来，但单引号 (') 和反引号 (`) 也是可能的。许多命令只允许一个属性-值对。请注意，注释终止符 (-->) 应以空格开头，以确保它不被视为 SSI 令牌的一部分。请注意，前导 <!--# 是一个令牌，不能包含任何空格。

允许的元素在以下表格中列出

元素	描述
comment	SSI 注释
config	配置输出格式
echo	打印变量
exec	执行外部程序
fsize	打印文件的大小
flastmod	打印文件的最后修改时间
include	包含文件
printenv	打印所有可用变量
set	设置变量的值

SSI 元素可能由除 mod_include 之外的模块定义。实际上，exec 元素由 mod_cgi 提供，并且只有在加载此模块时才可用。

注释元素

此命令不输出任何内容。它唯一的用途是在文件中添加注释。这些注释不会被打印。

此语法在版本 2.4.21 及更高版本中可用。

config 元素

此命令控制解析的各个方面。有效属性为

echomsg (Apache 2.1 及更高版本)

该值是当 echo 元素尝试回显未定义的变量时发送回客户端的消息。这将覆盖任何 SSIUndefinedEcho 指令。

<!--#config echomsg="[Value Undefined]" -->

errmsg

该值是当解析文档时发生错误时发送回客户端的消息。这将覆盖任何 SSIErrorMsg 指令。

<!--#config errmsg="[Oops, something broke.]" -->

sizefmt

该值设置在显示文件大小时要使用的格式。有效值为 bytes（以字节为单位的计数）或 abbrev（以 Kb 或 Mb 为单位的计数，具体取决于情况），例如，大小为 1024 字节将被打印为“1K”。

<!--#config sizefmt="abbrev" -->

timefmt

该值是在打印日期时由 strftime(3) 库例程使用的字符串。

<!--#config timefmt=""%R, %B %d, %Y"" -->

echo 元素

此命令打印下面定义的 包含变量 之一。如果变量未设置，则结果由 SSIUndefinedEcho 指令确定。任何打印的日期都受当前配置的 timefmt 影响。

属性

var

该值是要打印的变量的名称。

decoding

指定 Apache 是否应该在进一步处理变量之前从变量中剥离编码。默认值为 none，不会进行任何解码。如果设置为 url，则将执行 URL 解码（也称为 %-编码；这适用于链接等 URL 中的使用）。如果设置为 urlencoded，则将剥离与 application/x-www-form-urlencoded 兼容的编码（在查询字符串中找到）。如果设置为 base64，则将解码 base64，如果设置为 entity，则将剥离 HTML 实体编码。解码在对变量进行任何进一步编码之前完成。可以通过指定多个以逗号分隔的编码来剥离多个编码。解码设置将一直有效，直到遇到下一个解码属性或元素结束，以先发生者为准。

decoding 属性必须在相应的 var 属性之前才能生效。

encoding

指定 Apache 应该如何在输出之前对变量中包含的特殊字符进行编码。如果设置为 none，则不会进行任何编码。如果设置为 url，则将执行 URL 编码（也称为 %-编码；这适用于链接等 URL 中的使用）。如果设置为 urlencoded，则将执行与 application/x-www-form-urlencoded 兼容的编码，应与查询字符串一起使用。如果设置为 base64，则将执行 base64 编码。在 echo 元素的开头，默认设置为 entity，导致实体编码（这在块级 HTML 元素的上下文中是合适的，例如一段文本）。这可以通过添加 encoding 属性来更改，该属性将一直有效，直到遇到下一个 encoding 属性或元素结束，以先发生者为准。

encoding 属性必须在相应的 var 属性之前才能生效。

为了避免跨站点脚本问题，您应该始终对用户提供的數據进行编码。

示例

<!--#echo encoding="entity" var="QUERY_STRING" -->

exec 元素

exec 命令执行给定的 shell 命令或 CGI 脚本。它要求服务器中存在 mod_cgi。如果设置了 Options IncludesNOEXEC，则此命令将完全禁用。有效属性为

cgi

该值指定 CGI 脚本的（%-编码）URL 路径。如果路径没有以斜杠 (/) 开头，则它被认为相对于当前文档。通过此路径引用的文档被调用为 CGI 脚本，即使服务器通常不会将其识别为 CGI 脚本。但是，包含脚本的目录必须为 CGI 脚本启用（使用 ScriptAlias 或 Options ExecCGI）。

CGI 脚本被赋予来自客户端的原始请求的 PATH_INFO 和查询字符串 (QUERY_STRING)；这些不能在 URL 路径中指定。除了标准的 CGI 环境之外，包含变量也将对脚本可用。

示例

<!--#exec cgi="/cgi-bin/example.cgi" -->

如果脚本返回 Location: 标头而不是输出，则这将被转换为 HTML 锚点。

include virtual 元素应优先于 exec cgi 使用。特别是，如果您需要将其他参数传递给 CGI 程序，使用查询字符串，这无法使用 exec cgi 完成，但可以使用 include virtual 完成，如下所示

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

服务器将使用 /bin/sh 执行给定的字符串。除了通常的 CGI 变量集之外，包含变量 也对命令可用。

使用 #include virtual 几乎总是优于使用 #exec cgi 或 #exec cmd。前者 (#include virtual) 使用标准的 Apache 子请求机制来包含文件或脚本。它经过了更好的测试和维护。

此外，在某些平台上，例如 Win32，以及在使用 suexec 的 unix 上，您不能在 exec 指令中将参数传递给命令，也不能在命令中包含空格。因此，虽然以下内容在 unix 的非 suexec 配置下有效，但在 Win32 下或运行 suexec 时不会产生预期结果

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

fsize 元素

此命令打印指定文件的大小，受 sizefmt 格式规范的影响。属性

file

该值是相对于解析当前文档的目录的路径。

此文件大小为 <!--#fsize file="mod_include.html" --> 字节。

file 的值不能以斜杠 (/) 开头，也不能包含 ../ 以引用当前目录上方的文件或文档根目录之外的文件。尝试这样做会导致错误消息：给定的路径高于根路径。

虚拟

该值是（百分号编码的）URL 路径。如果它不以斜杠 (/) 开头，则它被认为是相对于当前文档的。请注意，这不会打印任何 CGI 输出的大小，而是打印 CGI 脚本本身的大小。

请注意，在许多情况下，这两个值完全相同。但是，file 属性不尊重 URL 空间别名。

flastmod 元素

此命令根据 timefmt 格式规范打印指定文件的最后修改日期。属性与 fsize 命令相同。

include 元素

此命令将另一个文档或文件的内容插入解析的文件中。任何包含的文件都受通常的访问控制。如果包含解析文件的目录具有 Options IncludesNOEXEC 设置，则只包含具有文本 MIME 类型（text/plain、text/html 等）的文档。否则，CGI 脚本将使用命令中给出的完整 URL（包括任何查询字符串）正常调用。

属性定义文档的位置，并且可以在一个 include 元素中出现多次；对于 include 命令给出的每个属性，都会依次执行包含操作。有效的属性是

file

该值是相对于解析当前文档的目录的路径。它不能包含 ../，也不能是绝对路径。因此，您不能包含位于文档根目录之外或在目录结构中位于当前文档上方的文件。virtual 属性应始终优先于此属性使用。

虚拟

该值是（百分号编码的）URL 路径。URL 不能包含方案或主机名，只能包含路径和可选的查询字符串。如果它不以斜杠 (/) 开头，则它被认为是相对于当前文档的。

从属性构建 URL，并且如果客户端访问该 URL，服务器将返回的输出包含在解析的输出中。因此，包含的文件可以嵌套。

如果指定的 URL 是 CGI 程序，则该程序将被执行，并且其输出将插入解析文件中指令的位置。您可以在 CGI url 中包含查询字符串

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

include virtual 应优先于 exec cgi 用于将 CGI 程序的输出包含到 HTML 文档中。

如果 KeptBodySize 指令配置正确并且对包含的文件有效，则尝试将 POST 请求发送到封闭的 HTML 文档将被传递到子请求作为 POST 请求。如果没有该指令，所有子请求都将作为 GET 请求处理。

onerror

该值是（百分号编码的）URL 路径，如果先前尝试包含文件或虚拟属性失败，则会显示该路径。要有效，此属性必须在要覆盖的文件或虚拟属性之后指定。如果尝试包含 onerror 路径失败，或者没有指定 onerror，则将包含默认错误消息。

# 简单示例
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# 专用 onerror 路径
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

printenv 元素

这将打印所有现有变量及其值的纯文本列表。特殊字符在输出之前进行实体编码（有关详细信息，请参阅 echo 元素）。没有属性。

set 元素

这将设置变量的值。属性

var

要设置的变量的名称。

value

要赋予变量的值。

decoding

指定 Apache 是否应该在进一步处理变量之前从变量中剥离编码。默认值为 none，不进行解码。如果设置为 url、urlencoded、base64 或 entity，则将分别执行 URL 解码、application/x-www-form-urlencoded 解码、base64 解码或 HTML 实体解码。可以通过逗号分隔来指定多个解码。解码设置将一直有效，直到遇到下一个解码属性或元素结束。decoding 属性必须位于相应的 var 属性之前才能生效。

encoding

指定 Apache 如何在设置变量之前对变量中包含的特殊字符进行编码。默认值为 none，不进行编码。如果设置为 url、urlencoding、base64 或 entity，则将分别执行 URL 编码、application/x-www-form-urlencoded 编码、base64 编码或 HTML 实体编码。可以通过逗号分隔来指定多个编码。编码设置将一直有效，直到遇到下一个编码属性或元素结束。encoding 属性必须位于相应的 var 属性之前才能生效。编码在剥离所有解码之后应用。

包含变量

除了标准 CGI 环境中的变量之外，这些变量还可用于 echo 命令、if 和 elif，以及文档调用的任何程序。

DATE_GMT

格林威治标准时间的当前日期。

DATE_LOCAL

本地时区的当前日期。

DOCUMENT_ARGS

此变量包含活动 SSI 文档的查询字符串，如果未包含查询字符串，则包含空字符串。对于通过 include SSI 指令调用的子请求，QUERY_STRING 将表示子请求的查询字符串，DOCUMENT_ARGS 将表示 SSI 文档的查询字符串。（在 Apache HTTP Server 2.4.19 及更高版本中可用。）

DOCUMENT_NAME

用户请求的文档的文件名（不包括目录）。

DOCUMENT_PATH_INFO

尾随路径名信息。有关 PATH_INFO 的更多信息，请参阅指令 AcceptPathInfo。

DOCUMENT_URI

用户请求的文档的（百分号解码的）URL 路径。请注意，在嵌套包含文件的情况下，这不是当前文档的 URL。还要注意，如果 URL 在内部被修改（例如，通过 alias 或 directoryindex），则会显示修改后的 URL。

LAST_MODIFIED

用户请求的文档的最后修改日期。

QUERY_STRING_UNESCAPED

如果活动 SSI 文档的请求中存在查询字符串，则此变量包含（百分号解码的）查询字符串，该字符串已转义以供 shell 使用（& 等特殊字符前面有反斜杠）。如果不存在查询字符串，则不会设置它。如果不需要 shell 转义，请使用 DOCUMENT_ARGS。

USER_NAME

文件所有者的用户名。

变量替换

在大多数情况下，变量替换会在引号字符串中完成，这些字符串可能合理地作为 SSI 指令的参数出现。这包括 config、exec、flastmod、fsize、include、echo 和 set 指令。如果 SSILegacyExprParser 设置为 on，则替换也会发生在条件运算符的参数中。您可以使用反斜杠引用将文字美元符号插入字符串中

如果需要在字符序列的中间替换变量引用，而该字符序列本身可能被视为有效的标识符，则可以通过将引用括在花括号中来消除歧义，类似于 shell 替换

如果 REMOTE_HOST 为 "X" 且 REQUEST_METHOD 为 "Y"，则这将导致 Zed 变量设置为 "X_Y"。

流程控制元素

基本流程控制元素是

if 元素的工作原理类似于编程语言中的 if 语句。测试条件将被评估，如果结果为真，则直到下一个 elif、else 或 endif 元素之间的文本将包含在输出流中。

elif 或 else 语句用于在原始 test_condition 为假时将文本放入输出流中。这些元素是可选的。

endif 元素结束 if 元素，并且是必需的。

test_condition 是一个布尔表达式，它遵循 ap_expr 语法。可以使用 SSILegacyExprParser 将语法更改为与 Apache HTTPD 2.2.x 兼容。

使用 var 元素设置的 SSI 变量将导出到请求环境中，并且可以使用 reqenv 函数访问。作为快捷方式，函数名 v 也可在 mod_include 内部使用。

以下示例将打印 "from local net"，如果客户端 IP 地址属于 10.0.0.0/8 子网。

以下示例将打印 "foo is bar"，如果变量 foo 设置为值 "bar"。

传统表达式语法

本节描述了如果 SSILegacyExprParser 设置为 on，则 #if expr 元素的语法。

string

如果 string 不为空，则为真

-A string

如果字符串表示的 URL 可通过配置访问，则为真，否则为假。这在页面上的内容需要对未经授权查看 URL 的用户隐藏时很有用，例如指向该 URL 的链接。请注意，URL 仅测试是否会授予访问权限，而不是测试 URL 是否存在。

示例

<!--#if expr="-A /private" -->
点击 <a href="/private">这里</a> 访问私有信息。
<!--#endif -->

string1 = string2
string1 == string2
string1 != string2

将 string1 与 string2 进行比较。如果 string2 的形式为 /string2/，则将其视为正则表达式。正则表达式由 PCRE 引擎实现，其语法与 perl 5 中的语法相同。请注意，== 只是 = 的别名，其行为完全相同。

如果匹配正值（= 或 ==），则可以捕获正则表达式的分组部分。捕获的部分存储在特殊变量 $1 .. $9 中。正则表达式匹配的整个字符串存储在特殊变量 $0 中

示例

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
<!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2

将 string1 与 string2 进行比较。请注意，字符串是逐字比较的（使用 strcmp(3)）。因此，字符串 "100" 小于 "20"。

( test_condition )

如果 test_condition 为真，则为真

! test_condition

如果 test_condition 为假，则为真

test_condition1 && test_condition2

如果 test_condition1 和 test_condition2 都为真，则为真

test_condition1 || test_condition2

如果 test_condition1 或 test_condition2 为真，则为真

"=" 和 "!=" 的绑定优先级高于 "&&" 和 "||"。"!" 的绑定优先级最高。因此，以下等效

布尔运算符 && 和 || 具有相同的优先级。因此，如果要将此类运算符绑定得更紧密，则应使用括号。

任何无法识别为变量或运算符的内容都将被视为字符串。字符串也可以用引号括起来：'string'。未加引号的字符串不能包含空格（空格和制表符），因为空格用于分隔变量等标记。如果在一行中找到多个字符串，则使用空格将它们连接起来。所以，

SSIEndTag "%>"

SSIErrorMsg "<!-- Error -->"

SSIStartTag "<%"
SSIEndTag   "%>"

SSITimeFormat "%R, %B %d, %Y"

SSIUndefinedEcho "<!-- undef -->"