当前位置：首页 > article >正文

利用 `ngx_http_xslt_module` 实现 NGINX 的 XML → HTML 转换

article 2025/8/18 15:35:04

一、模块简介

模块名称：ngx_http_xslt_module
首次引入版本：0.7.8
功能：在回传给客户端之前，用指定的 XSLT 样式表对 XML 响应进行转换。
依赖：
- libxml2
- libxslt
编译选项：需在 NGINX 编译时添加 --with-http_xslt_module。

二、使用场景

静态站点：将后端生成的 XML 直接转换成 HTML，减少后端压力。
API 网关：API 返回 XML，可根据客户端类型动态指定不同 XSLT。
多视图支持：同一份 XML，基于请求参数套用不同样式，实现多种展现。

三、核心指令

指令	作用	示例
`xml_entities path`	指定字符实体声明 DTD，用于支持自定义实体（如 ` `）	`xml_entities /etc/nginx/dtd/entities.dtd;`
`xslt_stylesheet file [param=value …]`	声明要应用的 XSLT 样式表及可选参数，支持多次调用，按顺序生效	`ngx\nxslt_stylesheet /site/xslt/one.xslt lang=zh_CN;\nxslt_stylesheet /site/xslt/two.xslt;\n`
`xslt_param name expr`	以 XPath 表达式方式传参给 XSLT	`xslt_param user_id $arg_uid;`
`xslt_string_param name value`	以字符串方式传参给 XSLT，防止 XPath 解析	`xslt_string_param theme '$cookie_theme';`
`xslt_last_modified on	off`	是否保留原响应的 `Last-Modified`，便于下游缓存	`xslt_last_modified on;`
`xslt_types mime…`	对哪些 MIME 类型的响应进行 XSLT 转换，默认仅 `text/xml`	`xslt_types text/xml application/xml;`

四、示例配置

http {# 声明全局 DTD（可选），支持自定义字符实体xml_entities /etc/nginx/dtd/entities.dtd;server {listen 80;server_name example.com;location /xml/ {# 只对 text/xml 和 application/xml 响应进行转换xslt_types text/xml application/xml;# 如果上游返回 Last-Modified，则保留xslt_last_modified on;# 应用两套样式表，先 one.xslt 再 two.xsltxslt_stylesheet /var/www/xslt/one.xslt version=1.0;xslt_stylesheet /var/www/xslt/two.xslt;}}
}

DTD 文件内容示例（entities.dtd）：

<!ENTITY nbsp "&#xa0;">
<!ENTITY copy "&#xA9;">

动态传参：
```
location /xml/ {xslt_stylesheet /xsl/apply.xsltlang=$arg_languser=$cookie_usertheme='$cookie_theme';
}
```
对于含有非字母数字的参数，使用 xslt_string_param 或以单/双引号包裹。

五、注意事项 & 性能调优

样式表预编译
- NGINX 在启动时编译 .xsl，运行时无需再次编译，性能开销主要在第一次加载。
响应缓存
- 配合 xslt_last_modified on 与 proxy_cache，可大幅提升重复请求性能。
错误处理
- 若待转换内容非有效 XML，模块会返回 500 错误，建议在上游加 add_header X-Debug ... 便于排查。
内存占用
- 较大的 XML 或 XSLT 会消耗更多内存，可通过 worker_processes 与 worker_rlimit_core 等指令调优。
DTD 文件
- 仅声明必要的字符实体，避免过大或复杂的 DTD 导致编译缓慢。