模块 ngx_http_ssi_module

ngx_http_ssi_module 模块是一个过滤器，用于处理通过它的响应中的 SSI (Server Side Includes) 命令。目前，支持的 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 处理过程中发生错误时，将抑制输出字符串“[处理指令时发生错误]”。

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

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

$date_gmt

当前格林威治标准时间（GMT）。格式由带 timefmt 参数的 config 命令设置。