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

nginx ngx_http_module(10) 指令详解

news 2025/2/23 19:20:17

nginx ngx_http_module(10) 指令详解

相关链接

  • nginx 嵌入式变量解析目录
  • nginx 嵌入式变量全目录
  • 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.58 ngx_http_v2_module
  • http2
  • http2_body_preread_size
  • http2_chunk_size
  • http2_idle_timeout
  • http2_max_concurrent_pushes
  • http2_max_concurrent_streams
  • http2_max_field_size
  • http2_max_header_size
  • http2_max_requests
  • http2_push
  • http2_push_preload
  • http2_recv_buffer_size
  • http2_recv_timeout
1.2.59 ngx_http_v3_module
  • http3
  • http3_hq
  • http3_max_concurrent_streams
  • http3_stream_buffer_size
  • quic_active_connection_id_limit
  • quic_bpf
  • quic_gso
  • quic_host_key
  • quic_retry
1.2.60 ngx_http_xslt_module
  • xml_entities
  • xslt_last_modified
  • xslt_param
  • xslt_string_param
  • xslt_stylesheet
  • xslt_types

二、解释

2.58 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 和 SSLserver_name example.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_protocols TLSv1.2 TLSv1.3;  # 仅启用安全的 TLS 版本ssl_prefer_server_ciphers on;location / {root /var/www/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.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_protocols TLSv1.2 TLSv1.3;ssl_prefer_server_ciphers on;location / {root /var/www/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.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;ssl_protocols TLSv1.2 TLSv1.3;ssl_prefer_server_ciphers on;http2_max_concurrent_streams 100;  # 设置最大并发流数为 100location / {root /var/www/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.58.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.com;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.com 时，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.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location /upload {# 设置预读取数据量为 128 KBhttp2_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.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location /stream {# 设置响应分块大小为 16 KBhttp2_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.com;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;  # 设置最大并发推送请求数为 5server {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location / {root /var/www/html;}}
}

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

调整并发推送请求数

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

server {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location /low_push/ {root /var/www/html;http2_max_concurrent_pushes 3;  # 较少的并发推送请求数}location /high_push/ {root /var/www/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;  # 设置最大并发流数为 64server {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location / {root /var/www/html;}}
}

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

调整并发流数

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

server {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location /low_streams/ {root /var/www/html;http2_max_concurrent_streams 32;  # 较少的并发流数}location /high_streams/ {root /var/www/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;  # 设置头字段的最大大小为 8KBserver {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location / {root /var/www/html;}}
}

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

调整头字段大小

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

server {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location /small_fields/ {root /var/www/html;http2_max_field_size 2k;  # 较小的头字段大小}location /large_fields/ {root /var/www/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;  # 设置头部的总大小为 32KBserver {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location / {root /var/www/html;}}
}

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

调整头部大小

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

server {listen 443 ssl http2;server_name example.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;location /small_headers/ {root /var/www/html;http2_max_header_size 8k;  # 较小的头部大小}location /large_headers/ {root /var/www/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.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.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.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;location / {proxy_pass http://backend_example1;http2_max_requests 500;}
}server {listen 443 ssl http2;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;location / {proxy_pass http://backend_example2;http2_max_requests 2000;}
}

在这个例子中：

  • 对于 example1.com，设置了 http2_max_requests 500。
  • 对于 example2.com，设置了 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.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location / {root /var/www/html;http2_push /css/style.css;}
}

在这个例子中：

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

动态设置不同配置

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

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

在这个例子中：

  • 对于 example1.com，设置了 http2_push /css/style1.css。
  • 对于 example2.com，设置了 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.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location / {root /var/www/html;http2_push_preload on;}
}

在这个例子中：

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

动态设置不同配置

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

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

在这个例子中：

  • 对于 example1.com，设置了 http2_push_preload on。
  • 对于 example2.com，设置了 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.com;ssl_certificate /etc/nginx/ssl/example.com.crt;ssl_certificate_key /etc/nginx/ssl/example.com.key;location / {root /var/www/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.com;ssl_certificate /etc/nginx/ssl/example1.com.crt;ssl_certificate_key /etc/nginx/ssl/example1.com.key;location / {root /var/www/html_example1;}}server {listen 443 ssl http2;server_name example2.com;ssl_certificate /etc/nginx/ssl/example2.com.crt;ssl_certificate_key /etc/nginx/ssl/example2.com.key;location / {root /var/www/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.com;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.com;}
}

在这个例子中：

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

使用默认值

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

server {listen 443 ssl http2;server_name example.com;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.com;}
}

在这个例子中：

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

注意事项

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

2.59 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 模块，你需要满足以下条件：

  1. Nginx 版本：确保你使用的是支持 HTTP/3 的 Nginx 版本（例如 Nginx 1.19.7 及以上版本）。
  2. OpenSSL 版本：需要 OpenSSL 1.1.1 或更高版本来支持 QUIC 和 TLS 1.3。
  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.com;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/www/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.com;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/www/html;index index.html index.htm;}
}

在这个例子中：

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

强制重定向 HTTP 到 HTTPS

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

server {listen 80;server_name example.com;# 强制重定向到 HTTPSreturn 301 https://$host$request_uri;
}server {listen 443 quic reuseport ssl http2;listen [::]:443 quic reuseport ssl http2;server_name example.com;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/www/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。

    编译步骤如下：

    1. 克隆 BoringSSL 仓库：

      git clone https://github.com/google/boringssl.git
cd boringssl

    2. 编译 BoringSSL：

      mkdir build
cd build
cmake ..
make

    3. 下载并编译 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.59.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.com;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.com;}
}

在这个例子中：

  • 启用了 HTTP/3 支持。

禁用 HTTP/3

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

server {listen 443 ssl;server_name example.com;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.com;}
}

在这个例子中：

  • 禁用了 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.com;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.com;}
}

在这个例子中：

  • 启用了 HTTP/3 的 HQ 功能。

禁用 HQ 功能

你可以选择禁用 HQ 功能：

server {listen 443 ssl http3;server_name example.com;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.com;}
}

在这个例子中：

  • 禁用了 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.com;ssl_certificate /etc/nginx/ssl/example.crt;ssl_certificate_key /etc/nginx/ssl/example.key;# 启用 HTTP/3 支持http3 on;# 设置最大并发流数量为 256http3_max_concurrent_streams 256;location / {proxy_pass http://backend.example.com;}
}

在这个例子中：

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

使用默认值

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

server {listen 443 ssl http3;server_name example.com;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.com;}
}

在这个例子中：

  • 使用默认的最大并发流数量（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.com;# 增加 HTTP/3 流的缓冲区大小到 128KBhttp3_stream_buffer_size 128k;}
}

使用默认的缓冲区大小

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

http {server {listen 80 http3;server_name example.com;# 使用默认的 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.com;# 增加允许的活动连接 ID 数量到 5quic_active_connection_id_limit 5;}
}

使用默认的连接 ID 限制

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

http {server {listen 80 quic;server_name example.com;# 使用默认的 2 个活动连接 IDquic_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.com;# 启用 GSO 支持quic_gso on;}
}

禁用 GSO 支持

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

http {server {listen 80 quic;server_name example.com;# 禁用 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.com;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.com;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.60 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.com;location /xml {# 设置根目录root /var/www/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.com;location /xml {# 设置根目录root /var/www/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.com;location /xml {# 设置根目录root /var/www/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.60.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.com;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.com;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.com;location /transform {root /var/www/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.com;location /transform {root /var/www/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.com;location /transform {root /var/www/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.com;location /transform {root /var/www/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.com;location /transform {root /var/www/xml;xslt_stylesheet /etc/nginx/xslt/transform.xsl;  # 指定样式表文件路径}
}

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

传递参数

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

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

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

完整配置示例

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

server {listen 80;server_name example.com;location /transform {root /var/www/xml;xslt_stylesheet /etc/nginx/xslt/transform.xsl title="Example Title" author="John Doe";  # 指定样式表并传递参数xslt_param subtitle "Subtitle Text";  # 额外传递参数}location /another_transform {root /var/www/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.com;location /transform {root /var/www/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.com;location /transform {root /var/www/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 转换功能更加灵活和强大。

http://www.mrgr.cn/news/91765.html

相关文章：

  • UE 播放视频
  • 设计模式教程：代理模式（Proxy Pattern）
  • 析言GBI：用自然语言交互重构企业数据分析范式
  • HTTP SSE 实现
  • ChromeDriver下载
  • 【从0做项目】Java音缘心动（1）———项目介绍设计
  • hive开窗函数边界值ROWS BETWEEN 和 RANGE BETWEEN区别
  • Debezium 报错：“The db history topic is missing” 的处理方法
  • 小米AX3000T 路由器如何开启 SSH 安装 OpenWRT 系统，不需要降级 v1.0.91 （2025）
  • DeepSeek本地部署教程
  • rtconfig.cpython-313.pyc 在 .gitignore文件中写入 *.pyc 文件仍然没有被忽略？
  • 导入大模型产生的字符串的时候碰到的问题
  • 基于Python/Java的医院系统切换互联网医院深度编程对接探索
  • ai json处理提示词
  • 设计模式教程：解释器模式（Interpreter Pattern）
  • 前端如何把SEO优化做到极致✅
  • TOGAF之架构标准规范-信息系统架构 | 应用架构
  • AIGC视频生成明星——Emu Video模型
  • nginx ngx_http_module(7) 指令详解
  • 【Java八股文】08-计算机网络面试篇