NGINX `ngx_http_core_module` 深度解读与实战指南
一、模块定位与主要功能
- 核心职责
- 接受并解析客户端请求
- 管理连接与请求生命周期（超时、长连接等）
- 路由与分发：
server、location、try_files - 静态文件服务：
root/alias/sendfile - 缓冲与 I/O 优化：
client_body_buffer_size、aio、directio - 访问控制与限速：
limit_except、limit_rate、satisfy - 错误处理：
error_page、recursive_error_pages - 日志与调试：
log_not_found、log_subrequest
二、请求与连接管理
1. 超时控制
client_header_timeout 60s; # 读取请求头超时时间
client_body_timeout 60s; # 读取请求体超时时间
send_timeout 60s; # 发送响应超时时间
keepalive_timeout 75s; # 长连接超时时间
合理调节可平衡用户体验与资源占用，避免慢速客户端拖垮 worker。
2. 缓冲与临时文件
client_body_buffer_size 16k; # 请求体缓冲大小
client_body_in_single_buffer on; # 将请求体保存在单一缓冲区
client_body_temp_path /tmp/nginx_body 1 2;
当请求体过大时，NGINX 会将剩余部分写入临时文件。client_body_in_file_only on|clean 可强制或清理这些文件。
三、静态文件 I/O 优化
1. sendfile 与 aio
sendfile on; # 使用零拷贝
tcp_nopush on; # 合并头部与文件首块
aio on; # 异步读文件（Linux/FreeBSD）
directio 4m; # 文件大于 4MB 时启用 O_DIRECT
- Zero-copy：
sendfile将内核页缓存直接发送给网络套接字。 - AIO + DirectIO：对于大文件启用异步与直接 I/O，减轻 worker 进程阻塞。
2. 读写分块
sendfile_max_chunk 2m; # 限制单次 sendfile 大小，防止吞占过多 worker
output_buffers 2 32k;# 磁盘文件读取缓冲区
postpone_output 1460; # 在缓冲区满一定数据后再发送
四、路由与文件定位
1. root vs alias
location /images/ {root /data/www; # /images/foo.jpg → /data/www/images/foo.jpg
}
location /static/ {alias /data/static/; # /static/foo.css → /data/static/foo.css
}
alias：直接替换整个 URI 前缀，更灵活；- 正则 Location 下 alias：必须引用捕获组。
2. try_files
location / {try_files $uri $uri/ /index.html =404;
}
按顺序检测文件或目录，未命中则内部重定向或返回错误。
3. location 匹配优先级
- 精确匹配 (
= /) - 前缀匹配最长 (
^~) - 正则按定义顺序
- 普通前缀
五、访问控制与限速
1. 方法限制
location /api/ {limit_except GET POST {deny all;}
}
仅允许指定方法，其余返回 405 或 403。
2. 速率限制
limit_rate 100k; # 每个请求最大 100KB/s
limit_rate_after 1m; # 前 1MB 不限速
配合 map 动态速率可实现分级限流；也可通过 $limit_rate 变量设置。
3. 访问策略
satisfy any;
allow 192.168.1.0/24;
deny all;
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/htpasswd;
all 要求同时满足 IP 白名单与身份验证；any 则二者其一即可。
六、错误处理与日志
1. 错误页自定义
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
error_page 403 =301 http://example.com/forbidden.html;
支持内部重定向与外部跳转，可变更响应码：=200。
2. 日志开关
log_not_found off; # 不记录 404
log_subrequest on; # 记录子请求
recursive_error_pages on; # 多级错误页跳转
七、内置变量精要
| 变量 | 含义 |
|---|---|
$remote_addr | 客户端 IP |
$request_uri | 原始请求 URI |
$args | 查询字符串 |
$request_body | 请求体（小体量时） |
$document_root | root 或 alias 值 |
$uri | 规范化后的 URI（可能因重写改变） |
$host | Host 头或服务器名 |
$scheme | http/https |
$status | 响应状态码 |
$connection_requests | 单连接请求计数 |
$request_time | 请求处理总时长，精度毫秒 |
借助这些变量，可在日志、proxy_pass、add_header 等指令中灵活操作。
八、最佳实践与调优建议
- 连接与超时：根据业务特性合理缩短超时，避免“慢速客户端攻击”。
- 缓冲与 I/O：静态大文件启用
sendfile+aio+directio；小文件用默认即可。 - 路由规则顺序：将最热路径放在前面（如
= /favicon.ico、^~ /static/）加速匹配。 - 错误页与重试：避免过度递归的错误重定向，
recursive_error_pages仅在必要时开启。 - 安全策略：结合
limit_except、satisfy与disable_symlinks加固防护。 - 日志管理：对高并发路径关闭
log_not_found，对子请求、反向代理开启log_subrequest，便于排查。
九、总结
ngx_http_core_module 是 NGINX HTTP 服务的基础基石，其指令涵盖了从连接管理、请求解析到路由分发、文件 I/O、访问控制、错误处理等核心场景。通过合理组合各项指令与内置变量，可打造高性能、可维护且安全的 Web 服务架构。希望本篇详解能帮助你在生产环境中灵活运用、精细调优，打造卓越的 NGINX 应用。