# Nginx中常用的模块整理|博客系列

> 本文系统整理了Nginx常用模块及其配置方法，涵盖性能优化、事件驱动、连接管理等核心内容，帮助开发者高效配置和优化Nginx服务器，提升网站性能与稳定性。

- 原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/nginx/-Nginx%E4%B8%AD%E5%B8%B8%E7%94%A8%E7%9A%84%E6%A8%A1%E5%9D%97%E6%95%B4%E7%90%86
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2025.10.25
- 可见范围：免费部分

---

> Nginx 配置文件在线生成: https://nginxconfig.io/

## 第一部分 基础模块

## 一、性能相关配置

```
worker_processes number | auto；
```

> `worker`进程的数量；通常应该为当前主机的`cpu`的物理核心数。多于`8`个的话建议写`8`，超过`8`个性能不会提升，稳定性降低

```bash
worker_cpu_affinity auto [cpumask] #将work进程绑定在固定cpu上提高缓存命中率 
# 例：
worker_cpu_affinity 0001 0010 0100 1000;
worker_cpu_affinity 0101 1010;
```

```bash
worker_priority number
# 指定worker进程的nice值，设定worker进程优先级： [-20,20]
```

```bash
worker_rlimit_nofile number
worker # 进程所能够打开的文件数量上限,默认较小，生产中需要调大如65535。系统资源通过配置修改/etc/security/limits.conf 例：root soft nofile 65535，或命令修改ulimit -n，修改后需重启服务或系统生效。
```

## 二、时间驱动events相关的配置

- 每个`worker`进程所能够打开的最大并发连接数数量，如`10240`
- 总最大并发数： `worker_processes * worker_connections`

```bash
worker_connections number
```

- 指明并发连接请求的处理方法,默认自动选择最优方法不用调整

```bash
use method
# 如：use epoll;
```

- `on`指由各个`worker`轮流处理新请求
- `Off`指每个新请求的到达都会通知(唤醒)所有的`worker`进程，但只有一个进程可获得连接，造成“惊群”，影响性能，默认`on`

```bash
# 处理新的连接请求的方法
accept_mutex on | off # 互斥；
```

## 三、http核心模块相关配置ngx_http_core_module

### 3.1web服务模板

```bash
server { ... }
# 配置一个虚拟主机
server {
    listen address[:PORT]|PORT;
    server_name SERVER_NAME; # 指令指向不同的主机名
    root /PATH/TO/DOCUMENT_ROOT;
} 
```

### 3.2套接字相关配置

```bash
listen address[:port] [default_server] [ssl] [http2 | spdy] [backlog=number] [rcvbuf=size] [sndbuf=size]
```
- `default_server` 设定为默认虚拟主机
- `ssl` 限制仅能够通过`ssl`连接提供服务
- `backlog=number` 超过并发连接数后，新请求进入后援队列的长度
- `rcvbuf=size` 接收缓冲区大小
- `sndbuf=size` 发送缓冲区大小

### 3.3 server_name

- 支持*通配任意长度的任意字符

```
server_name *.magedu.com www.magedu.*
```

- 支持`~`起始的字符做正则表达式模式匹配，性能原因慎用

```
server_name ~^www\d+\.magedu\.com$   #\d 表示 [0-9]
```

**匹配优先级机制从高到低：**

- 首先是字符串精确匹配 如： `www.magedu.com`
- 左侧`*`通配符 如： `*.magedu.com`
- 右侧`*`通配符 如： `www.magedu.*`
- 正则表达式 如： `~^.*\.magedu\.com$`
- `default_server`

### 3.4 延迟发送选项

```
tcp_nodelay on | off;
tcp_nopush  on | off;
```

- 在`keep alived`模式下的连接是否启用`TCP_NODELAY`选项。
- `tcp_nopush`必须在`sendfile`为`on`时才有效，当为`off`时，延迟发送，合并多个请求后再发送
- 默认`On`时，不延迟发送
- 可用于： `http`, `server`, `location`

### 3.5 sendfile

```bash
sendfile on | off;
```

> 是否启用`sendfile`功能，在内核中封装报文直接发送。如用来进行下载等应用磁盘IO重负载应用可设置为`off`，以平衡磁盘与网络IO处理速度降低系统负载，如图片显示不正常把这个改为`off`。默认`Off`

### 3.6 隐藏版本信息

> 是否在响应报文的`Server`首部显示`nginx`版本

```bash
server_tokens on | off | build | string
```

### 3.7 location匹配

```bash
location [ = | ~ | ~* | ^~ ] uri { ... }
location @name { ... }
```

> 在一个`server`中`location`配置段可存在多个，用于实现从`uri`到文件系统的路径映射； `ngnix`会根据用户请求的`URI`来检查定义的所有`location`，并找出一个最佳匹配，而后应用其配置 

```bash
server {...
    server_name www.magedu.com;
    location /images/ {
        root /data/imgs/;
        }
}
http://www.magedu.com/images/logo.jpg
--> /data/imgs/images/logo.jpg 
```

- `=`：对`URI`做精确匹配； 
- `^~`：对`URI`的最左边部分做匹配检查，不区分字符大小写
- `~`：对`URI`做正则表达式模式匹配，区分字符大小写
- `~*`：对`URI`做正则表达式模式匹配，不区分字符大小写
不带符号：匹配起始于此`uri`的所有的`uri`
匹配优先级从高到低：
- `=`, `^~`, `～/～*`, 不带符号

**路径别名alias path**

示例：

```bash
# http://www.magedu.com/bbs/index.php

location /bbs/ {
    alias /web/forum/;
} # --> /web/forum/index.html
location /bbs/ {
    root /web/forum/;
}     # --> /web/forum/bbs/index.html    
```

**注意**：

> `location`中使用`root`指令和`alias`指令的意义不同    

- `root`，相当于追加在`root`目录后面  
- `alias`，相当于对`location`中的`url`进行替换

### 3.8 错误页面显示

```
error_page code ... [=[response]] uri;
```

**模块：**

```
ngx_http_core_module
```

- 定义错误页， 以指定的响应状态码进行响应
- 可用位置： `http`, `server`, `location`, `if in location`

```bash
error_page 404 /404.html
error_page 404 =200 /404.html  #防止404页面被劫持
```

### 3.9 长连接相关配置

```
keepalive_timeout timeout [header_timeout];
```

- 设定保持连接超时时长， `0`表示禁止长连接， 默认为`75s`

```
keepalive_requests number;
```

- 在一次长连接上所允许请求的资源的最大数量，默认为`100`

```
keepalive_disable none | browser ...
```

- 对哪种浏览器禁用长连接

```
send_timeout time;
```

- 向客户端发送响应报文的超时时长，此处是指两次写操作之间的间隔时长，而非
整个响应过程的传输时长

### 3.10 请求报文缓存

```
client_body_buffer_size size;
```

> 用于接收每个客户端请求报文的body部分的缓冲区大小；默认为`16k`；超出此大小时，其将被暂存到磁盘上的由`client_body_temp_path`指令所定义的位置

```
client_body_temp_path path [level1 [level2 [level3]]];
```

> 设定用于存储客户端请求报文的`body`部分的临时存储路径及子目录结构和数量 
目录名为`16`进制的数字；

```
client_body_temp_path /var/tmp/client_body 1 2 2
```

- `1`级目录占1位`16`进制，即`2^4=16个目录 `0-f`
- `2`级目录占2位`16`进制，即`2^8=256`个目录 `00-ff`
- `3`级目录占2位`16`进制， 即`2^8=256`个目录 `00--ff` 

### 3.11 对客户端进行限制相关配置

```
limit_rate rate;
```

> 限制响应给客户端的传输速率，单位是`bytes/second` 默认`0`表示无限制

```
limit_except method ... { ... }
```
> 仅用于`location`限制客户端使用除了指定的请求方法之外的其它方法 
`method:GET`, `HEAD`, `POST`, `PUT`, `DELETE`，`MKCOL`, `COPY`, `MOVE`, `OPTIONS`, `PROPFIND`,
`PROPPATCH`, `LOCK`, `UNLOCK`, `PATCH`

```bash
# 例：
limit_except GET {
    allow 192.168.1.0/24;
    deny all;
} 
```

> 除了`GET`和`HEAD` 之外其它方法仅允许`192.168.1.0/24`网段主机使用

## 四、访问控制模块ngx_http_access_module

> 实现基于`ip`的访问控制功能

```bash
allow address | CIDR | unix: | all;
deny address | CIDR | unix: | all;
http, server, location, limit_except
```

> 自上而下检查，一旦匹配，将生效，条件严格的置前

```bash
#示例：

location / {
    deny 192.168.1.1;
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    allow 2001:0db8::/32;
    deny all;
}
```

## 五、用户认证模块ngx_http_auth_basic_module

> 实现基于用户的访问控制，使用`basic`机制进行用户认证

```bash
auth_basic string | off;
auth_basic_user_file file;
location /admin/ {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.ngxpasswd;
}
```

**用户口令：**

- 明文文本：格式`name:password:comment`
- 加密文本：由`htpasswd`命令实现 `httpd-tools`所提供
- `htpasswd` [`-c`第一次创建时使用] [`-D`删除用户] `passwdfile`   `username`

六、状态查看模块ngx_http_stub_status_module

> 用于输出nginx的基本状态信息

- `Active connections`:当前状态，活动状态的连接数
- `accepts`：统计总值，已经接受的客户端请求的总数
- `handled`：统计总值，已经处理完成的客户端请求的总数
- `requests`：统计总值，客户端发来的总的请求数
- `Reading`：当前状态，正在读取客户端请求报文首部的连接的连接数
- `Writing`：当前状态，正在向客户端发送响应报文过程中的连接数
- `Waiting`：当前状态，正在等待客户端发出请求的空闲连接数 

```bash
# 示例：

location /status {
    stub_status;
    allow 172.16.0.0/16;
    deny all;
}
```

## 七、日志记录模块ngx_http_log_module

```
log_format name string
```

- `string`可以使用`nginx`核心模块及其它模块内嵌的变量

```
access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]];
access_log off;
```

- 访问日志文件路径，格式及相关的缓冲的配置

```
buffer=size
flush=time 
```

```bash
# 示例
log_format compression '$remote_addr-$remote_user [$time_local] '
                         '"$request" $status $bytes_sent '
                         '"$http_referer" "$http_user_agent" "$gzip_ratio"';
access_log /spool/logs/nginx-access.log compression buffer=32k; 
json格式日志示例;log_format json '{"@timestamp":"$time_iso8601",'
                                 '"client_ip":"$remote_addr",'
                                 '"size":$body_bytes_sent,'
                                 '"responsetime":$request_time,'
                                 '"upstreamtime":"$upstream_response_time",'
                                 '"upstreamhost":"$upstream_addr",'
                                 '"http_host":"$host",'
                                 '"method":"$request_method",'
                                 '"request_uri":"$request_uri",'
                                 '"xff":"$http_x_forwarded_for",'
                                 '"referrer":"$http_referer",'
                                 '"agent":"$http_user_agent",'
                                 '"status":"$status"}';
```

```
open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];
```

- `open_log_file_cache off`; 缓存各日志文件相关的元数据信息
- `max`：缓存的最大文件描述符数量
- `min_uses`：在`inactive`指定的时长内访问大于等于此值方可被当作活动项
- `inactive`：非活动时长
- `valid`：验正缓存中各缓存项是否为活动项的时间间隔

```bash
# 例: 
open_log_file_cache max=1000 inactive=20s  valid=1m;
```

## 八、压缩相关选项ngx_http_gzip_module

- `gzip on | off`;  #启用或禁用`gzip`压缩
- `gzip_comp_level level`;  #压缩比由低到高： `1` 到 `9 ` 默认： `1`
- `gzip_disable regex` ...;  #匹配到客户端浏览器不执行压缩
- `gzip_min_length length`;  #启用压缩功能的响应报文大小阈值 
- `gzip_http_version 1.0 | 1.1`; #设定启用压缩功能时，协议的最小版本 默认：`1.1`
- `gzip_buffers number size`;
支持实现压缩功能时缓冲区数量及每个缓存区的大小
默认： `32 4k` 或 `16 8k`
- `gzip_types mime-type` ...;
指明仅对哪些类型的资源执行压缩操作；即压缩过滤器
默认包含有`text/html`，不用显示指定，否则出错
- `gzip_vary on | off;`
如果启用压缩，是否在响应报文首部插入`“Vary: AcceptEncoding`
- `gzip_proxied off` | `expired` | `no-cache` | `no-store `|
`private` | `no_last_modified` | `no_etag `| `auth` | `any` ...;

> `nginx`对于代理服务器请求的响应报文，在何种条件下启用压缩功能

- `off`：对被代理的请求不启用压缩
- `expired`,`no-cache`, `no-store`， `private`：对代理服务器请求的响应报文首部`Cache-Control`值任何一个，启用压缩功能

```bash
# 示例：
gzip on;
gzip_comp_level 6;
gzip_http_version 1.1;
gzip_vary on;
gzip_min_length 1024;
gzip_buffers 16 8k;
gzip_proxied any;
gzip_disable "MSIE[1-6]\.(?!.*SV1)";
gzip_types text/xml text/plain text/css application/javascript application/xml application/json;
```

## 九、https模块ngx_http_ssl_module模块：

- `ssl on | off`; 为指定虚拟机启用`HTTPS protocol`， 建议用`listen`指令代替
- `ssl_certificate file`; 当前虚拟主机使用PEM格式的证书文件
- `ssl_certificate_key fil`; 当前虚拟主机上与其证书匹配的私钥文件
- `ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]`; 支持`ssl`协议版本，默认为后三个
- `ssl_session_cache off | none | [builtin[:size]]
[shared:name:size]`;
  - `builtin[:size]`：使用`OpenSSL`内建缓存，为每`worker`进程私有
  - `[shared:name:size]`：在各`worker`之间使用一个共享的缓存 
- `ssl_session_timeout time`;
  - 客户端连接可以复用`ssl session cache`中缓存的`ssl`参数的有效时长，默认`5m`

```bash
# 示例：
server {
    listen 443 ssl;
    server_name www.magedu.com;
    root /vhosts/ssl/htdocs;
    ssl on;
    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;
    ssl_session_cache shared:sslcache:20m;
    ssl_session_timeout 10m;
}
```

## 十、重定向模块ngx_http_rewrite_module

1. **rewrite regex replacement [flag]**

> 将用户请求的`URI`基于`regex`所描述的模式进行检查，匹配到时将其替换为`replacement`指定的新的`URI`。注意：如果在同一级配置块中存在多个`rewrite`规则，那么会自下而下逐个检查；被某条件规则替换完成后，会重新一轮的替换检查

- 隐含有循环机制,但不超过`10`次；如果超过，提示`500`响应码，`[flag]`所表示的标志位用于控制此循环机制
- 如果`replacement`是以`http://`或`https://`开头，则替换结果会直接以重向返回给客户端 `[flag]`：
- `last`：重写完成后停止对当前`URI`在当前`location`中后续的其它重写操作，而后对新的URI启动新一轮重写检查；提前重启新一轮循环
- `break`：重写完成后停止对当前`URI`在当前`location`中后续的其它重写操作，而后直接跳转至重写规则配置块之后的其它配置；结束循环，建议在`location`中使用
- `redirect`：临时重定向，重写完成后以临时重定向方式直接返回重写后生成的新URI给客户端，由客户端重新发起请求；不能以`http://`或`https://`开头，使用相对路径，状态码： `302`
- `permanent`:重写完成后以永久重定向方式直接返回重写后生成的新URI给客户端，由客户端重新发起请求，状态码：`301`

```bash
# 例：
rewrite ^/zz/(.*\.html)$  /zhengzhou/$1 break;
rewrite ^/zz/(.*\.html)$  https://www.dianping/zhengzhou/$1 permanent;
```

2. **return**

> 停止处理，并返回给客户端指定的响应码

```bash
return code [text];
return code URL;
return URL;
```

3. **rewrite_log on | off;**

> 是否开启重写日志, 发送至`error_log（notice level）`

4. **set $variable value;**

- 用户自定义变量
- 注意：变量定义和调用都要以`$`开头

5. **if (condition) { ... }**

> 引入新的上下文,条件满足时，执行配置块中的配置指令； `server`, `location`

**比较操作符**：
- `==` 相同
- `!=` 不同
- `~：`模式匹配，区分字符大小写
- `~*`：模式匹配，不区分字符大小写
- `!~`：模式不匹配，区分字符大小写
- `!~*`：模式不匹配，不区分字符大小写
文件及目录存在性判断：
- `-e`, `!-e` 存在（包括文件，目录，软链接）
- `-f`, `!-f` 文件
- `-d`, `!-d` 目录
- `-x`, `!-x` 执行 

```bash
# 浏览器分流示例：
if ($http_user_agent ~ Chrom) {
rewrite ^(.*)$  /chrome/$1 break;                                                 
}
if ($http_user_agent ~ MSIE) {
rewrite ^(.*)$  /IE/$1 break;                                                      
}
```

## 十一、引用模块ngx_http_referer_module

```
valid_referers none|blocked|server_names|string ...;
```

> 定义`referer`首部的合法可用值，不能匹配的将是非法值,用于防盗链，

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/nginx/-Nginx%E4%B8%AD%E5%B8%B8%E7%94%A8%E7%9A%84%E6%A8%A1%E5%9D%97%E6%95%B4%E7%90%86
