模块 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 ... -->

支持以下命令

块

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

名称

块名称。

示例

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

配置

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

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

等待

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

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

设置

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

<!--# 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 指令设置。

设置

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

var

变量名称。

值

变量值。如果分配的值包含变量，则替换其值。

ngx_http_ssi_module 模块支持两个嵌入式变量

$date_local

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

$date_gmt

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