Nginx 配置详解

以官方文档为准，逐指令讲清语法、取值、上下文、继承规则与常见误配。

本专栏逐指令解析 nginx 配置：每条指令的语法、默认值、可用上下文、取值含义，以及配错时会发生什么。

不讲「nginx 是什么」，不讲安装教程，只讲配置文件里的每一行到底是什么意思。

版本基准

以 nginx.org 官方文档为准，快照于 2026-07-30：

分支	版本	说明
stable	1.30.4	生产推荐。第二段是偶数，只收高危修复，不加新特性
mainline	1.31.3	活跃开发分支，新特性先进这里。第二段是奇数

nginx 的版本号规则与多数项目相反：偶数是稳定分支，奇数是主线。1.30.x 稳定、1.31.x 主线。官方实际推荐多数场景用 mainline——它包含全部修复且质量长期稳定，stable 只是变更更保守。

本专栏标注指令时会注明「x.y.z 起可用」，遇到较新特性会提示所需版本。

nginx 官方文档按模块组织，每个模块一页，页内列出该模块的全部指令。三类模块：

每条指令在文档里都有固定的三行元信息，本专栏沿用这个格式：

语法:    directive_name value [value...];
默认:    directive_name default;
上下文:  http, server, location

「上下文」是最容易被忽略却最重要的一行——它决定这条指令能写在哪，写错位置轻则不生效，重则 nginx 起不来。

第 0 部分 · 基础——配置语法、指令与上下文、继承规则、请求处理流程。必读，后面所有章节都建立在这四篇之上。
第 1 部分 · 核心指令——ngx_core_module、server 与 listen、location 匹配、root/alias/try_files、变量。
第 2 部分 · 代理与上游——proxy、upstream 负载均衡、FastCGI/uWSGI/gRPC。
第 3 部分 · TLS 与协议——ssl 模块、HTTP/2 与 HTTP/3。
第 4 部分 · 性能——缓存、压缩、静态文件与连接调优。
第 5 部分 · 访问控制——access/auth、限流限速。
第 6 部分 · 日志与重写——log_format、rewrite/return/if、map/geo。
第 7 部分 · stream 与收尾——TCP/UDP 代理、常见误配速查。

配置里大量出现 HTTP 概念（Host、ETag、Cache-Control、Range、Connection）。不清楚这些字段的精确语义时，回查：