# Nginx 配置详解

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

- 作者：David（道雾轩）
- 最后更新：2026-08-03
- 原文：https://daiw.org/manual/nginx
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

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

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

## 版本基准

以 [nginx.org 官方文档](https://nginx.org/en/docs/)为准，快照于 **2026-07-30**：

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

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

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

## 文档怎么读

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

| 前缀 | 数量 | 作用域 |
| --- | --- | --- |
| `ngx_core_module` 等 | 4 | 主上下文与全局 |
| `ngx_http_*` | 80+ | HTTP 处理 |
| `ngx_stream_*` | 20+ | TCP/UDP 代理 |
| `ngx_mail_*` | 7 | 邮件代理 |

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

```text
语法:    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 代理、常见误配速查。

从 [配置文件语法](https://daiw.org/manual/nginx/config-syntax) 开始。

## 与站内其他专栏的关系

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

- [《HTTP/1.1 协议详解》](https://daiw.org/manual/http11)——字段语义、状态码、缓存与条件请求。
- [《HTTP/2 与 HTTP/3 协议详解》](https://daiw.org/manual/http2-3)——`listen ... http2` / `quic` 背后的协议差异。

## 本专栏篇目

- [Nginx 配置详解](https://daiw.org/manual/nginx.md): 以官方文档为准，逐指令讲清语法、取值、上下文、继承规则与常见误配。

### 第 0 部分 · 基础

- [配置文件语法](https://daiw.org/manual/nginx/config-syntax.md): 简单指令与块指令、上下文的定义、注释、计量单位与 include 的展开时机。
- [指令、上下文与继承](https://daiw.org/manual/nginx/contexts.md): 值继承与数组继承的本质区别、add_header 覆盖陷阱，以及 1.29.3 起的 add_header_inherit。
- [nginx 如何处理请求](https://daiw.org/manual/nginx/request-processing.md): 虚拟服务器选择的两步、default_server 的真实含义、server_name 匹配的四级优先级。

### 第 1 部分 · 核心指令

- [核心模块指令](https://daiw.org/manual/nginx/core-module.md): worker 进程与连接、events 块、error_log 八级、user/pid，以及连接数的真实上限。
- [server 与 listen](https://daiw.org/manual/nginx/server-listen.md): listen 的三种形式与全部参数、http2 参数的废弃、reuseport 与 backlog，以及 server 级常用指令。
- [location 匹配规则](https://daiw.org/manual/nginx/location.md): 五种修饰符、「记住最长前缀再试正则」的两阶段算法、^~ 与 = 的短路，以及嵌套 location。
- [root、alias 与 try_files](https://daiw.org/manual/nginx/root-alias.md): 拼接 vs 替换的本质差异、alias 的尾斜杠陷阱、try_files 的三种回退目标与无限循环。
- [变量](https://daiw.org/manual/nginx/variables.md): $uri 与 $request_uri 的关键差异、$host 的三级回退、动态变量族与求值时机。

### 第 2 部分 · 代理与上游

- [proxy 反向代理](https://daiw.org/manual/nginx/proxy.md): proxy_pass 带不带 URI 的本质区别、默认 Host 的坑、缓冲与超时、proxy_next_upstream 的重试语义。
- [upstream 负载均衡](https://daiw.org/manual/nginx/upstream.md): 五种调度算法、server 参数全解、被动健康检查的真实语义与 keepalive 的默认值变更。
- [FastCGI、uWSGI 与 gRPC](https://daiw.org/manual/nginx/fastcgi-grpc.md): fastcgi_param 的必填项、PATH_INFO 与安全陷阱、uwsgi/scgi 对照与 grpc_pass。

### 第 3 部分 · TLS 与协议

- [SSL/TLS 配置](https://daiw.org/manual/nginx/ssl.md): 证书链、协议与套件的默认值、会话复用三件套、OCSP stapling 与 0-RTT 重放风险。
- [HTTP/2 与 HTTP/3](https://daiw.org/manual/nginx/http2-http3.md): http2 指令取代 listen 参数、QUIC 的双 listen 与 Alt-Svc、quic_gso 与 0-RTT 的前置条件。

### 第 4 部分 · 性能

- [代理缓存](https://daiw.org/manual/nginx/caching.md): proxy_cache_path 全参数、缓存键的默认值陷阱、优先级链、锁与后台更新、stale 兜底。
- [压缩与静态文件](https://daiw.org/manual/nginx/static-perf.md): gzip 全部默认值的陷阱、gzip_vary 与代理缓存、sendfile/tcp_nopush 组合与 open_file_cache。

### 第 5 部分 · 访问控制

- [访问控制与限流](https://daiw.org/manual/nginx/access-limits.md): allow/deny 的顺序语义、auth_basic 与 auth_request、漏桶限流的 burst/nodelay 与连接数限制。

### 第 6 部分 · 日志与重写

- [日志](https://daiw.org/manual/nginx/logging.md): log_format 的可用变量、缓冲与条件日志、access_log 的数组继承，以及一份可排障的日志格式。
- [rewrite、return 与 if](https://daiw.org/manual/nginx/rewrite.md): 四个 flag 的精确差异、rewrite 阶段的执行时机、「if is evil」的真实含义与安全替代。
- [map、geo 与 split_clients](https://daiw.org/manual/nginx/map-geo.md): map 的匹配优先级与惰性求值、geo 的 CIDR 查表、split_clients 做灰度发布。

### 第 7 部分 · stream 与收尾

- [stream：TCP/UDP 代理](https://daiw.org/manual/nginx/stream.md): 与 http 平行的另一套世界、UDP 的会话语义、SNI 分流与 PROXY 协议。
- [常见误配速查](https://daiw.org/manual/nginx/recap.md): 二十条高频错误、需要改的默认值清单、已过期的旧最佳实践，以及调试手法。