📋 指令作用域层级

作用域说明: Nginx 指令的作用域决定了它们可以在哪个配置块中使用。层级结构如下:
  • main - 全局配置,影响 Nginx 整体行为
  • events - 事件处理配置
  • http - HTTP 服务配置
  • server - 虚拟主机配置
  • location - 路由匹配配置

核心配置指令

Main 上下文指令

指令默认值说明
worker_processes1Worker 进程数量,通常设为 CPU 核心数或 auto
error_loglogs/error.log错误日志路径和级别(debug|info|notice|warn|error|crit|alert|emerg)
pidlogs/nginx.pid主进程 PID 文件路径
daemonon是否以守护进程运行
userroot运行 Nginx 的用户和用户组
worker_rlimit_nofile-Worker 进程最大打开文件数
include-包含其他配置文件

Events 上下文指令

指令默认值说明
worker_connections1024每个 Worker 的最大连接数
use-连接处理方法(epoll|kqueue|select|poll 等)
multi_acceptoff是否一次接受多个连接
accept_mutexon是否使用互斥锁接受连接

HTTP 核心指令

基础服务指令

指令默认值作用域说明
server-http定义虚拟服务器
listen80server监听端口和地址
server_name""server虚拟主机名
roothtmlhttp, server, location网站根目录
indexindex.htmlhttp, server, location默认首页文件
location-server, location匹配请求 URI
alias-location路径别名(仅用于 location)
try_files-server, location按顺序检查文件是否存在

性能优化指令

指令默认值作用域说明
sendfileoffhttp, server, location启用零拷贝传输
tcp_nopushoffhttp, server, location优化 TCP 包发送
tcp_nodelayoffhttp, server, location禁用 Nagle 算法
keepalive_timeout75shttp, server长连接超时时间
keepalive_requests100http, server长连接最大请求数
send_timeout60shttp, server, location响应超时时间
reset_timedout_connectionoffhttp重置超时的连接

Gzip 压缩指令

指令默认值作用域说明
gzipoffhttp, server, location启用 gzip 压缩
gzip_comp_level1http, server, location压缩级别 (1-9)
gzip_typestext/htmlhttp, server, location压缩的 MIME 类型
gzip_min_length20http, server, location最小压缩长度
gzip_max_lengthunlimitedhttp, server, location最大压缩长度
gzip_buffers32 4k/16 8khttp, server, location压缩缓冲区
gzip_http_version1.1http, server, locationHTTP 版本要求
gzip_proxiedoffhttp, server, location代理响应压缩条件
gzip_varyoffhttp, server, location添加 Vary: Accept-Encoding
gzip_disable-http, server, location禁用压缩的条件

代理相关指令

基础代理指令

指令默认值作用域说明
proxy_pass-location, if代理服务器地址
proxy_set_header-http, server, location设置代理请求头
proxy_connect_timeout60shttp, server, location连接超时时间
proxy_send_timeout60shttp, server, location发送超时时间
proxy_read_timeout60shttp, server, location读取超时时间
proxy_bufferingonhttp, server, location启用代理缓冲
proxy_buffer_size4k/8khttp, server, location代理响应头缓冲区
proxy_buffers8 4k/8khttp, server, location代理响应缓冲区
proxy_busy_buffers_size8k/16khttp, server, location繁忙时缓冲区大小
proxy_max_temp_file_size1024mhttp, server, location临时文件最大大小
proxy_redirectdefaulthttp, server, location修改代理响应头
proxy_http_version1.0http, server, location代理 HTTP 版本

代理缓存指令

指令默认值作用域说明
proxy_cache_path-http定义缓存路径和参数
proxy_cacheoffhttp, server, location启用代理缓存
proxy_cache_valid-http, server, location缓存有效时间
proxy_cache_key$scheme$proxy_host$request_urihttp, server, location缓存键
proxy_cache_min_uses1http, server, location最小使用次数后缓存
proxy_cache_use_staleoffhttp, server, location使用过期缓存的条件
proxy_cache_methodsGET HEADhttp, server, location缓存的 HTTP 方法
proxy_no_cache-http, server, location不缓存的条件
proxy_cache_bypass-http, server, location绕过缓存的条件

代理其他指令

指令默认值作用域说明
proxy_next_upstreamerror timeouthttp, server, location切换到后端服务器的条件
proxy_next_upstream_triesunlimitedhttp, server, location最大尝试次数
proxy_next_upstream_timeoutunlimitedhttp, server, location尝试超时时间
proxy_ignore_client_abortoffhttp, server, location忽略客户端中断
proxy_intercept_errorsoffhttp, server, location是否拦截错误响应
proxy_pass_request_headersonhttp, server, location传递请求头
proxy_pass_request_bodyonhttp, server, location传递请求体
proxy_request_bufferingonhttp, server, location请求体缓冲

负载均衡指令

Upstream 配置

指令默认值作用域说明
upstream-http定义后端服务器组
server-upstream定义后端服务器地址
least_conn-upstream最少连接负载均衡
ip_hash-upstreamIP 哈希会话保持
hash-upstream自定义哈希负载均衡
least_time-upstream最短响应时间负载均衡
random-upstream随机负载均衡
keepalive-upstream保持连接数
zone-upstream共享内存区域

Upstream Server 参数

参数说明
weight=number服务器权重
max_fails=number最大失败次数(默认 1)
fail_timeout=time失败超时时间(默认 10s)
backup标记为备份服务器
down标记服务器离线
max_conns=number最大连接数限制

SSL/TLS 指令

指令默认值作用域说明
ssloffhttp, server启用 SSL
ssl_certificate-http, server证书文件路径
ssl_certificate_key-http, server私钥文件路径
ssl_protocolsTLSv1 TLSv1.1 TLSv1.2http, server支持的 SSL 协议版本
ssl_ciphersDEFAULThttp, server加密套件
ssl_prefer_server_ciphersoffhttp, server优先使用服务器加密套件
ssl_session_cacheNONEhttp, serverSSL 会话缓存
ssl_session_timeout1dhttp, serverSSL 会话超时
ssl_session_ticketsonhttp, serverSSL 会话票证
ssl_staplingoffhttp, serverOCSP 装订
ssl_stapling_verifyoffhttp, server验证 OCSP 响应
ssl_trusted_certificate-http, server可信 CA 证书
ssl_verify_clientoffhttp, server验证客户端证书
ssl_verify_depth1http, server客户端证书验证深度
ssl_dhparam-http, serverDiffie-Hellman 参数文件
ssl_early_dataoffhttp, serverTLS 1.3 0-RTT 数据

访问控制指令

IP 访问控制

指令默认值作用域说明
allow-http, server, location允许访问的 IP 或网段
deny-http, server, location拒绝访问的 IP 或网段

认证指令

指令默认值作用域说明
auth_basicoffhttp, server, location启用 HTTP 基本认证
auth_basic_user_file-http, server, location用户密码文件路径
auth_request-http, server, location子请求认证
auth_request_set-http, server, location设置子请求认证变量

连接和请求限制

指令默认值作用域说明
limit_conn_zone-http定义连接限制区域
limit_conn-http, server, location限制连接数
limit_conn_status503http, server, location连接超限状态码
limit_req_zone-http定义请求限制区域
limit_req-http, server, location限制请求速率
limit_req_status503http, server, location请求超限状态码
limit_req_dry_runoffhttp, server, location限流测试模式

请求处理指令

请求体控制

指令默认值作用域说明
client_max_body_size1mhttp, server, location最大请求体大小
client_body_buffer_size8k/16khttp, server, location请求体缓冲区大小
client_body_timeout60shttp, server, location请求体读取超时
client_header_timeout60shttp, server, location请求头读取超时
client_body_temp_pathclient_body_temphttp, server请求体临时文件路径
client_body_in_file_onlyoffhttp, server, location请求体是否存入文件

重定向和重写

指令默认值作用域说明
return-server, location, if返回状态码或重定向
rewrite-server, location, ifURL 重写
rewrite_logoffhttp, server, location重写日志
error_page-http, server, location自定义错误页面
postpone_output1460http, server, location延迟输出大小

条件判断

指令默认值作用域说明
if-server, location条件判断
set-server, location, if设置变量值
break-server, location, if停止重写处理

变量和映射指令

变量定义

指令默认值作用域说明
set-server, location, if定义变量
map-http创建变量映射
geo-http基于 IP 定义变量
geoip_country-httpGeoIP 国家数据库
geoip_city-httpGeoIP 城市数据库

常用内置变量

变量说明
$remote_addr客户端 IP 地址
$remote_user客户端用户名(认证时)
$request_uri完整的请求 URI(带参数)
$uri当前请求 URI(不含参数)
$request_method请求方法(GET/POST 等)
$http_user_agent客户端 User-Agent
$http_referer来源页面
$http_host请求 Host 头
$scheme请求协议(http/https)
$server_port服务器端口
$server_name服务器名称
$host请求主机名
$request_time请求处理时间
$status响应状态码
$body_bytes_sent发送的字节数
$bytes_sent发送的总字节数
$upstream_addr后端服务器地址
$upstream_status后端响应状态码
$upstream_response_time后端响应时间
$document_root当前请求的根目录
$request_filename当前请求的文件路径
$arg_name请求参数 name 的值
$cookie_nameCookie 中 name 的值

缓存指令

浏览器缓存

指令默认值作用域说明
expiresoffhttp, server, location设置浏览器缓存过期时间
add_header-http, server, location添加 HTTP 响应头
etagonhttp, server, location启用 ETag
last_modified-http, server, location设置 Last-Modified 头

文件缓存

指令默认值作用域说明
open_file_cacheoffhttp, server, location文件描述符缓存
open_file_cache_valid60shttp, server, location缓存检查间隔
open_file_cache_min_uses1http, server, location最小使用次数
open_file_cache_errorsoffhttp, server, location缓存错误文件

日志指令

指令默认值作用域说明
access_loglogs/access.loghttp, server, location访问日志路径
log_formatcombinedhttp定义日志格式
log_not_foundonhttp, server, location是否记录 404 日志
log_subrequestoffhttp, server, location是否记录子请求日志
error_loglogs/error.logmain, http, server, location错误日志路径和级别
常用日志格式变量:
$remote_addr - 客户端 IP | $time_local - 时间 | $request - 请求行 | $status - 状态码 | $body_bytes_sent - 发送字节数 | $http_referer - 来源 | $http_user_agent - User-Agent

Mirror 镜像指令

指令默认值作用域说明
mirrorofflocation启用请求镜像
mirror_request_bodyonlocation是否镜像请求体
使用说明: Mirror 功能用于将请求复制到另一个服务器,常用于生产流量复制到测试环境。镜像请求的响应会被丢弃。

FastCGI 指令

指令默认值作用域说明
fastcgi_pass-locationFastCGI 服务器地址
fastcgi_param-http, server, location设置 FastCGI 参数
fastcgi_index-http, server, location默认索引文件
fastcgi_connect_timeout60shttp, server, location连接超时
fastcgi_send_timeout60shttp, server, location发送超时
fastcgi_read_timeout60shttp, server, location读取超时
fastcgi_bufferingonhttp, server, location启用缓冲
fastcgi_buffers8 4k/8khttp, server, location缓冲区
fastcgi_buffer_size4k/8khttp, server, location响应头缓冲区
fastcgi_cacheoffhttp, server, location启用缓存
fastcgi_cache_path-http缓存路径

gRPC 指令

指令默认值作用域说明
grpc_pass-locationgRPC 服务器地址
grpc_set_header-http, server, location设置 gRPC 请求头
grpc_connect_timeout60shttp, server, location连接超时
grpc_read_timeout60shttp, server, location读取超时
grpc_send_timeout60shttp, server, location发送超时
grpc_bufferingonhttp, server, location启用缓冲
grpc_ssl_name-http, server, locationSSL 名称

其他常用指令

内部重定向

指令默认值作用域说明
internal-location标记为内部请求
include-任意包含其他配置文件

连接保持

指令默认值作用域说明
lingering_closeonhttp, server, location延迟关闭连接
lingering_time30shttp, server, location延迟关闭时间
lingering_timeout5shttp, server, location延迟关闭超时

其他配置

指令默认值作用域说明
server_tokensonhttp, server是否显示 Nginx 版本
types_hash_max_size1024http, server, locationMIME 类型哈希表大小
server_names_hash_bucket_size32/64/128http服务器名哈希桶大小
limit_rate0http, server, location限制响应速率
limit_rate_after0http, server, location开始限速的字节数

常用配置示例

静态文件服务配置

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.html;

    # 启用压缩
    gzip on;
    gzip_types text/plain text/css application/json;

    # 浏览器缓存
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location / {
        try_files $uri $uri/ =404;
    }
}

反向代理配置

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }
}

负载均衡配置

upstream backend {
    least_conn;
    server 192.168.1.1:8080 weight=3;
    server 192.168.1.2:8080;
    server 192.168.1.3:8080 backup;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend;
    }
}

HTTPS 配置

server {
    listen 443 ssl http2;
    server_name secure.example.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    location / {
        proxy_pass http://backend;
    }
}

🆕 近年新增指令(2020-2026)

以下是 Nginx 从 2020 年到 2026 年版本中新增的真实有效指令

版本说明: Nginx 分为稳定版(如 1.18.x、1.20.x、1.22.x、1.24.x、1.26.x)和主线版(如 1.19.x-1.21.x、1.23.x-1.25.x、1.27.x-1.29.x)。新特性通常在主线版中引入。

2025 年新增指令(1.27.x - 1.29.x)

指令版本作用域说明
ssl_ech_file1.29.4http, serverEncrypted ClientHello (ECH) TLS 扩展支持
add_header_inherit1.29.3http, server, location继承并添加响应头
add_trailer_inherit1.29.3http, server, location继承并添加尾部头
ssl_certificate_compression1.29.1http, serverSSL 证书压缩
early_hints1.29.0http, server, location支持来自代理和 gRPC 后端的 103 响应
ssl_object_cache_inheritable1.27.4httpSSL 对象缓存可继承
ssl_certificate_cache1.27.4httpSSL 证书缓存
proxy_ssl_certificate_cache1.27.4http代理 SSL 证书缓存
grpc_ssl_certificate_cache1.27.4httpgRPC SSL 证书缓存
uwsgi_ssl_certificate_cache1.27.4httpuWSGI SSL 证书缓存
keepalive_min_timeout1.27.4http, server最小保活超时时间
resolver (upstream 块)1.27.3upstream上游服务器 DNS 解析器配置
resolver_timeout (upstream 块)1.27.3upstream上游 DNS 解析超时
server ... resolve1.27.3upstream动态解析上游服务器地址
proxy_pass_trailers1.27.2http, server, location传递 HTTP 尾部头

2024 年新增指令(1.25.x - 1.27.x)

指令版本作用域说明
proxy_limit_rate (支持变量)1.27.0http, server, location代理速率限制支持变量
fastcgi_limit_rate (支持变量)1.27.0http, server, locationFastCGI 速率限制支持变量
scgi_limit_rate (支持变量)1.27.0http, server, locationSCGI 速率限制支持变量
uwsgi_limit_rate (支持变量)1.27.0http, server, locationuWSGI 速率限制支持变量
http21.25.1server按服务器启用 HTTP/2(替代 listen 的 http2 参数)
🌐 HTTP/3 支持: Nginx 1.25.0 开始提供实验性 HTTP/3 支持,使用 listen ... quic 参数启用。

2023 年新增指令(1.23.x - 1.25.x)

指令版本作用域说明
$proxy_protocol_tlv_...1.23.2-PROXY 协议 TLV 变量
resolver ... ipv4=off1.23.1http, server禁用 IPv4 地址查找

2022 年新增指令(1.21.x - 1.23.x)

指令版本作用域说明
$ssl_curve1.21.5-SSL 曲线变量
proxy_half_close1.21.4streamStream 代理半关闭支持
ssl_alpn1.21.4streamStream ALPN 协议设置
$ssl_alpn_protocol1.21.4-SSL ALPN 协议变量
mp4_start_key_frame1.21.4locationMP4 从关键帧开始
proxy_ssl_certificate (支持变量)1.21.0http, server, location代理 SSL 证书支持变量
grpc_ssl_certificate (支持变量)1.21.0http, server, locationgRPC SSL 证书支持变量
uwsgi_ssl_certificate (支持变量)1.21.0http, server, locationuWSGI SSL 证书支持变量
max_errors1.21.0mail邮件代理最大错误数
listen ... fastopen1.21.0streamTCP Fast Open 支持

2021 年新增指令(1.19.x - 1.21.x)

指令版本作用域说明
keepalive_time1.19.10http, server保活连接最大使用时间
$connection_time1.19.10-连接时间变量
proxy_cookie_flags (支持变量)1.19.8http, server, location代理 Cookie 标志支持变量
-e1.19.5命令行启动时指定错误日志文件

2020 年新增指令(1.17.x - 1.19.x)

指令版本作用域说明
ssl_conf_command1.19.4http, serverSSL 配置命令(OpenSSL 配置)
proxy_ssl_conf_command1.19.4http, server, location代理 SSL 配置命令
grpc_ssl_conf_command1.19.4http, server, locationgRPC SSL 配置命令
uwsgi_ssl_conf_command1.19.4http, server, locationuWSGI SSL 配置命令
ssl_reject_handshake1.19.4http, server拒绝 SSL 握手
proxy_smtp_auth1.19.4mail邮件代理 SMTP 认证
proxy_cookie_flags1.19.3http, server, location代理 Cookie 标志
userid_flags1.19.3http, server, location用户 ID 标志
auth_delay1.17.10http, server, location认证延迟(防止暴力破解)
grpc_pass (支持变量)1.17.8locationgRPC 代理地址支持变量
📈 发展趋势:
  • HTTP/3 支持 - 1.25.0 开始实验性支持 QUIC 和 HTTP/3
  • SSL/TLS 增强 - ECH 加密、证书压缩、OCSP、硬件令牌支持
  • 动态上游解析 - upstream 块支持 DNS 动态解析
  • 变量支持扩展 - 更多指令支持变量,配置更灵活
  • 性能优化 - SSL 缓存、连接处理、HTTP/2 优化

新增变量汇总

变量版本说明
$request_port1.29.3请求端口
$is_request_port1.29.3请求端口判断
$ssl_sigalg1.29.3SSL 签名算法
$ssl_client_sigalg1.29.3客户端 SSL 签名算法
$ssl_curve1.21.5SSL 曲线
$ssl_alpn_protocol1.21.4SSL ALPN 协议
$connection_time1.19.10连接时间
$proxy_protocol_tlv_...1.23.2PROXY 协议 TLV 变量