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

nginx ngx_http_module(10) 指令详解

news 2025/11/28 20:26:50

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
  • 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.2 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.3 ngx_http_xslt_module
  • xml_entities
  • xslt_last_modified
  • xslt_param
  • xslt_string_param
  • xslt_stylesheet
  • xslt_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 和 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.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.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.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 模块，你需要满足以下条件：

  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.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.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.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.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.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.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 转换功能更加灵活和强大。

相关文章：

nginx ngx_http_module(10) 指令详解

nginx ngx_http_module(10) 指令详解 nginx 模块目录 nginx 全指令目录 一、目录 1.1 模块简介 ngx_http_v2_module&#xff1a;HTTP/2支持模块&#xff0c;允许Nginx通过HTTP/2协议与客户端进行通信。HTTP/2带来了许多性能优化&#xff0c;如多路复用、头部压缩和服务器推…...

编程日记 2025/2/21 4:13:33

【ENSP】链路聚合的两种模式

【ENSP】链路聚合的两种模式 1、背景介绍2、链路聚合的使用场景3、配置过程1、手工模式Eth-Trunk配置2、静态LACP模式Eth-Trunk 4、总结 1、背景介绍 随着网络规模的不断扩大&#xff0c;人们对骨干链路的带宽吞吐量和可靠性提出了越来越高的要求。在传统方案中&#xff0c;为…...

编程日记 2025/2/21 4:12:32

Windows环境安装部署minimind步骤

Windows环境安装部署minimind步骤 必要的软件环境 git git&#xff0c;可下载安装版&#xff0c;本机中下载绿色版&#xff0c;解压到本地目录下&#xff08;如&#xff1a;c:\soft\git.win64&#xff09;&#xff0c;可将此路径添加到PATH环境变量中&#xff0c;供其他程序…...

编程日记 2025/2/21 4:05:24

让大模型帮我设计crnn网络及可运行demo，gpt4o豆包qwendeepseek-r1

prompt 使用 crnn 提取图像特征&#xff0c;给出图像好坏的二分类结果&#xff0c;写清楚代码备注&#xff0c;注释清楚向量维度大小&#xff0c;并给出一个可运行的 demo1、GPT-4o 以下是一个使用 CRNN&#xff08;Convolutional Recurrent Neural Network&#xff09;提取图…...

编程日记 2025/2/21 4:03:21

代码随想录-- 第一天图论 --- 岛屿的数量

99 统计岛屿的数量 c 99. 岛屿数量 #include <iostream> #include <vector> #include <queue>using namespace std;struct MGraph {int numVertices, numEdges;vector<vector<int>> Edge; };int dir[4][2] {{1, 0}, {0, 1}, {-1, 0}, {0, -1}…...

编程日记 2025/2/21 4:01:19

Mybatis MyBatis框架的缓存 一级缓存

1. 缓存的概念 缓存的概念 在内存中临时存储数据&#xff0c;速度快&#xff0c;可以减少数据库的访问次数。经常需要查询&#xff0c;不经常修改的数据&#xff0c;不是特别重要的数据都适合于存储到缓存中。 2.Mybatis缓存 mybatis包含了一个非常强大的查询缓存特性&#…...

编程日记 2025/2/21 3:56:11

Weboffice在线Word权限控制：限制编辑，只读、修订、禁止复制等

在现代企业办公中&#xff0c;文档编辑是一项常见且重要的任务。尤其是在线办公环境中&#xff0c;员工需要在网页中打开和编辑文档&#xff0c;但如何确保这些文档只能进行预览而无法被编辑或复制&#xff0c;成为许多企业面临的一个痛点。尤其是在处理涉密文档时&#xff0c;…...

编程日记 2025/2/21 3:54:07

RT-Thread+STM32L475VET6实现呼吸灯

文章目录 前言一、板载资源资源说明二、具体步骤1.新建rt_thread项目2. 打开PWM设备驱动3. 在Stm32CubeMX配置定时器3.1打开Stm32CubeMX3.2 使用外部高速时钟&#xff0c;并修改时钟树3.3打开定时器1&#xff0c;并配置通道一为PWM输出模式(定时器根据自己需求调整)3.4 打开串口…...

编程日记 2025/2/21 3:53:05

【Web前端开发精品课 HTML CSS JavaScript基础教程】第二十四章课后题答案

文章目录 问题1&#xff1a;问题2&#xff1a;问题3&#xff1a; 问题1&#xff1a; 在HTML中嵌入JavaScript&#xff0c;应该使用的标签是&#xff08; &#xff09;。 选项&#xff1a; A. <style></style> B. <script></script> C. <js><…...

编程日记 2025/2/21 3:52:02

记录 pycharm 无法识别提示导入已有的模块解决方案 No module named ‘xxx‘

在windows下&#xff0c;使用pycharm开发项目&#xff0c;每个项目都有自己独立的虚拟环境&#xff0c;有时候就会出现&#xff0c;在该项目中明明已经安装了某个模块&#xff0c;但是在写代码的时候就是导入不了&#xff0c;无法识别导入&#xff0c;在运行的时候却又是正常的…...

编程日记 2025/2/21 3:51:01

网工项目实践2.6 广域网需求分析及方案制定

本专栏持续更新&#xff0c;整一个专栏为一个大型复杂网络工程项目。阅读本文章之前务必先看《本专栏必读》。 全网拓扑展示 一.广域网互联方式 1.专线 优点 稳定 独享。绝对安全。可靠性高&#xff0c;带宽高&#xff0c;完全取决于终端接口。 缺点: 费用高。建设时间长。难…...

编程日记 2025/2/21 3:47:56

【架构】分层架构 (Layered Architecture)

一、分层模型基础理论 ![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/0365cf0bfa754229bdedca6b472bffc7.png 1. 核心定义 分层架构（Layered Architecture）模型是一种常见的软件设计架构，它将软件系统按照功能划分为不同的层次，每个层次都有特定的职责和功能…...

编程日记 2025/2/21 3:45:35

玩客云 IP查找

1.玩客云使用静态IP在不同网段路由器下不能使用&#xff0c;动态不好找IP地址 1.1使用python3 实现自动获取发送 import requests import os import socket# 从环境变量获取 PushPlus 的 token 和群组编码 PUSH_PLUS_TOKEN os.getenv("PUSH_PLUS_TOKEN") PUSH_PLU…...

编程日记 2025/2/21 3:41:10

Android - Handler使用post之后，Runnable没有执行

问题&#xff1a;子线程创建的Handler。如果 post 之后&#xff0c;在Handler.removeCallbacks(run)移除了&#xff0c;下次再使用Handler.postDelayed(Runnable)接口或者使用post时&#xff0c;Runnable是没有执行。导致没有收到消息。 解决办法&#xff1a;只有主线程创建的…...

编程日记 2025/2/21 3:40:03

MyBatis-Plus之通用枚举

MyBatis-Plus之通用枚举 前言 MyBatis-Plus中提供了通用枚举&#xff0c;简单来说就是将数据库中的某一字段的代替的含义转换成真实的含义将数据展示给用户&#xff0c;用户在存储时也会将真实值转换成代替的数字存入到数据库中。举个例子&#xff1a;用户性别在数据库中存储…...

编程日记 2025/2/21 3:38:50

基于Spring Boot的图书管理系统设计与实现（LW+源码+讲解）

专注于大学生项目实战开发,讲解,毕业答疑辅导&#xff0c;欢迎高校老师/同行前辈交流合作✌。 技术范围&#xff1a;SpringBoot、Vue、SSM、HLMT、小程序、Jsp、PHP、Nodejs、Python、爬虫、数据可视化、安卓app、大数据、物联网、机器学习等设计与开发。 主要内容&#xff1a;…...

编程日记 2025/2/21 3:26:12

如何在 VS Code 中快速使用 Copilot 来辅助开发

在日常开发中&#xff0c;编写代码往往是最耗时的环节之一。而 GitHub Copilot&#xff0c;作为一款 AI 编码助手&#xff0c;可以帮助开发者 自动补全代码、生成代码片段&#xff0c;甚至直接编写完整的函数&#xff0c;大幅提升编码效率。那么&#xff0c;如何在 VS Code 中快…...

编程日记 2025/2/21 3:25:07

12.1 Android中协程的基本使用

文章目录 前言1、导入依赖2、使用协程获取服务器中的数据2.1 定义请求回调结果的数据类2.2 网络请求 3、网络回调结构4、通过ViewModel处理网络请求数据 前言 在使用协程的时候一直没有一个具体的概念&#xff0c;只知道协程能够使得异步操作等同于同步操作&#xff0c;且不会…...

编程日记 2025/2/21 3:22:56

【黑马点评优化】2-Canel实现多级缓存（Redis+Caffeine）同步

【黑马点评优化】2-Canel实现多级缓存&#xff08;RedisCaffeine&#xff09;同步 0 背景1 配置MySQL1.1 开启MySQL的binlog功能1.1.1 找到mysql配置文件my.ini的位置1.1.2 开启binlog 1.2 创建canal用户 2 下载配置canal2.1 canal 1.1.5下载2.2 配置canal2.3 启动canal2.4 测试…...

编程日记 2025/2/21 3:21:53

php-fpm

摘要 php-fpm(fastcgi process manager)是PHP 的FastCGI管理器&#xff0c;管理PHP的FastCGI进程&#xff0c;提升PHP应用的性能和稳定性 php-fpm是一个高性能的php FastCGI管理器&#xff0c;提供了更好的php进程管理方式&#xff0c;可以有效的控制内存和进程&#xff0c;支…...

编程日记 2025/2/21 3:17:40

智慧医疗能源事业线深度画像分析（上）

引言 医疗行业作为现代社会的关键基础设施，其能源消耗与环境影响正日益受到关注。随着全球"双碳"目标的推进和可持续发展理念的深入，智慧医疗能源事业线应运而生，致力于通过创新技术与管理方案，重构医疗领域的能源使用模式。这一事业线融合了能源管理、可持续发…...

编程新知 2025/11/26 11:35:26

突破不可导策略的训练难题：零阶优化与强化学习的深度嵌合

强化学习&#xff08;Reinforcement Learning, RL&#xff09;是工业领域智能控制的重要方法。它的基本原理是将最优控制问题建模为马尔可夫决策过程&#xff0c;然后使用强化学习的Actor-Critic机制&#xff08;中文译作“知行互动”机制&#xff09;&#xff0c;逐步迭代求解…...

编程新知 2025/11/21 6:24:45

Cilium动手实验室: 精通之旅---20.Isovalent Enterprise for Cilium: Zero Trust Visibility

Cilium动手实验室: 精通之旅---20.Isovalent Enterprise for Cilium: Zero Trust Visibility 1. 实验室环境1.1 实验室环境1.2 小测试 2. The Endor System2.1 部署应用2.2 检查现有策略 3. Cilium 策略实体3.1 创建 allow-all 网络策略3.2 在 Hubble CLI 中验证网络策略源3.3 …...

编程新知 2025/11/26 11:20:42

AspectJ 在 Android 中的完整使用指南

一、环境配置&#xff08;Gradle 7.0 适配&#xff09; 1. 项目级 build.gradle // 注意&#xff1a;沪江插件已停更&#xff0c;推荐官方兼容方案 buildscript {dependencies {classpath org.aspectj:aspectjtools:1.9.9.1 // AspectJ 工具} } 2. 模块级 build.gradle plu…...

编程新知 2025/7/7 22:33:57

Linux --进程控制

本文从以下五个方面来初步认识进程控制&#xff1a; 目录 进程创建 进程终止 进程等待 进程替换 模拟实现一个微型shell 进程创建 在Linux系统中我们可以在一个进程使用系统调用fork()来创建子进程&#xff0c;创建出来的进程就是子进程&#xff0c;原来的进程为父进程。…...

编程新知 2025/11/22 2:57:58

使用Matplotlib创建炫酷的3D散点图：数据可视化的新维度

文章目录 基础实现代码代码解析进阶技巧1. 自定义点的大小和颜色2. 添加图例和样式美化3. 真实数据应用示例实用技巧与注意事项完整示例（带样式）应用场景在数据科学和可视化领域，三维图形能为我们提供更丰富的数据洞察。本文将手把手教你如何使用Python的Matplotlib库创建引…...

编程新知 2025/10/4 3:01:43

基于SpringBoot在线拍卖系统的设计和实现

摘 要 随着社会的发展&#xff0c;社会的各行各业都在利用信息化时代的优势。计算机的优势和普及使得各种信息系统的开发成为必需。 在线拍卖系统&#xff0c;主要的模块包括管理员&#xff1b;首页、个人中心、用户管理、商品类型管理、拍卖商品管理、历史竞拍管理、竞拍订单…...

编程新知 2025/11/27 13:22:52

【Android】Android 开发 ADB 常用指令

查看当前连接的设备 adb devices 连接设备 adb connect 设备IP 断开已连接的设备 adb disconnect 设备IP 安装应用 adb install 安装包的路径 卸载应用 adb uninstall 应用包名 查看已安装的应用包名 adb shell pm list packages 查看已安装的第三方应用包名 adb shell pm list…...

编程新知 2025/11/18 18:31:30

毫米波雷达基础理论（3D+4D）

3D、4D毫米波雷达基础知识及厂商选型 PreView : https://mp.weixin.qq.com/s/bQkju4r6med7I3TBGJI_bQ 1. FMCW毫米波雷达基础知识 主要参考博文&#xff1a; 一文入门汽车毫米波雷达基本原理 &#xff1a;https://mp.weixin.qq.com/s/_EN7A5lKcz2Eh8dLnjE19w 毫米波雷达基础…...

编程新知 2025/11/28 16:30:11

从零开始了解数据采集（二十八）——制造业数字孪生

近年来&#xff0c;我国的工业领域正经历一场前所未有的数字化变革&#xff0c;从“双碳目标”到工业互联网平台的推广&#xff0c;国家政策和市场需求共同推动了制造业的升级。在这场变革中&#xff0c;数字孪生技术成为备受关注的关键工具&#xff0c;它不仅让企业“看见”设…...

编程新知 2025/11/25 23:29:32