📋 指令作用域层级
作用域说明: Nginx 指令的作用域决定了它们可以在哪个配置块中使用。层级结构如下:
- main - 全局配置,影响 Nginx 整体行为
- events - 事件处理配置
- http - HTTP 服务配置
- server - 虚拟主机配置
- location - 路由匹配配置
核心配置指令
Main 上下文指令
| 指令 | 默认值 | 说明 |
|---|---|---|
worker_processes | 1 | Worker 进程数量,通常设为 CPU 核心数或 auto |
error_log | logs/error.log | 错误日志路径和级别(debug|info|notice|warn|error|crit|alert|emerg) |
pid | logs/nginx.pid | 主进程 PID 文件路径 |
daemon | on | 是否以守护进程运行 |
user | root | 运行 Nginx 的用户和用户组 |
worker_rlimit_nofile | - | Worker 进程最大打开文件数 |
include | - | 包含其他配置文件 |
Events 上下文指令
| 指令 | 默认值 | 说明 |
|---|---|---|
worker_connections | 1024 | 每个 Worker 的最大连接数 |
use | - | 连接处理方法(epoll|kqueue|select|poll 等) |
multi_accept | off | 是否一次接受多个连接 |
accept_mutex | on | 是否使用互斥锁接受连接 |
HTTP 核心指令
基础服务指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
server | - | http | 定义虚拟服务器 |
listen | 80 | server | 监听端口和地址 |
server_name | "" | server | 虚拟主机名 |
root | html | http, server, location | 网站根目录 |
index | index.html | http, server, location | 默认首页文件 |
location | - | server, location | 匹配请求 URI |
alias | - | location | 路径别名(仅用于 location) |
try_files | - | server, location | 按顺序检查文件是否存在 |
性能优化指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
sendfile | off | http, server, location | 启用零拷贝传输 |
tcp_nopush | off | http, server, location | 优化 TCP 包发送 |
tcp_nodelay | off | http, server, location | 禁用 Nagle 算法 |
keepalive_timeout | 75s | http, server | 长连接超时时间 |
keepalive_requests | 100 | http, server | 长连接最大请求数 |
send_timeout | 60s | http, server, location | 响应超时时间 |
reset_timedout_connection | off | http | 重置超时的连接 |
Gzip 压缩指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
gzip | off | http, server, location | 启用 gzip 压缩 |
gzip_comp_level | 1 | http, server, location | 压缩级别 (1-9) |
gzip_types | text/html | http, server, location | 压缩的 MIME 类型 |
gzip_min_length | 20 | http, server, location | 最小压缩长度 |
gzip_max_length | unlimited | http, server, location | 最大压缩长度 |
gzip_buffers | 32 4k/16 8k | http, server, location | 压缩缓冲区 |
gzip_http_version | 1.1 | http, server, location | HTTP 版本要求 |
gzip_proxied | off | http, server, location | 代理响应压缩条件 |
gzip_vary | off | http, server, location | 添加 Vary: Accept-Encoding |
gzip_disable | - | http, server, location | 禁用压缩的条件 |
代理相关指令
基础代理指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
proxy_pass | - | location, if | 代理服务器地址 |
proxy_set_header | - | http, server, location | 设置代理请求头 |
proxy_connect_timeout | 60s | http, server, location | 连接超时时间 |
proxy_send_timeout | 60s | http, server, location | 发送超时时间 |
proxy_read_timeout | 60s | http, server, location | 读取超时时间 |
proxy_buffering | on | http, server, location | 启用代理缓冲 |
proxy_buffer_size | 4k/8k | http, server, location | 代理响应头缓冲区 |
proxy_buffers | 8 4k/8k | http, server, location | 代理响应缓冲区 |
proxy_busy_buffers_size | 8k/16k | http, server, location | 繁忙时缓冲区大小 |
proxy_max_temp_file_size | 1024m | http, server, location | 临时文件最大大小 |
proxy_redirect | default | http, server, location | 修改代理响应头 |
proxy_http_version | 1.0 | http, server, location | 代理 HTTP 版本 |
代理缓存指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
proxy_cache_path | - | http | 定义缓存路径和参数 |
proxy_cache | off | http, server, location | 启用代理缓存 |
proxy_cache_valid | - | http, server, location | 缓存有效时间 |
proxy_cache_key | $scheme$proxy_host$request_uri | http, server, location | 缓存键 |
proxy_cache_min_uses | 1 | http, server, location | 最小使用次数后缓存 |
proxy_cache_use_stale | off | http, server, location | 使用过期缓存的条件 |
proxy_cache_methods | GET HEAD | http, server, location | 缓存的 HTTP 方法 |
proxy_no_cache | - | http, server, location | 不缓存的条件 |
proxy_cache_bypass | - | http, server, location | 绕过缓存的条件 |
代理其他指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
proxy_next_upstream | error timeout | http, server, location | 切换到后端服务器的条件 |
proxy_next_upstream_tries | unlimited | http, server, location | 最大尝试次数 |
proxy_next_upstream_timeout | unlimited | http, server, location | 尝试超时时间 |
proxy_ignore_client_abort | off | http, server, location | 忽略客户端中断 |
proxy_intercept_errors | off | http, server, location | 是否拦截错误响应 |
proxy_pass_request_headers | on | http, server, location | 传递请求头 |
proxy_pass_request_body | on | http, server, location | 传递请求体 |
proxy_request_buffering | on | http, server, location | 请求体缓冲 |
负载均衡指令
Upstream 配置
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
upstream | - | http | 定义后端服务器组 |
server | - | upstream | 定义后端服务器地址 |
least_conn | - | upstream | 最少连接负载均衡 |
ip_hash | - | upstream | IP 哈希会话保持 |
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 指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
ssl | off | http, server | 启用 SSL |
ssl_certificate | - | http, server | 证书文件路径 |
ssl_certificate_key | - | http, server | 私钥文件路径 |
ssl_protocols | TLSv1 TLSv1.1 TLSv1.2 | http, server | 支持的 SSL 协议版本 |
ssl_ciphers | DEFAULT | http, server | 加密套件 |
ssl_prefer_server_ciphers | off | http, server | 优先使用服务器加密套件 |
ssl_session_cache | NONE | http, server | SSL 会话缓存 |
ssl_session_timeout | 1d | http, server | SSL 会话超时 |
ssl_session_tickets | on | http, server | SSL 会话票证 |
ssl_stapling | off | http, server | OCSP 装订 |
ssl_stapling_verify | off | http, server | 验证 OCSP 响应 |
ssl_trusted_certificate | - | http, server | 可信 CA 证书 |
ssl_verify_client | off | http, server | 验证客户端证书 |
ssl_verify_depth | 1 | http, server | 客户端证书验证深度 |
ssl_dhparam | - | http, server | Diffie-Hellman 参数文件 |
ssl_early_data | off | http, server | TLS 1.3 0-RTT 数据 |
访问控制指令
IP 访问控制
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
allow | - | http, server, location | 允许访问的 IP 或网段 |
deny | - | http, server, location | 拒绝访问的 IP 或网段 |
认证指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
auth_basic | off | http, 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_status | 503 | http, server, location | 连接超限状态码 |
limit_req_zone | - | http | 定义请求限制区域 |
limit_req | - | http, server, location | 限制请求速率 |
limit_req_status | 503 | http, server, location | 请求超限状态码 |
limit_req_dry_run | off | http, server, location | 限流测试模式 |
请求处理指令
请求体控制
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
client_max_body_size | 1m | http, server, location | 最大请求体大小 |
client_body_buffer_size | 8k/16k | http, server, location | 请求体缓冲区大小 |
client_body_timeout | 60s | http, server, location | 请求体读取超时 |
client_header_timeout | 60s | http, server, location | 请求头读取超时 |
client_body_temp_path | client_body_temp | http, server | 请求体临时文件路径 |
client_body_in_file_only | off | http, server, location | 请求体是否存入文件 |
重定向和重写
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
return | - | server, location, if | 返回状态码或重定向 |
rewrite | - | server, location, if | URL 重写 |
rewrite_log | off | http, server, location | 重写日志 |
error_page | - | http, server, location | 自定义错误页面 |
postpone_output | 1460 | http, server, location | 延迟输出大小 |
条件判断
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
if | - | server, location | 条件判断 |
set | - | server, location, if | 设置变量值 |
break | - | server, location, if | 停止重写处理 |
变量和映射指令
变量定义
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
set | - | server, location, if | 定义变量 |
map | - | http | 创建变量映射 |
geo | - | http | 基于 IP 定义变量 |
geoip_country | - | http | GeoIP 国家数据库 |
geoip_city | - | http | GeoIP 城市数据库 |
常用内置变量
| 变量 | 说明 |
|---|---|
$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_name | Cookie 中 name 的值 |
缓存指令
浏览器缓存
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
expires | off | http, server, location | 设置浏览器缓存过期时间 |
add_header | - | http, server, location | 添加 HTTP 响应头 |
etag | on | http, server, location | 启用 ETag |
last_modified | - | http, server, location | 设置 Last-Modified 头 |
文件缓存
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
open_file_cache | off | http, server, location | 文件描述符缓存 |
open_file_cache_valid | 60s | http, server, location | 缓存检查间隔 |
open_file_cache_min_uses | 1 | http, server, location | 最小使用次数 |
open_file_cache_errors | off | http, server, location | 缓存错误文件 |
日志指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
access_log | logs/access.log | http, server, location | 访问日志路径 |
log_format | combined | http | 定义日志格式 |
log_not_found | on | http, server, location | 是否记录 404 日志 |
log_subrequest | off | http, server, location | 是否记录子请求日志 |
error_log | logs/error.log | main, http, server, location | 错误日志路径和级别 |
常用日志格式变量:
$remote_addr - 客户端 IP |
$time_local - 时间 |
$request - 请求行 |
$status - 状态码 |
$body_bytes_sent - 发送字节数 |
$http_referer - 来源 |
$http_user_agent - User-Agent
Mirror 镜像指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
mirror | off | location | 启用请求镜像 |
mirror_request_body | on | location | 是否镜像请求体 |
使用说明: Mirror 功能用于将请求复制到另一个服务器,常用于生产流量复制到测试环境。镜像请求的响应会被丢弃。
FastCGI 指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
fastcgi_pass | - | location | FastCGI 服务器地址 |
fastcgi_param | - | http, server, location | 设置 FastCGI 参数 |
fastcgi_index | - | http, server, location | 默认索引文件 |
fastcgi_connect_timeout | 60s | http, server, location | 连接超时 |
fastcgi_send_timeout | 60s | http, server, location | 发送超时 |
fastcgi_read_timeout | 60s | http, server, location | 读取超时 |
fastcgi_buffering | on | http, server, location | 启用缓冲 |
fastcgi_buffers | 8 4k/8k | http, server, location | 缓冲区 |
fastcgi_buffer_size | 4k/8k | http, server, location | 响应头缓冲区 |
fastcgi_cache | off | http, server, location | 启用缓存 |
fastcgi_cache_path | - | http | 缓存路径 |
gRPC 指令
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
grpc_pass | - | location | gRPC 服务器地址 |
grpc_set_header | - | http, server, location | 设置 gRPC 请求头 |
grpc_connect_timeout | 60s | http, server, location | 连接超时 |
grpc_read_timeout | 60s | http, server, location | 读取超时 |
grpc_send_timeout | 60s | http, server, location | 发送超时 |
grpc_buffering | on | http, server, location | 启用缓冲 |
grpc_ssl_name | - | http, server, location | SSL 名称 |
其他常用指令
内部重定向
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
internal | - | location | 标记为内部请求 |
include | - | 任意 | 包含其他配置文件 |
连接保持
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
lingering_close | on | http, server, location | 延迟关闭连接 |
lingering_time | 30s | http, server, location | 延迟关闭时间 |
lingering_timeout | 5s | http, server, location | 延迟关闭超时 |
其他配置
| 指令 | 默认值 | 作用域 | 说明 |
|---|---|---|---|
server_tokens | on | http, server | 是否显示 Nginx 版本 |
types_hash_max_size | 1024 | http, server, location | MIME 类型哈希表大小 |
server_names_hash_bucket_size | 32/64/128 | http | 服务器名哈希桶大小 |
limit_rate | 0 | http, server, location | 限制响应速率 |
limit_rate_after | 0 | http, 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_file | 1.29.4 | http, server | Encrypted ClientHello (ECH) TLS 扩展支持 |
add_header_inherit | 1.29.3 | http, server, location | 继承并添加响应头 |
add_trailer_inherit | 1.29.3 | http, server, location | 继承并添加尾部头 |
ssl_certificate_compression | 1.29.1 | http, server | SSL 证书压缩 |
early_hints | 1.29.0 | http, server, location | 支持来自代理和 gRPC 后端的 103 响应 |
ssl_object_cache_inheritable | 1.27.4 | http | SSL 对象缓存可继承 |
ssl_certificate_cache | 1.27.4 | http | SSL 证书缓存 |
proxy_ssl_certificate_cache | 1.27.4 | http | 代理 SSL 证书缓存 |
grpc_ssl_certificate_cache | 1.27.4 | http | gRPC SSL 证书缓存 |
uwsgi_ssl_certificate_cache | 1.27.4 | http | uWSGI SSL 证书缓存 |
keepalive_min_timeout | 1.27.4 | http, server | 最小保活超时时间 |
resolver (upstream 块) | 1.27.3 | upstream | 上游服务器 DNS 解析器配置 |
resolver_timeout (upstream 块) | 1.27.3 | upstream | 上游 DNS 解析超时 |
server ... resolve | 1.27.3 | upstream | 动态解析上游服务器地址 |
proxy_pass_trailers | 1.27.2 | http, server, location | 传递 HTTP 尾部头 |
2024 年新增指令(1.25.x - 1.27.x)
| 指令 | 版本 | 作用域 | 说明 |
|---|---|---|---|
proxy_limit_rate (支持变量) | 1.27.0 | http, server, location | 代理速率限制支持变量 |
fastcgi_limit_rate (支持变量) | 1.27.0 | http, server, location | FastCGI 速率限制支持变量 |
scgi_limit_rate (支持变量) | 1.27.0 | http, server, location | SCGI 速率限制支持变量 |
uwsgi_limit_rate (支持变量) | 1.27.0 | http, server, location | uWSGI 速率限制支持变量 |
http2 | 1.25.1 | server | 按服务器启用 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=off | 1.23.1 | http, server | 禁用 IPv4 地址查找 |
2022 年新增指令(1.21.x - 1.23.x)
| 指令 | 版本 | 作用域 | 说明 |
|---|---|---|---|
$ssl_curve | 1.21.5 | - | SSL 曲线变量 |
proxy_half_close | 1.21.4 | stream | Stream 代理半关闭支持 |
ssl_alpn | 1.21.4 | stream | Stream ALPN 协议设置 |
$ssl_alpn_protocol | 1.21.4 | - | SSL ALPN 协议变量 |
mp4_start_key_frame | 1.21.4 | location | MP4 从关键帧开始 |
proxy_ssl_certificate (支持变量) | 1.21.0 | http, server, location | 代理 SSL 证书支持变量 |
grpc_ssl_certificate (支持变量) | 1.21.0 | http, server, location | gRPC SSL 证书支持变量 |
uwsgi_ssl_certificate (支持变量) | 1.21.0 | http, server, location | uWSGI SSL 证书支持变量 |
max_errors | 1.21.0 | 邮件代理最大错误数 | |
listen ... fastopen | 1.21.0 | stream | TCP Fast Open 支持 |
2021 年新增指令(1.19.x - 1.21.x)
| 指令 | 版本 | 作用域 | 说明 |
|---|---|---|---|
keepalive_time | 1.19.10 | http, server | 保活连接最大使用时间 |
$connection_time | 1.19.10 | - | 连接时间变量 |
proxy_cookie_flags (支持变量) | 1.19.8 | http, server, location | 代理 Cookie 标志支持变量 |
-e | 1.19.5 | 命令行 | 启动时指定错误日志文件 |
2020 年新增指令(1.17.x - 1.19.x)
| 指令 | 版本 | 作用域 | 说明 |
|---|---|---|---|
ssl_conf_command | 1.19.4 | http, server | SSL 配置命令(OpenSSL 配置) |
proxy_ssl_conf_command | 1.19.4 | http, server, location | 代理 SSL 配置命令 |
grpc_ssl_conf_command | 1.19.4 | http, server, location | gRPC SSL 配置命令 |
uwsgi_ssl_conf_command | 1.19.4 | http, server, location | uWSGI SSL 配置命令 |
ssl_reject_handshake | 1.19.4 | http, server | 拒绝 SSL 握手 |
proxy_smtp_auth | 1.19.4 | 邮件代理 SMTP 认证 | |
proxy_cookie_flags | 1.19.3 | http, server, location | 代理 Cookie 标志 |
userid_flags | 1.19.3 | http, server, location | 用户 ID 标志 |
auth_delay | 1.17.10 | http, server, location | 认证延迟(防止暴力破解) |
grpc_pass (支持变量) | 1.17.8 | location | gRPC 代理地址支持变量 |
📈 发展趋势:
- HTTP/3 支持 - 1.25.0 开始实验性支持 QUIC 和 HTTP/3
- SSL/TLS 增强 - ECH 加密、证书压缩、OCSP、硬件令牌支持
- 动态上游解析 - upstream 块支持 DNS 动态解析
- 变量支持扩展 - 更多指令支持变量,配置更灵活
- 性能优化 - SSL 缓存、连接处理、HTTP/2 优化
新增变量汇总
| 变量 | 版本 | 说明 |
|---|---|---|
$request_port | 1.29.3 | 请求端口 |
$is_request_port | 1.29.3 | 请求端口判断 |
$ssl_sigalg | 1.29.3 | SSL 签名算法 |
$ssl_client_sigalg | 1.29.3 | 客户端 SSL 签名算法 |
$ssl_curve | 1.21.5 | SSL 曲线 |
$ssl_alpn_protocol | 1.21.4 | SSL ALPN 协议 |
$connection_time | 1.19.10 | 连接时间 |
$proxy_protocol_tlv_... | 1.23.2 | PROXY 协议 TLV 变量 |