模块 ngx_http_xslt_module

提示

来自deepseek解释

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

该模块是一个过滤器（0.7.8+），能够使用一个或多个 XSLT 样式表对 XML 响应进行转换。此模块默认不构建，需要通过 --with-http_xslt_module 配置参数启用。该模块依赖 libxml2 和 libxslt 库。

---

介绍

ngx_http_xslt_module 模块（0.7.8+）是一个过滤器，它使用一个或多个 XSLT 样式表对 XML 响应进行转换。此模块默认不构建，必须通过 --with-http_xslt_module 配置参数启用。该模块需要 libxml2 和 libxslt 库。

示例配置

location / {
    xml_entities /site/dtd/entities.dtd;
    xslt_stylesheet /site/xslt/one.xslt param=value;
    xslt_stylesheet /site/xslt/two.xslt;
}

指令

xml_entities

属性	说明
语法	xml_entities path;
默认值	—
上下文	http, server, location

指定用于声明字符实体的 DTD 文件。该文件在配置阶段进行编译。由于技术原因，该模块无法使用被处理 XML 中声明的外部子集，因此该外部子集会被忽略，转而使用专门定义的文件。此文件不应描述 XML 结构，只需声明所需的字符实体即可。

例如：

xml_entities /site/dtd/entities.dtd;

---

xslt_last_modified

属性	说明
语法	xslt_last_modified on | off;
默认值	xslt_last_modified off;
上下文	http, server, location
版本	自 1.5.1 版本起

允许在 XSLT 转换过程中保留原始响应的“Last-Modified”头字段，以便进行响应缓存。默认情况下，该头字段会被移除，因为响应内容在转换过程中被修改，可能包含动态生成的元素或与原始响应无关的变更部分。

---

xslt_param

属性	说明
语法	xslt_param parameter value;
默认值	—
上下文	http, server, location
版本	自 1.1.18 版本起

定义 XSLT 样式表的参数。value 被视为 XPath 表达式。value 可以包含变量。若要向样式表传递字符串值，可使用 xslt_string_param 指令。可以有多个 xslt_param 指令。这些指令仅在当前级别未定义任何 xslt_param 和 xslt_string_param 指令时，才会从上一配置级别继承。

---

xslt_string_param

属性	说明
语法	xslt_string_param parameter value;
默认值	—
上下文	http, server, location
版本	自 1.1.18 版本起

定义 XSLT 样式表的字符串参数。value 中的 XPath 表达式不会被解析。value 可以包含变量。可以有多个 xslt_string_param 指令。这些指令仅在当前级别未定义任何 xslt_param 和 xslt_string_param 指令时，才会从上一配置级别继承。

---

xslt_stylesheet

属性	说明
语法	xslt_stylesheet stylesheet [parameter=value ...];
默认值	—
上下文	location

定义 XSLT 样式表及其可选参数。样式表在配置阶段编译。参数可以单独指定，也可以使用“:”分隔符合并在同一行。如果参数包含“:”字符，则需要转义为“%3A”。此外，libxslt 要求包含非字母数字字符的参数必须用单引号或双引号括起来。

例如：

param1='http%3A//www.example.com':param2=value2

参数描述可以包含变量，例如，整行参数可以取自单个变量：

location / {
    xslt_stylesheet /site/xslt/one.xslt
        $arg_xslt_params
        param1='$value1':param2=value2
        param3=value3;
}

可以指定多个样式表。它们将按照指定的顺序依次应用。

---

xslt_types

属性	说明
语法	xslt_types mime-type ...;
默认值	xslt_types text/xml;
上下文	http, server, location

除了“text/xml”之外，还允许对指定的 MIME 类型响应进行转换。特殊值“*”匹配任何 MIME 类型（0.8.29）。如果转换结果为 HTML 响应，其 MIME 类型将更改为“text/html”。