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

一、模块简介

• 模块名称：ngx_http_xslt_module

• 首次引入版本：0.7.8

• 功能：在回传给客户端之前，用指定的 XSLT 样式表对 XML 响应进行转换。

• 依赖：

  • libxml2
  • libxslt

• 编译选项：需在 NGINX 编译时添加 --with-http_xslt_module。

二、使用场景

1. 静态站点：将后端生成的 XML 直接转换成 HTML，减少后端压力。
2. API 网关：API 返回 XML，可根据客户端类型动态指定不同 XSLT。
3. 多视图支持：同一份 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 或以单/双引号包裹。

五、注意事项 & 性能调优

1. 样式表预编译

   • NGINX 在启动时编译 .xsl，运行时无需再次编译，性能开销主要在第一次加载。

2. 响应缓存

   • 配合 xslt_last_modified on 与 proxy_cache，可大幅提升重复请求性能。

3. 错误处理

   • 若待转换内容非有效 XML，模块会返回 500 错误，建议在上游加 add_header X-Debug ... 便于排查。

4. 内存占用

   • 较大的 XML 或 XSLT 会消耗更多内存，可通过 worker_processes 与 worker_rlimit_core 等指令调优。

5. DTD 文件

   • 仅声明必要的字符实体，避免过大或复杂的 DTD 导致编译缓慢。

六、总结

通过 ngx_http_xslt_module，我们可以让 NGINX 在代理层直接完成 XML → HTML（或其他 XML）转换，最大化利用 NGINX 的高性能、高并发优势，简化后端应用的逻辑复杂度。

• 简化架构：删除后端转换逻辑，统一由 NGINX 处理。
• 动态化：支持根据 URI、参数、Cookie 等动态传参。
• 高性能：样式表预编译 + 缓存策略，让转换成本可控。

欢迎将此模块纳入你的生产环境试点，并在评论区分享你的最佳实践与优化经验！