nginxngx_http_module(10)指令详解

nginx ngx_http_module(10) 指令详解

nginx 模块目录

nginx 全指令目录

一、目录 1.1 模块简介

ngx_http_v2_module：HTTP/2支持模块，允许Nginx通过HTTP/2协议与客户端进行通信。HTTP/2带来了许多性能优化，如多路复用、头部压缩和服务器推送等功能，可以显著提高网页加载速度和用户体验。启用此模块通常需要在配置中使用 http2 参数，例如在 listen 指令中指定 ssl http2。

ngx_http_v3_module：HTTP/3支持模块，允许Nginx通过HTTP/3协议（基于QUIC传输协议）与客户端进行通信。HTTP/3旨在解决HTTP/2的一些局限性，特别是在高延迟或不稳定的网络环境下提供更好的性能和可靠性。由于HTTP/3依赖于QUIC协议，因此需要相应的QUIC实现（如Google’s QUIC library）。请注意，该模块可能不是所有Nginx版本的标准部分，且需要特定的编译选项。

ngx_http_xslt_module：XSLT转换模块，允许Nginx在返回XML内容之前对其进行XSLT（可扩展样式语言转换）处理。这对于动态生成HTML页面或以其他格式呈现XML数据非常有用。通过这个模块，你可以定义如何将XML文档转换为其他格式（如HTML），并在响应中返回转换后的内容。常用的指令包括 xslt_stylesheet 用于指定XSLT样式表的位置，以及 xslt_types 用于定义哪些MIME类型应被转换。

1.2 指令目录 1.2.1 ngx_http_v2_module http2http2_body_preread_sizehttp2_chunk_sizehttp2_idle_timeouthttp2_max_concurrent_pusheshttp2_max_concurrent_streamshttp2_max_field_sizehttp2_max_header_sizehttp2_max_requestshttp2_pushhttp2_push_preloadhttp2_recv_buffer_sizehttp2_recv_timeout 1.2.2 ngx_http_v3_module http3http3_hqhttp3_max_concurrent_streamshttp3_stream_buffer_sizequic_active_connection_id_limitquic_bpfquic_gsoquic_host_keyquic_retry 1.2.3 ngx_http_xslt_module xml_entitiesxslt_last_modifiedxslt_paramxslt_string_paramxslt_stylesheetxslt_types 二、解释 2.1 ngx_http_v2_module

ngx_http_v2_module 是 Nginx 的一个模块，用于支持 HTTP/2 协议。HTTP/2 旨在解决 HTTP/1.1 中的一些性能瓶颈，并提供更高效的网络通信。通过 ngx_http_v2_module，Nginx 可以利用 HTTP/2 的特性，如多路复用、头部压缩和服务器推送等，从而提升网页加载速度和用户体验。

主要功能

多路复用：允许在同一个 TCP 连接上同时处理多个请求和响应，减少连接建立的开销。头部压缩：使用 HPACK 算法对 HTTP 头部进行压缩，减少传输数据量。服务器推送：允许服务器主动推送资源到客户端，减少额外的请求往返时间。流优先级：允许客户端为不同的请求设置优先级，优化资源加载顺序。

常用指令

以下是与 ngx_http_v2_module 模块相关的常用配置指令及其简要说明：

http2：在 listen 指令中启用 HTTP/2 支持。

ssl_protocols：指定支持的 SSL/TLS 协议版本，确保兼容性和安全性。

ssl_prefer_server_ciphers：优先使用服务器端的加密套件，增强安全性。

http2_push：用于服务器推送资源。

http2_max_concurrent_streams：设置每个连接的最大并发流数，默认是无限制。

使用示例

以下是一些具体的配置示例，展示如何利用 ngx_http_v2_module 来实现 HTTP/2 支持。

基本配置

假设你想在你的网站上启用 HTTP/2 支持：

server { listen 443 ssl http2; # 启用 HTTP/2 和 SSL server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; ssl_protocols TLSv1.2 TLSv1.3; # 仅启用安全的 TLS 版本 ssl_prefer_server_ciphers on; location / { root /var/ /html; index index.html; } }

在这个例子中：

listen 443 ssl http2; 启用了 HTTPS 和 HTTP/2 支持。ssl_certificate 和 ssl_certificate_key 指定了 SSL 证书和私钥文件的路径。ssl_protocols 设置了支持的 TLS 协议版本，推荐仅启用较新的、更安全的版本。ssl_prefer_server_ciphers on; 优先使用服务器端的加密套件，提高安全性。

服务器推送

你可以使用 http2_push 指令来推送资源到客户端，减少额外的请求往返时间：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; location / { root /var/ /html; index index.html; # 推送 CSS 文件 http2_push /styles.css; # 推送 JavaScript 文件 http2_push /script.js; } }

在这个例子中：

http2_push /styles.css; 和 http2_push /script.js; 指令会在客户端请求根路径 / 时，自动推送这些资源到客户端，减少额外的请求。

流优先级

虽然 ngx_http_v2_module 不直接提供流优先级的配置选项，但你可以在前端代码中通过 HTTP/2 的 Priority 头部来设置优先级。例如，在 HTML 中可以这样指定：

<link rel="stylesheet" href="/styles.css" importance="high"> <script src="/script.js" importance="low"></script>

浏览器会根据这些提示调整资源加载的优先级。

调整并发流数

你可以通过设置 http2_max_concurrent_streams 来控制每个连接的最大并发流数：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; http2_max_concurrent_streams 100; # 设置最大并发流数为 100 location / { root /var/ /html; index index.html; } }

在这个例子中：

http2_max_concurrent_streams 100; 设置了每个连接的最大并发流数为 100。默认情况下，这个值是无限制的。

注意事项

性能考虑：

HTTP/2 提供了许多性能改进，但在某些场景下可能会引入额外的复杂性。确保合理配置超时时间和重试机制，避免不必要的延迟和资源浪费。

安全性：

确保 SSL 证书的有效性和安全性，定期更新证书。对敏感数据进行加密传输，防止中间人攻击。

日志记录：

合理配置日志级别和格式，便于监控和故障排查。特别是注意记录 HTTP/2 相关的错误信息和性能指标。

兼容性：

确保客户端浏览器支持 HTTP/2。大多数现代浏览器都支持 HTTP/2，但旧版本可能不支持。如果需要支持 HTTP/1.1 客户端，确保 Nginx 配置能够同时处理 HTTP/1.1 和 HTTP/2 请求。

通过合理配置 ngx_http_v2_module，你可以充分利用 HTTP/2 的优势，显著提升网页加载速度和用户体验。这对于构建高可用性和高性能的应用系统非常有用。

2.1.1 指令列表 http2

http2 指令用于控制是否启用 HTTP/2 协议。HTTP/2 提供了多项性能优化，如多路复用、头部压缩和服务器推送等。

Syntax: http2 on | off; Default: http2 off; Context: http, server This directive appeared in version 1.25.1. on：启用 HTTP/2 协议。off：禁用 HTTP/2 协议，默认行为。

案例

基本用法

最简单的 http2 用法是启用或禁用 HTTP/2 协议：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { # 启用 HTTP/2 协议 http2 on; proxy_pass http://backend; } }

在这个例子中：

当用户访问 example 时，Nginx 将通过 HTTPS 使用 HTTP/2 协议与客户端通信。

注意事项

SSL/TLS 要求：HTTP/2 需要在 SSL/TLS 上运行，因此必须同时配置 listen 443 ssl http2。浏览器支持：确保目标用户的浏览器支持 HTTP/2，以充分利用其性能优势。 http2_body_preread_size

http2_body_preread_size 指令用于设置在处理请求体之前预先读取的数据量。这有助于优化大请求体的处理。

Syntax: http2_body_preread_size size; Default: http2_body_preread_size 64k; Context: http, server This directive appeared in version 1.11.0. size：在处理请求体之前预先读取的数据量，默认为 64 KB。

案例

基本用法

最简单的 http2_body_preread_size 用法是指定预读取数据量：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location /upload { # 设置预读取数据量为 128 KB http2_body_preread_size 128k; proxy_pass http://backend; } }

在这个例子中：

当用户上传文件到 /upload 路径时，Nginx 将预先读取 128 KB 的请求体数据。

注意事项

性能优化：合理设置预读取数据量可以减少 I/O 操作次数，提高处理效率，特别是在处理大数据量请求时。内存使用：注意不要设置过大的预读取数据量，以免占用过多内存。 http2_chunk_size

http2_chunk_size 指令用于设置 HTTP/2 响应分块的大小。这有助于优化响应传输的效率。

Syntax: http2_chunk_size size; Default: http2_chunk_size 8k; Context: http, server, location size：HTTP/2 响应分块的大小，默认为 8 KB。

案例

基本用法

最简单的 http2_chunk_size 用法是指定响应分块大小：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location /stream { # 设置响应分块大小为 16 KB http2_chunk_size 16k; proxy_pass http://backend; } }

在这个例子中：

当 Nginx 从后端服务器获取响应并传输给客户端时，将使用 16 KB 的分块大小进行传输。

注意事项

传输效率：合理的分块大小可以提高传输效率，特别是在高带宽环境下。延迟问题：较小的分块大小可能会增加传输延迟，尤其是在低带宽环境下。 http2_idle_timeout

http2_idle_timeout 指令用于设置 HTTP/2 连接在空闲状态下的超时时间。这有助于管理连接资源，避免长时间占用连接。

Syntax: http2_idle_timeout time; Default: http2_idle_timeout 3m; Context: http, server time：HTTP/2 连接在空闲状态下的超时时间，默认为 3 分钟。

案例

基本用法

最简单的 http2_idle_timeout 用法是指定空闲超时时间：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { # 设置空闲超时时间为 5 分钟 http2_idle_timeout 5m; proxy_pass http://backend; } }

在这个例子中：

当 HTTP/2 连接处于空闲状态超过 5 分钟时，Nginx 将关闭该连接。

注意事项

资源管理：合理设置空闲超时时间可以有效管理连接资源，避免长时间占用连接。用户体验：过短的超时时间可能导致频繁断开连接，影响用户体验，特别是在长轮询或 WebSocket 应用中。 http2_max_concurrent_pushes

http2_max_concurrent_pushes 用于设置 HTTP/2 连接中允许的最大并发推送请求数。这有助于控制服务器在单个连接上可以主动推送的资源数量，避免过多的推送请求影响性能。

Syntax: http2_max_concurrent_pushes number; Default: http2_max_concurrent_pushes 10; Context: http, server This directive appeared in version 1.13.9. number：指定最大并发推送请求数，默认值为 10。

案例

基本用法

最简单的 http2_max_concurrent_pushes 用法是指定最大并发推送请求数：

http { http2_max_concurrent_pushes 5; # 设置最大并发推送请求数为 5 server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { root /var/ /html; } } }

在这个例子中，设置了 http2_max_concurrent_pushes 5，这意味着每个 HTTP/2 连接最多允许 5 个并发推送请求。

调整并发推送请求数

根据实际需求调整并发推送请求数：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location /low_push/ { root /var/ /html; http2_max_concurrent_pushes 3; # 较少的并发推送请求数 } location /high_push/ { root /var/ /html; http2_max_concurrent_pushes 20; # 较多的并发推送请求数 } }

在这个例子中：

对于 /low_push/ 路径下的请求，设置了较少的并发推送请求数（3）。对于 /high_push/ 路径下的请求，设置了较多的并发推送请求数（20）。

注意事项

性能优化：合理设置并发推送请求数，确保既能提高页面加载速度，又不会对服务器造成过大压力。用户体验：根据页面的实际资源需求和用户的网络状况，调整合适的并发推送请求数。 http2_max_concurrent_streams

http2_max_concurrent_streams 用于设置 HTTP/2 连接中允许的最大并发流数。这有助于控制单个连接上的并发请求数量，提升性能并避免资源争用。

Syntax: http2_max_concurrent_streams number; Default: http2_max_concurrent_streams 128; Context: http, server number：指定最大并发流数，默认值为 128。

案例

基本用法

最简单的 http2_max_concurrent_streams 用法是指定最大并发流数：

http { http2_max_concurrent_streams 64; # 设置最大并发流数为 64 server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { root /var/ /html; } } }

在这个例子中，设置了 http2_max_concurrent_streams 64，这意味着每个 HTTP/2 连接最多允许 64 个并发流。

调整并发流数

根据实际需求调整并发流数：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location /low_streams/ { root /var/ /html; http2_max_concurrent_streams 32; # 较少的并发流数 } location /high_streams/ { root /var/ /html; http2_max_concurrent_streams 256; # 较多的并发流数 } }

在这个例子中：

对于 /low_streams/ 路径下的请求，设置了较少的并发流数（32）。对于 /high_streams/ 路径下的请求，设置了较多的并发流数（256）。

注意事项

性能优化：合理设置并发流数，确保既能满足应用需求，又不会对服务器造成过大压力。负载均衡：根据服务器的实际负载情况，调整合适的并发流数以优化性能。 http2_max_field_size

http2_max_field_size 用于设置 HTTP/2 请求或响应头字段的最大大小。这有助于防止过大的头字段导致内存溢出或其他问题。

Syntax: http2_max_field_size size; Default: http2_max_field_size 4k; Context: http, server size：指定头字段的最大大小，默认值为 4KB。

案例

基本用法

最简单的 http2_max_field_size 用法是指定头字段的最大大小：

http { http2_max_field_size 8k; # 设置头字段的最大大小为 8KB server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { root /var/ /html; } } }

在这个例子中，设置了 http2_max_field_size 8k，这意味着每个头字段的最大大小为 8KB。

调整头字段大小

根据实际需求调整头字段大小：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location /small_fields/ { root /var/ /html; http2_max_field_size 2k; # 较小的头字段大小 } location /large_fields/ { root /var/ /html; http2_max_field_size 16k; # 较大的头字段大小 } }

在这个例子中：

对于 /small_fields/ 路径下的请求，设置了较小的头字段大小（2KB）。对于 /large_fields/ 路径下的请求，设置了较大的头字段大小（16KB）。

注意事项

安全性：合理设置头字段大小，防止恶意客户端发送过大的头字段，导致服务器资源耗尽。功能完整性：确保头字段大小限制不影响正常的功能和业务逻辑。 http2_max_header_size

http2_max_header_size 用于设置 HTTP/2 请求或响应头部的总大小。这有助于防止过大的头部数据导致内存溢出或其他问题。

Syntax: http2_max_header_size size; Default: http2_max_header_size 16k; Context: http, server size：指定头部的总大小，默认值为 16KB。

案例

基本用法

最简单的 http2_max_header_size 用法是指定头部的总大小：

http { http2_max_header_size 32k; # 设置头部的总大小为 32KB server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { root /var/ /html; } } }

在这个例子中，设置了 http2_max_header_size 32k，这意味着每个请求或响应头部的总大小为 32KB。

调整头部大小

根据实际需求调整头部大小：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location /small_headers/ { root /var/ /html; http2_max_header_size 8k; # 较小的头部大小 } location /large_headers/ { root /var/ /html; http2_max_header_size 64k; # 较大的头部大小 } }

在这个例子中：

对于 /small_headers/ 路径下的请求，设置了较小的头部大小（8KB）。对于 /large_headers/ 路径下的请求，设置了较大的头部大小（64KB）。

注意事项

安全性：合理设置头部大小，防止恶意客户端发送过大的头部数据，导致服务器资源耗尽。性能优化：确保头部大小限制不影响正常的请求处理，并优化服务器性能。 http2_max_requests

http2_max_requests 指令用于设置在关闭HTTP/2连接之前可以处理的最大请求数。这个指令帮助控制HTTP/2连接的复用和资源管理。

Syntax: http2_max_requests number; Default: http2_max_requests 1000; Context: http, server This directive appeared in version 1.11.6. number：指定在关闭HTTP/2连接之前可以处理的最大请求数，默认值为 1000。

案例

基本用法

最简单的 http2_max_requests 用法是指定一个具体的请求数量：

http { server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; location / { proxy_pass http://backend; http2_max_requests 500; } } }

在这个例子中：

设置了 http2_max_requests 500，这意味着Nginx将在关闭HTTP/2连接之前处理最多500个请求。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的最大请求数：

server { listen 443 ssl http2; server_name example1 ; ssl_certificate /etc/nginx/ssl/example1 .crt; ssl_certificate_key /etc/nginx/ssl/example1 .key; location / { proxy_pass http://backend_example1; http2_max_requests 500; } } server { listen 443 ssl http2; server_name example2 ; ssl_certificate /etc/nginx/ssl/example2 .crt; ssl_certificate_key /etc/nginx/ssl/example2 .key; location / { proxy_pass http://backend_example2; http2_max_requests 2000; } }

在这个例子中：

对于 example1 ，设置了 http2_max_requests 500。对于 example2 ，设置了 http2_max_requests 2000。

注意事项

资源管理：合理设置最大请求数，避免过高的数值导致资源耗尽或过低影响性能。适用场景：适用于需要精确控制HTTP/2连接复用的应用场景。例如，在高并发网站、API网关等环境中使用。调试和监控：如果你遇到连接复用问题，可以检查以下几点： 确保最大请求数设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 http2_push

http2_push 指令用于启用HTTP/2服务器推送功能。这个指令帮助提前推送资源到客户端，减少页面加载时间。

Syntax: http2_push uri | off; Default: http2_push off; Context: http, server, location This directive appeared in version 1.13.9. uri：指定要推送的资源URI。off：禁用HTTP/2服务器推送（默认值）。

案例

基本用法

最简单的 http2_push 用法是指定一个具体的资源URI：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; location / { root /var/ /html; http2_push /css/style.css; } }

在这个例子中：

设置了 http2_push /css/style.css，这意味着Nginx将提前推送 /css/style.css 资源给客户端。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置不同的推送资源：

server { listen 443 ssl http2; server_name example1 ; ssl_certificate /etc/nginx/ssl/example1 .crt; ssl_certificate_key /etc/nginx/ssl/example1 .key; location / { root /var/ /html_example1; http2_push /css/style1.css; } } server { listen 443 ssl http2; server_name example2 ; ssl_certificate /etc/nginx/ssl/example2 .crt; ssl_certificate_key /etc/nginx/ssl/example2 .key; location / { root /var/ /html_example2; http2_push /css/style2.css; } }

在这个例子中：

对于 example1 ，设置了 http2_push /css/style1.css。对于 example2 ，设置了 http2_push /css/style2.css。

注意事项

资源选择：合理选择需要推送的资源，避免不必要的资源推送增加网络负担。适用场景：适用于需要优化页面加载速度的应用场景。例如，在提升用户体验、减少首次渲染时间等方面使用。调试和监控：如果你遇到推送资源问题，可以检查以下几点： 确保推送资源设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 http2_push_preload

http2_push_preload 指令用于启用对 <link rel="preload"> 标签的支持，并将其转换为HTTP/2服务器推送。这个指令帮助自动推送预加载的资源。

Syntax: http2_push_preload on | off; Default: http2_push_preload off; Context: http, server, location This directive appeared in version 1.13.9. on：启用对 <link rel="preload"> 标签的支持并自动推送资源。off：禁用此功能（默认值）。

案例

基本用法

最简单的 http2_push_preload 用法是指定是否启用预加载支持：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; location / { root /var/ /html; http2_push_preload on; } }

在这个例子中：

设置了 http2_push_preload on，这意味着Nginx将自动推送带有 <link rel="preload"> 标签的资源。

动态设置不同配置

你可以根据不同的域名或服务器块动态设置是否启用预加载支持：

server { listen 443 ssl http2; server_name example1 ; ssl_certificate /etc/nginx/ssl/example1 .crt; ssl_certificate_key /etc/nginx/ssl/example1 .key; location / { root /var/ /html_example1; http2_push_preload on; } } server { listen 443 ssl http2; server_name example2 ; ssl_certificate /etc/nginx/ssl/example2 .crt; ssl_certificate_key /etc/nginx/ssl/example2 .key; location / { root /var/ /html_example2; http2_push_preload off; } }

在这个例子中：

对于 example1 ，设置了 http2_push_preload on。对于 example2 ，设置了 http2_push_preload off。

注意事项

自动推送：合理利用 <link rel="preload"> 标签，避免不必要的资源推送增加网络负担。适用场景：适用于需要自动推送预加载资源以优化页面加载速度的应用场景。例如，在提升用户体验、减少首次渲染时间等方面使用。调试和监控：如果你遇到预加载资源问题，可以检查以下几点： 确保预加载支持设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 http2_recv_buffer_size

http2_recv_buffer_size 指令用于设置接收HTTP/2帧时的缓冲区大小。这个指令帮助优化HTTP/2协议的数据传输效率。

Syntax: http2_recv_buffer_size size; Default: http2_recv_buffer_size 256k; Context: http size：指定接收缓冲区的大小，默认值为 256k。

案例

基本用法

最简单的 http2_recv_buffer_size 用法是指定一个具体的缓冲区大小：

http { http2_recv_buffer_size 512k; server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example .crt; ssl_certificate_key /etc/nginx/ssl/example .key; location / { root /var/ /html; } } }

在这个例子中：

设置了 http2_recv_buffer_size 512k，这意味着Nginx将使用512KB的接收缓冲区来处理HTTP/2帧。

动态设置不同配置

由于 http2_recv_buffer_size 只能在 http 上下文中配置，因此不能针对不同的服务器块单独设置。你可以在主配置文件中统一设置：

http { http2_recv_buffer_size 1m; server { listen 443 ssl http2; server_name example1 ; ssl_certificate /etc/nginx/ssl/example1 .crt; ssl_certificate_key /etc/nginx/ssl/example1 .key; location / { root /var/ /html_example1; } } server { listen 443 ssl http2; server_name example2 ; ssl_certificate /etc/nginx/ssl/example2 .crt; ssl_certificate_key /etc/nginx/ssl/example2 .key; location / { root /var/ /html_example2; } } }

在这个例子中：

所有服务器块都将使用 http2_recv_buffer_size 1m 的设置。

注意事项

性能与资源平衡：合理设置接收缓冲区大小，避免过大导致内存占用过高或过小影响数据传输效率。适用场景：适用于需要优化HTTP/2协议数据传输效率的应用场景。例如，在高并发网站、实时应用等环境中使用。调试和监控：如果你遇到接收缓冲区问题，可以检查以下几点： 确保接收缓冲区大小设置合理，并符合你的需求。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。使用工具模拟不同负载条件下的请求进行测试，确保在各种情况下都能正常工作。 http2_recv_timeout

http2_recv_timeout 指令用于设置 HTTP/2 连接中接收数据的超时时间。

Syntax: http2_recv_timeout time; Default: http2_recv_timeout 30s; Context: http, server time：指定超时时间，默认值为 30 秒。

案例

基本用法

最简单的 http2_recv_timeout 用法是指定超时时间：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 设置 HTTP/2 接收数据的超时时间为 60 秒 http2_recv_timeout 60s; location / { proxy_pass http://backend.example ; } }

在这个例子中：

设置了 HTTP/2 接收数据的超时时间为 60 秒。

使用默认值

你可以选择使用默认值（30 秒）：

server { listen 443 ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 使用默认的超时时间（30 秒） http2_recv_timeout 30s; location / { proxy_pass http://backend.example ; } }

在这个例子中：

使用默认的超时时间（30 秒）。

注意事项

性能优化：合理设置超时时间可以避免长时间未响应的连接占用资源，但过短的超时时间可能导致正常请求被中断。适用场景：适用于需要控制 HTTP/2 连接中接收数据超时的应用场景。例如，在高流量网站或需要处理大量并发请求的环境中，适当调整超时时间可以提高系统的稳定性和性能。调试和监控：如果你遇到超时问题，可以检查以下几点： 确保数值设置合理，不会导致过多的超时或过早中断。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 2.2 ngx_http_v3_module

ngx_http_v3_module 是 Nginx 的一个模块，用于支持 HTTP/3 协议。HTTP/3 是基于 QUIC（Quick UDP Internet Connections）传输协议的新一代 HTTP 协议，旨在提高网络连接的性能和可靠性，特别是在高延迟和不稳定的网络环境中。

主要功能

QUIC 支持：通过 QUIC 协议实现更快的连接建立和更高效的传输。0-RTT 连接恢复：允许客户端在重新连接时跳过握手过程，从而减少延迟。多路复用：多个请求可以共享同一个连接，避免了队头阻塞问题。增强的安全性：默认使用 TLS 1.3 加密，确保数据传输的安全性。

配置要求

为了启用 ngx_http_v3_module 模块，你需要满足以下条件：

Nginx 版本：确保你使用的是支持 HTTP/3 的 Nginx 版本（例如 Nginx 1.19.7 及以上版本）。OpenSSL 版本：需要 OpenSSL 1.1.1 或更高版本来支持 QUIC 和 TLS 1.3。BoringSSL：Nginx 对 HTTP/3 的支持依赖于 BoringSSL 库，因此你可能需要下载并编译 BoringSSL。

常用指令

listen

用途：指定服务器监听的端口和协议类型。

示例：

listen 443 quic reuseport;

http3

用途：启用 HTTP/3 支持。

示例：

http3 on;

quic

用途：配置 QUIC 相关参数。

示例：

quic { max_idle_timeout 60s; initial_max_data 1048576; }

使用示例

以下是一些简化的配置示例，展示了如何使用 ngx_http_v3_module 来启用 HTTP/3 支持。

基本 HTTP/3 配置

假设你希望为你的网站启用 HTTP/3 支持：

server { listen 443 quic reuseport ssl http2; listen [::]:443 quic reuseport ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example_com.crt; ssl_certificate_key /etc/nginx/ssl/example_com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { root /var/ /html; index index.html index.htm; } }

在这个例子中：

listen 443 quic reuseport ssl http2; 启用了 HTTP/3、HTTP/2 和 SSL/TLS 支持。ssl_certificate 和 ssl_certificate_key 分别指定了服务器证书和私钥文件的路径。ssl_protocols 和 ssl_ciphers 设置了支持的协议和加密套件。

详细配置 QUIC 参数

你可以进一步配置 QUIC 相关参数以优化性能：

server { listen 443 quic reuseport ssl http2; listen [::]:443 quic reuseport ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example_com.crt; ssl_certificate_key /etc/nginx/ssl/example_com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; quic { max_idle_timeout 60s; initial_max_data 1048576; initial_max_stream_data_bidi_local 262144; initial_max_stream_data_bidi_remote 262144; initial_max_stream_data_uni 262144; initial_max_streams_bidi 100; initial_max_streams_uni 100; ack_delay_exponent 3; max_ack_delay 25ms; } location / { root /var/ /html; index index.html index.htm; } }

在这个例子中：

quic 块定义了多个 QUIC 参数，包括最大空闲超时时间、初始最大数据量等。

强制重定向 HTTP 到 HTTPS

为了确保所有请求都通过 HTTPS 处理，可以配置 HTTP 请求自动重定向到 HTTPS：

server { listen 80; server_name example ; # 强制重定向到 HTTPS return 301 $host$request_uri; } server { listen 443 quic reuseport ssl http2; listen [::]:443 quic reuseport ssl http2; server_name example ; ssl_certificate /etc/nginx/ssl/example_com.crt; ssl_certificate_key /etc/nginx/ssl/example_com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; quic { max_idle_timeout 60s; initial_max_data 1048576; } location / { root /var/ /html; index index.html index.htm; } }

在这个例子中：

第一个 server 块监听 HTTP 端口 80，并将所有请求重定向到 HTTPS。第二个 server 块监听 HTTPS 端口 443，并配置了 HTTP/3 和 QUIC 参数。

注意事项

BoringSSL 库：Nginx 对 HTTP/3 的支持依赖于 BoringSSL 库，而不是标准的 OpenSSL。你需要从 BoringSSL GitHub 仓库 下载并编译 BoringSSL。

编译步骤如下：

克隆 BoringSSL 仓库：

git clone github /google/boringssl.git cd boringssl

编译 BoringSSL：

mkdir build cd build cmake .. make

下载并编译 Nginx，使用 BoringSSL 而不是 OpenSSL：

wget http://nginx.org/download/nginx-1.21.4.tar.gz tar -zxvf nginx-1.21.4.tar.gz cd nginx-1.21.4 ./configure --with-http_v3_module --with-cc-opt="-I/path/to/boringssl/include" --with-ld-opt="-L/path/to/boringssl/build/ssl -L/path/to/boringssl/build/crypto" make sudo make install

防火墙设置：确保防火墙允许 UDP 流量，因为 QUIC 协议基于 UDP。

sudo ufw allow 443/udp

日志记录：为了方便调试和监控，建议启用详细的日志记录，特别是在配置 HTTP/3 时。

error_log /var/log/nginx/error.log warn; access_log /var/log/nginx/access.log main;

测试配置：在生产环境中部署前，务必进行充分的测试，确保 HTTP/3 配置正确无误。可以使用工具如 Qualys SSL Labs 来评估你的 SSL/TLS 配置是否支持 HTTP/3。

通过合理配置 ngx_http_v3_module，你可以为你的网站提供更快、更可靠的连接体验。

2.2.1 指令列表 http3

http3 指令用于启用或禁用 HTTP/3 支持。

Syntax: http3 on | off; Default: http3 on; Context: http, server on：启用 HTTP/3 支持。off：禁用 HTTP/3 支持。

案例

启用 HTTP/3

最简单的 http3 用法是启用 HTTP/3 支持：

server { listen 443 ssl http3; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 启用 HTTP/3 支持 http3 on; location / { proxy_pass http://backend.example ; } }

在这个例子中：

启用了 HTTP/3 支持。

禁用 HTTP/3

你可以选择禁用 HTTP/3 支持：

server { listen 443 ssl; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 禁用 HTTP/3 支持 http3 off; location / { proxy_pass http://backend.example ; } }

在这个例子中：

禁用了 HTTP/3 支持。

注意事项

兼容性：确保客户端支持 HTTP/3 协议，否则可能会导致连接失败。适用场景：适用于需要利用 HTTP/3 提供的性能优势的应用场景。例如，在高延迟或不稳定网络环境中，HTTP/3 可以显著提高页面加载速度和用户体验。调试和监控：如果你遇到 HTTP/3 支持问题，可以检查以下几点： 确保 Nginx 配置正确，并且服务器支持 QUIC 协议。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 http3_hq

http3_hq 指令用于启用或禁用 HTTP/3 的 HQ（Header Compression）功能。

Syntax: http3_hq on | off; Default: http3_hq off; Context: http, server on：启用 HTTP/3 的 HQ 功能。off：禁用 HTTP/3 的 HQ 功能。

案例

启用 HQ 功能

最简单的 http3_hq 用法是启用 HQ 功能：

server { listen 443 ssl http3; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 启用 HTTP/3 支持 http3 on; # 启用 HTTP/3 的 HQ 功能 http3_hq on; location / { proxy_pass http://backend.example ; } }

在这个例子中：

启用了 HTTP/3 的 HQ 功能。

禁用 HQ 功能

你可以选择禁用 HQ 功能：

server { listen 443 ssl http3; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 启用 HTTP/3 支持 http3 on; # 禁用 HTTP/3 的 HQ 功能 http3_hq off; location / { proxy_pass http://backend.example ; } }

在这个例子中：

禁用了 HTTP/3 的 HQ 功能（默认值）。

注意事项

性能优化：启用 HQ 功能可以减少传输的数据量，但在某些情况下可能会增加 CPU 负载。根据实际需求进行权衡。适用场景：适用于需要减少传输数据量的应用场景。例如，在移动设备或低带宽网络环境中，启用 HQ 功能可以显著提高传输效率。调试和监控：如果你遇到 HQ 功能问题，可以检查以下几点： 确保 Nginx 配置正确，并且服务器支持 HQ 功能。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 http3_max_concurrent_streams

http3_max_concurrent_streams 指令用于设置 HTTP/3 连接中最大并发流的数量。

Syntax: http3_max_concurrent_streams number; Default: http3_max_concurrent_streams 128; Context: http, server number：指定最大并发流的数量，默认值为 128。

案例

基本用法

最简单的 http3_max_concurrent_streams 用法是指定最大并发流的数量：

server { listen 443 ssl http3; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 启用 HTTP/3 支持 http3 on; # 设置最大并发流数量为 256 http3_max_concurrent_streams 256; location / { proxy_pass http://backend.example ; } }

在这个例子中：

设置了最大并发流数量为 256。

使用默认值

你可以选择使用默认值（128）：

server { listen 443 ssl http3; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 启用 HTTP/3 支持 http3 on; # 使用默认的最大并发流数量（128） http3_max_concurrent_streams 128; location / { proxy_pass http://backend.example ; } }

在这个例子中：

使用默认的最大并发流数量（128）。

注意事项

性能优化：合理设置最大并发流数量可以平衡资源使用和性能。过高的并发流数量可能导致资源耗尽，而过低则可能限制性能。适用场景：适用于需要控制 HTTP/3 连接中并发流数量的应用场景。例如，在高并发环境下，适当调整并发流数量可以提高系统性能和稳定性。调试和监控：如果你遇到并发流数量问题，可以检查以下几点： 确保数值设置合理，不会导致过多的并发流或资源耗尽。查看Nginx的日志文件，确认是否有与此相关的警告或错误信息。 http3_stream_buffer_size

http3_stream_buffer_size 指令用于设置 HTTP/3 流的缓冲区大小。这影响着数据在传输过程中的缓冲效率和性能，特别是在高并发场景下。

Syntax: http3_stream_buffer_size size; Default: http3_stream_buffer_size 64k; Context: http, server size：指定缓冲区大小，默认值为 64k（即64KB）。

案例

设置较大的缓冲区

假设我们希望增加 HTTP/3 流的缓冲区大小以提高处理大文件时的性能：

http { server { listen 80 http3; server_name example ; # 增加 HTTP/3 流的缓冲区大小到 128KB http3_stream_buffer_size 128k; } }

使用默认的缓冲区大小

如果我们希望使用默认的64KB缓冲区大小：

http { server { listen 80 http3; server_name example ; # 使用默认的 64KB 缓冲区大小 http3_stream_buffer_size 64k; } }

注意事项

性能优化：适当增加缓冲区大小可以提高大文件传输的性能，但过大的缓冲区可能会导致内存占用过高。资源管理：根据实际应用场景调整缓冲区大小，确保系统资源的有效利用。 quic_active_connection_id_limit

quic_active_connection_id_limit 指令用于设置 QUIC 协议中允许的活动连接 ID 的最大数量。这有助于控制服务器端的资源消耗，并防止滥用。

Syntax: quic_active_connection_id_limit number; Default: quic_active_connection_id_limit 2; Context: http, server number：指定允许的最大活动连接 ID 数量，默认值为 2。

案例

设置较大的连接 ID 限制

假设我们希望增加允许的活动连接 ID 数量以支持更多的并发连接：

http { server { listen 80 quic; server_name example ; # 增加允许的活动连接 ID 数量到 5 quic_active_connection_id_limit 5; } }

使用默认的连接 ID 限制

如果我们希望使用默认的2个活动连接 ID：

http { server { listen 80 quic; server_name example ; # 使用默认的 2 个活动连接 ID quic_active_connection_id_limit 2; } }

注意事项

资源管理：增加活动连接 ID 数量可以支持更多并发连接，但也需要相应增加服务器资源。安全性：合理设置连接 ID 限制，避免被滥用导致资源耗尽。 quic_bpf

quic_bpf 指令用于启用或禁用 BPF（Berkeley Packet Filter）支持，主要用于高级网络调试和监控。BPF 可以帮助捕获和分析网络流量，但在大多数情况下不需要启用。

Syntax: quic_bpf on | off; Default: quic_bpf off; Context: main on：启用 BPF 支持。off（默认）：禁用 BPF 支持。

案例

启用 BPF 支持

假设我们需要启用 BPF 支持进行高级网络调试：

main { # 启用 BPF 支持 quic_bpf on; }

禁用 BPF 支持

如果我们不需要 BPF 支持：

main { # 禁用 BPF 支持（默认行为） quic_bpf off; }

注意事项

调试工具：BPF 主要用于高级调试和监控，普通应用通常不需要启用。性能影响：启用 BPF 可能会对性能产生一定影响，需谨慎使用。 quic_gso

quic_gso 指令用于启用或禁用 GSO（Generic Segmentation Offload）支持。GSO 是一种网络优化技术，通过减少内核中断次数来提高网络性能。

Syntax: quic_gso on | off; Default: quic_gso off; Context: http, server on：启用 GSO 支持。off（默认）：禁用 GSO 支持。

案例

启用 GSO 支持

假设我们希望启用 GSO 支持以提高网络性能：

http { server { listen 80 quic; server_name example ; # 启用 GSO 支持 quic_gso on; } }

禁用 GSO 支持

如果我们不希望启用 GSO 支持：

http { server { listen 80 quic; server_name example ; # 禁用 GSO 支持（默认行为） quic_gso off; } }

注意事项

性能优化：GSO 可以显著提高网络性能，尤其是在高吞吐量场景下。硬件兼容性：确保服务器硬件支持 GSO，否则可能无法获得预期的性能提升。 quic_host_key

quic_host_key 指令用于指定 QUIC 协议使用的主机密钥文件。QUIC 是一种基于 UDP 的传输协议，旨在提高网络连接的安全性和性能。

Syntax: quic_host_key file; Default: — Context: http, server file：QUIC 协议使用的主机密钥文件路径。

案例

基本用法

最简单的 quic_host_key 用法是指定主机密钥文件路径：

server { listen 443 quic ssl; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 指定 QUIC 主机密钥文件路径 quic_host_key /etc/nginx/ssl/quic_host_key.pem; location / { proxy_pass http://backend; } }

在这个例子中：

当 Nginx 使用 QUIC 协议与客户端通信时，将使用 /etc/nginx/ssl/quic_host_key.pem 文件中的密钥进行加密和身份验证。

注意事项

安全性：确保主机密钥文件的安全性，防止未经授权的访问。配置要求：确保正确生成并配置了主机密钥文件，以支持 QUIC 协议的安全通信。 quic_retry

quic_retry 指令用于控制是否启用 QUIC 协议的重试机制。重试机制有助于防止中间人攻击（MITM）和其他潜在的安全威胁。

Syntax: quic_retry on | off; Default: quic_retry off; Context: http, server on：启用 QUIC 协议的重试机制。off：禁用 QUIC 协议的重试机制，默认行为。

案例

基本用法

最简单的 quic_retry 用法是启用或禁用重试机制：

server { listen 443 quic ssl; server_name example ; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; # 启用 QUIC 重试机制 quic_retry on; location / { proxy_pass http://backend; } }

在这个例子中：

当客户端尝试通过 QUIC 协议与 Nginx 进行通信时，Nginx 将启用重试机制来增强安全性。

注意事项

安全性：启用重试机制可以防止某些类型的攻击，但可能会增加初始连接的时间。性能考虑：在高并发环境下，频繁的重试可能会增加服务器负载。 2.3 ngx_http_xslt_module

ngx_http_xslt_module 是 Nginx 的一个模块，用于在将 XML 数据发送给客户端之前，使用 XSLT（Extensible Stylesheet Language Transformations）样式表对 XML 进行转换。这个模块使得 Nginx 能够作为一个轻量级的中间层，在处理 XML 数据时进行格式化和转换，从而生成更易读或更适合特定应用需求的输出。

主要功能

XML 转换：通过 XSLT 样式表对 XML 数据进行转换。动态加载 XSLT 样式表：可以根据请求的不同动态选择不同的 XSLT 样式表。支持参数传递：可以将请求参数传递给 XSLT 样式表，以便在转换过程中使用这些参数。

常用指令

以下是 ngx_http_xslt_module 中一些常用的指令及其说明：

xslt_stylesheet: 定义用于转换 XML 数据的 XSLT 样式表文件路径。

xslt_string: 直接在配置文件中定义 XSLT 样式表内容（通常不推荐，因为样式表可能较长且难以维护）。

xslt_types: 指定哪些 MIME 类型的响应需要进行 XSLT 转换，默认是 text/xml。

xslt_parameters: 将请求参数传递给 XSLT 样式表。可以在样式表中使用这些参数来控制转换逻辑。

使用示例

以下是一些具体的配置示例，展示了如何使用 ngx_http_xslt_module 对 XML 数据进行转换。

基本配置

假设你有一个 XML 文件，并希望使用 XSLT 样式表对其进行转换：

server { listen 80; server_name example ; location /xml { # 设置根目录 root /var/ /data; # 启用 XSLT 转换 xslt_stylesheet /etc/nginx/stylesheet.xsl; # 设置需要进行 XSLT 转换的 MIME 类型 xslt_types application/xml; } }

在这个例子中：

xslt_stylesheet /etc/nginx/stylesheet.xsl; 指定了用于转换 XML 数据的 XSLT 样式表文件路径。xslt_types application/xml; 指定了需要进行 XSLT 转换的 MIME 类型为 application/xml。

动态加载 XSLT 样式表

你可以根据请求的不同动态选择不同的 XSLT 样式表：

server { listen 80; server_name example ; location /xml { # 设置根目录 root /var/ /data; # 根据请求参数选择不同的 XSLT 样式表 if ($arg_style = "mobile") { xslt_stylesheet /etc/nginx/mobile.xsl; } if ($arg_style = "desktop") { xslt_stylesheet /etc/nginx/desktop.xsl; } # 设置需要进行 XSLT 转换的 MIME 类型 xslt_types application/xml; } }

在这个例子中：

if ($arg_style = "mobile") { ... } 和 if ($arg_style = "desktop") { ... } 根据请求参数 style 的值动态选择不同的 XSLT 样式表。

传递参数到 XSLT 样式表

你可以将请求参数传递给 XSLT 样式表，以便在转换过程中使用这些参数：

server { listen 80; server_name example ; location /xml { # 设置根目录 root /var/ /data; # 启用 XSLT 转换并传递参数 xslt_stylesheet /etc/nginx/stylesheet.xsl; xslt_parameters $lang $theme; # 设置需要进行 XSLT 转换的 MIME 类型 xslt_types application/xml; } }

在这个例子中：

xslt_parameters $lang $theme; 将请求参数 lang 和 theme 传递给 XSLT 样式表。在 XSLT 样式表中，可以通过 $lang 和 $theme 变量访问这些参数。

注意事项

性能考虑：XSLT 转换可能会消耗一定的计算资源，特别是在高并发环境下。建议对 XSLT 样式表进行优化，避免复杂的转换逻辑。缓存机制：为了提高性能，可以结合使用缓存机制（如 proxy_cache 或 fastcgi_cache），以减少重复的 XSLT 转换操作。安全性：确保 XSLT 样式表的内容是安全的，防止恶意代码注入。可以使用静态样式表文件而不是动态生成的样式表，以降低风险。测试验证：在部署之前进行全面测试，确保所有配置按预期工作，并检查是否有任何潜在的问题（如转换错误、样式表未正确加载等）。 2.3.1 指令列表 xml_entities

xml_entities 指令用于指定 XML 实体文件的路径。XML 实体文件定义了自定义实体，这些实体可以在处理 XML 文档时被引用。

Syntax: xml_entities path; Default: — Context: http, server, location path：XML 实体文件的路径。

案例

基本用法

最简单的 xml_entities 用法是指定 XML 实体文件路径：

server { listen 80; server_name example ; location /xml { # 指定 XML 实体文件路径 xml_entities /etc/nginx/xml/entities.dtd; # 处理 XML 请求 proxy_pass http://backend; } }

在这个例子中：

当 Nginx 处理 /xml 路径下的请求时，将使用 /etc/nginx/xml/entities.dtd 文件中的定义来解析和处理 XML 实体。

注意事项

文件路径：确保指定的 XML 实体文件路径存在并且 Nginx 对其具有读权限。安全性：避免加载不受信任的 XML 实体文件，以防止潜在的安全风险。 xslt_last_modified

xslt_last_modified 指令用于控制是否启用 XSLT 输出的最后修改时间头信息。这有助于优化缓存策略和提高性能。

Syntax: xslt_last_modified on | off; Default: xslt_last_modified off; Context: http, server, location This directive appeared in version 1.5.1. on：启用 XSLT 输出的最后修改时间头信息。off：禁用 XSLT 输出的最后修改时间头信息，默认行为。

案例

基本用法

最简单的 xslt_last_modified 用法是启用或禁用最后修改时间头信息：

server { listen 80; server_name example ; location /xml-transform { # 启用 XSLT 输出的最后修改时间头信息 xslt_last_modified on; # 指定 XSLT 样式表 xslt_stylesheet /etc/nginx/xslt/style.xsl; # 处理 XML 请求并应用 XSLT 转换 proxy_pass http://backend; } }

在这个例子中：

当 Nginx 处理 /xml-transform 路径下的请求并应用 XSLT 转换时，会包含 Last-Modified 响应头，指示输出内容的最后修改时间。

注意事项

缓存优化：启用 xslt_last_modified 可以帮助客户端和代理服务器更好地管理缓存，减少不必要的请求。响应头准确性：确保 Last-Modified 响应头的值准确反映实际的最后修改时间，以免误导客户端缓存策略。 xslt_param

xslt_param 用于在 XSLT 转换过程中传递参数给 XSLT 样式表。这允许你在转换 XML 数据时动态地向样式表传递值，从而实现更灵活的转换逻辑。

Syntax: xslt_param parameter value; Default: — Context: http, server, location This directive appeared in version 1.1.18. parameter：指定要传递给 XSLT 样式表的参数名称。value：指定参数的值。

案例

基本用法

最简单的 xslt_param 用法是指定参数及其值：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; xslt_param title "Example Title"; # 传递参数 'title' 及其值 'Example Title' } }

在这个例子中，设置了 xslt_param title "Example Title"，这意味着在执行 XSLT 转换时，将传递一个名为 title 的参数，并将其值设置为 "Example Title"。

多个参数

根据实际需求传递多个参数：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; xslt_param title "Example Title"; # 传递第一个参数 xslt_param author "John Doe"; # 传递第二个参数 } }

在这个例子中，传递了两个参数：title 和 author。

注意事项

灵活性：通过传递参数，可以使 XSLT 样式表更加通用和灵活。数据安全：确保传递的参数值是安全的，避免注入攻击等安全问题。 xslt_string_param

xslt_string_param 与 xslt_param 类似，但专门用于传递字符串类型的参数。它允许你明确指定传递的参数类型为字符串。

Syntax: xslt_string_param parameter value; Default: — Context: http, server, location This directive appeared in version 1.1.18. parameter：指定要传递给 XSLT 样式表的参数名称。value：指定参数的值（字符串类型）。

案例

基本用法

最简单的 xslt_string_param 用法是指定参数及其字符串值：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; xslt_string_param title "Example Title"; # 传递字符串参数 'title' } }

在这个例子中，设置了 xslt_string_param title "Example Title"，这意味着在执行 XSLT 转换时，将传递一个名为 title 的字符串参数，并将其值设置为 "Example Title"。

多个字符串参数

根据实际需求传递多个字符串参数：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; xslt_string_param title "Example Title"; # 传递第一个字符串参数 xslt_string_param author "John Doe"; # 传递第二个字符串参数 } }

在这个例子中，传递了两个字符串参数：title 和 author。

注意事项

明确性：使用 xslt_string_param 明确指定了传递的参数类型为字符串，有助于提高代码的可读性和维护性。适用场景：适用于需要明确传递字符串参数的场景。 xslt_stylesheet

xslt_stylesheet 用于指定用于 XML 转换的 XSLT 样式表文件路径，并可以传递参数给样式表。这使得你可以将 XML 数据转换为其他格式（如 HTML、文本等）。

Syntax: xslt_stylesheet stylesheet [parameter=value ...]; Default: — Context: location stylesheet：指定 XSLT 样式表文件的路径。[parameter=value ...]：可选参数，指定传递给 XSLT 样式表的参数及其值。

案例

基本用法

最简单的 xslt_stylesheet 用法是指定样式表文件路径：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; # 指定样式表文件路径 } }

在这个例子中，指定了 XSLT 样式表文件路径 /etc/nginx/xslt/transform.xsl。

传递参数

根据实际需求传递参数给样式表：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl title="Example Title" author="John Doe"; # 传递参数给样式表 } }

在这个例子中，传递了两个参数：title 和 author 给样式表。

完整配置示例

结合多个指令进行完整配置：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl title="Example Title" author="John Doe"; # 指定样式表并传递参数 xslt_param subtitle "Subtitle Text"; # 额外传递参数 } location /another_transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/another_transform.xsl; # 不同的样式表 } }

在这个例子中：

对于 /transform 路径下的请求，使用了样式表 /etc/nginx/xslt/transform.xsl 并传递了多个参数。对于 /another_transform 路径下的请求，使用了不同的样式表 /etc/nginx/xslt/another_transform.xsl。

注意事项

路径正确性：确保指定的样式表文件路径正确，并且 Nginx 进程具有访问该文件的权限。参数传递：合理使用参数传递功能，使样式表更具灵活性和通用性。 xslt_types

xslt_types 用于指定哪些 MIME 类型的响应应被转换为 XSLT 样式表处理。默认情况下，只有 text/xml 类型的响应会被处理。

Syntax: xslt_types mime-type ...; Default: xslt_types text/xml; Context: http, server, location mime-type：指定要处理的 MIME 类型，默认为 text/xml。

案例

基本用法

最简单的 xslt_types 用法是指定处理的 MIME 类型：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; xslt_types application/xml text/xml; # 处理多种 MIME 类型 } }

在这个例子中，设置了 xslt_types application/xml text/xml，这意味着除了默认的 text/xml 类型外，还将处理 application/xml 类型的响应。

扩展处理类型

根据实际需求扩展处理的 MIME 类型：

server { listen 80; server_name example ; location /transform { root /var/ /xml; xslt_stylesheet /etc/nginx/xslt/transform.xsl; xslt_types text/xml application/xml text/plain; # 处理更多的 MIME 类型 } }

在这个例子中，处理了三种 MIME 类型：text/xml、application/xml 和 text/plain。

注意事项

兼容性：确保指定的 MIME 类型确实适合 XSLT 转换，以避免不必要的错误或性能问题。灵活性：通过扩展处理的 MIME 类型，可以使 XSLT 转换功能更加灵活和强大。