模块 ngx_http_ssi_module

提示

来自deepseek解释

这是 ngx_http_ssi_module 模块的官方文档中文翻译。

该模块是一个过滤器，能够在响应中处理 SSI（服务器端包含）命令。SSI 是一种在服务器端解析 HTML 文件，并动态包含其他文件内容的技术，常用于在静态页面中插入动态内容。

---

介绍

ngx_http_ssi_module 模块是一个过滤器，用于处理通过它的响应中的 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
版本	自 1.5.1 版本起

允许在 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

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

---

ssi_value_length

属性	说明
语法	ssi_value_length length;
默认值	ssi_value_length 256;
上下文	http, server, location

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

---

SSI 命令

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

<!--# 命令 参数1=值1 参数2=值2 ... -->

目前支持以下命令：

block

定义一个块，可以作为 include 命令的替代内容（stub）使用。该块可以包含其他 SSI 命令。

参数：

• name - 块的名称。

---

config

设置 SSI 处理期间使用的参数。

参数：

• errmsg - SSI 处理过程中发生错误时输出的字符串。默认情况下，输出以下字符串：“[an error occurred while processing the directive]”。
• timefmt - 传递给 strftime() 函数的格式字符串，用于输出日期和时间。默认情况下，使用以下格式："%A, %d-%b-%Y %H:%M:%S %Z"。

---

echo

输出一个变量的值。

参数：

• var - 变量名称。
• encoding - 编码方法。可能的值包括：none、url 和 entity。默认情况下，使用 entity。
• default - 一个非标准参数，用于设置如果变量未定义时输出的字符串。默认情况下，输出“(none)”。

---

if

执行条件包含。

注意： 目前只支持一层嵌套。

参数：

• expr - 表达式。表达式可以是：
  • 变量存在性检查：
  • 变量与文本的比较：
  • 变量与正则表达式的比较：

---

include

将另一个请求的结果包含到响应中。

参数：

• file - 指定要包含的文件，例如：<!--# include file="footer.html" -->。
• virtual - 指定要包含的请求，例如：<!--# include virtual="/remote/body.php" -->。
• stub - 一个非标准参数，用于指定块的名称。如果所包含的请求结果为空体或处理过程中发生错误，将输出该块的内容。
• wait - 一个非标准参数，指示在继续 SSI 处理之前等待请求完全完成，例如：<!--# include virtual="/remote/body.php" wait="yes" -->。
• set - 一个非标准参数，指示将请求处理成功的结果写入指定的变量，例如：<!--# include virtual="/remote/body.php" set="var" -->。

---

set

设置一个变量的值。

参数：

• var - 变量名称。
• value - 变量值。如果赋值中包含变量，它们的值将被替换。

---

嵌入变量

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

• $date_local - 当前本地时区的时间。格式由 config 命令的 timefmt 参数设置。
• $date_gmt - 当前的 GMT 时间。格式由 config 命令的 timefmt 参数设置。