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;

启用在响应中处理SSI命令的指定MIME类型，除了“text/html”之外。特殊值“*”匹配任何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处理期间发生错误，则输出的字符串。默认情况下，输出以下字符串：

[处理指令时发生错误]

timefmt

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

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

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

echo

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

var

变量名称。

encoding

编码方法。可能的值包括none、url和entity。默认情况下，使用entity。

default

一个非标准参数，如果变量未定义，则设置要输出的字符串。默认情况下，输出“(none)”。该命令

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

替换以下一系列命令：

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

if

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

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

目前仅支持一级嵌套。该命令具有以下参数：

expr

表达式。表达式可以是：

• 变量存在检查：

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

• 将变量与文本进行比较：

  <!--# if expr="$name = 文本" -->
  <!--# if expr="$name != 文本" -->
  

• 将变量与正则表达式进行比较：

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

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

<!--# 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

变量值。如果分配的值包含变量，则会替换它们的值。

nginx的ngx_http_ssi_module模块支持两个内嵌变量：

$date_local

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

$date_gmt

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