SSI#

该模块是一个过滤器,用于处理通过它传递的响应中的 SSI(服务器端包含)命令。

配置示例#

location / {
    ssi on;
#    ...
}

指令#

ssi#

语法

ssi on | off;

默认值

ssi off;

上下文

http, server, location, if in location

启用或禁用响应中 SSI 命令的处理。

ssi_last_modified#

语法

ssi_last_modified on | off;

默认值

ssi_last_modified off;

上下文

http, server, location

允许在 SSI 处理过程中保留原始响应中的 "Last-Modified" 头字段,以便于响应缓存。

默认情况下,头字段会被移除,因为响应的内容在处理过程中被修改,可能包含动态生成的元素或与原始响应独立更改的部分。

ssi_min_file_chunk#

语法

ssi_min_file_chunk size;

默认值

ssi_min_file_chunk 1k;

上下文

http, server, location

设置存储在磁盘上的响应部分的最小大小,从该大小开始,使用 sendfile 发送它们是有意义的。

ssi_silent_errors#

语法

ssi_silent_errors on | off;

默认值

ssi_silent_errors off;

上下文

http, server, location

如果启用,在 SSI 处理期间发生错误时,将抑制输出 "[an error occurred while processing the directive]" 字符串。

ssi_types#

语法

ssi_types mime-type ...;

默认值

ssi_types text/html;

上下文

http, server, location

启用对具有指定 MIME 类型的响应中 SSI 命令的处理,除了 "text/html"。特殊值 "*" 匹配任何 MIME 类型。

ssi_value_length#

语法

ssi_value_length length;

默认值

ssi_value_length 256;

上下文

http, server, location

设置 SSI 命令中参数值的最大长度。

SSI 命令#

SSI 命令具有以下通用格式:

<!--# command parameter1=value1 parameter2=value2 ... -->

支持以下命令:

block#

定义一个可以作为 include 命令中的存根使用的块。块可以包含其他 SSI 命令。该命令具有以下参数:

name#

块名称。

示例:

<!--# block name="one" -->
stub
<!--# endblock -->

config#

设置在 SSI 处理期间使用的一些参数,即:

errmsg#

在 SSI 处理期间发生错误时输出的字符串。默认情况下,输出以下字符串:

[an error occurred while processing the directive]

timefmt#

传递给 strftime() 函数的格式字符串,用于输出日期和时间。默认情况下,使用以下格式:

"%A, %d-%b-%Y %H:%M:%S %Z"

"%s" 格式适合以秒为单位输出时间。

echo#

输出变量的值。该命令具有以下参数:

var#

变量名称。

encoding#

编码方法。可能的值包括 noneurlentity

默认使用 entity

default#

一个非标准参数,设置在变量未定义时输出的字符串。
默认输出 "(none)"。该命令

<!--# echo var="name" default="no" -->

替换以下命令序列:

<!--# if expr="$name" --><!--# echo var="name" --><!--#
     else -->no<!--# endif -->

if#

执行条件包含。支持以下命令:

<!--# if expr="..." -->
...
<!--# elif expr="..." -->
...
<!--# else -->
...
<!--# endif -->

当前仅支持一层嵌套。该命令具有以下参数:

expr#

表达式。表达式可以是:

  • 变量存在性检查:

<!--# if expr="$name" -->
  • 变量与文本的比较:

<!--# if expr="$name = text" -->
<!--# if expr="$name != text" -->
  • 变量与正则表达式的比较:

<!--# if expr="$name = /text/" -->
<!--# if expr="$name != /text/" -->

如果 text 包含变量,则会替换它们的值。正则表达式可以包含位置捕获和命名捕获,稍后可以通过变量使用,例如:

<!--# if expr="$name = /(.+)@(?P<domain>.+)/" -->
  <!--# echo var="1" -->
  <!--# echo var="domain" -->
<!--# endif -->

include#

将另一个请求的结果包含到响应中。该命令具有以下参数:

file#

指定包含的文件,例如:

<!--# include file="footer.html" -->

virtual#

指定包含的请求,例如:

<!--# include virtual="/remote/body.php?argument=value" -->

在一页上指定的多个请求,由代理或 FastCGI/uwsgi/SCGI/gRPC 服务器并行处理。如果需要顺序处理,则应使用 wait 参数。

stub#

一个非标准参数,命名包含请求结果为空主体或请求处理期间发生错误时输出的块,例如:

<!--# block name="one" -->&nbsp;<!--# endblock -->
<!--# include virtual="/remote/body.php?argument=value" stub="one" -->

替换块内容在包含请求上下文中处理。

wait#

一个非标准参数,指示在继续 SSI 处理之前等待请求完全完成,例如:

<!--# include virtual="/remote/body.php?argument=value" wait="yes" -->

set#

一个非标准参数,指示将请求处理的成功结果写入指定变量,例如:

<!--# include virtual="/remote/body.php?argument=value" set="one" -->

响应的最大大小由 subrequest_output_buffer_size 指令设置:

location /remote/ {
    subrequest_output_buffer_size 64k;
#    ...
}

set#

设置变量的值。该命令具有以下参数:

var#

变量名称。

value#

变量值。如果赋值中包含变量,则会替换它们的值。

内置变量#

$date_local#

当前时间(本地时区)。格式由 config 命令中的 timefmt 参数设置。

$date_gmt#

当前时间(GMT)。格式由 config 命令中的 timefmt 参数设置。