模块 ngx_http_ssi_module

ngx_http_ssi_module 模块是一个过滤器，它处理通过它的响应中的 SSI（服务器端包含）命令。目前，支持的 SSI 命令列表不完整。

location / {
    ssi on;
    ...
}

ssi off;

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

ssi_last_modified off;

允许在 SSI 处理期间保留原始响应中的“Last-Modified”报头字段，以方便响应缓存。

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

ssi_min_file_chunk 1k;

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

ssi_silent_errors off;

如果启用，则如果在 SSI 处理期间发生错误，则抑制输出“[an error occurred while processing the directive]”字符串。

ssi_types text/html;

除了“text/html”之外，还启用对具有指定 MIME 类型的响应中 SSI 命令的处理。特殊值“*”匹配任何 MIME 类型（0.8.29）。

ssi_value_length 256;

设置 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

编码方法。可能的值包括none、url和entity。默认情况下，使用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指令（1.13.10）设置

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

在 1.13.10 版本之前，只能将使用ngx_http_proxy_module、ngx_http_memcached_module、ngx_http_fastcgi_module（1.5.6）、ngx_http_uwsgi_module（1.5.6）和ngx_http_scgi_module（1.5.6）模块获得的响应的结果写入变量。响应的最大大小由proxy_buffer_size、memcached_buffer_size、fastcgi_buffer_size、uwsgi_buffer_size和scgi_buffer_size指令设置。

set

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

var

变量名称。

value

变量值。如果赋值包含变量，则替换其值。

ngx_http_ssi_module 模块支持两个嵌入变量

$date_local

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

$date_gmt

GMT 的当前时间。格式由config命令使用timefmt参数设置。