Web 服务器与网关 / 知识点
Nginx 配置指令速查手册
基础结构
load_module file;加载动态模块,通常在主配置文件最前部使用。
load_module
加载动态模块,通常在主配置文件最前部使用。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
load_module file;上下文: main
推荐配置
load_module modules/ngx_http_image_filter_module.so;关键行为
模块文件存在不等于已加载;路径和模块必须与当前 Nginx 构建兼容。
相关指令: include、nginx -V
include file | mask;把其他配置文件或通配符匹配的文件包含到当前位置。
include
把其他配置文件或通配符匹配的文件包含到当前位置。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
include file | mask;上下文: 任意上下文
推荐配置
include /etc/nginx/conf.d/*.conf;关键行为
包含位置决定被引入指令的上下文;目录里的文件不会自动生效,必须被 include 匹配。
相关指令: nginx -T
定义连接处理相关的全局事件配置。
events
定义连接处理相关的全局事件配置。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
events { ... }上下文: main
推荐配置
events {
worker_connections 4096;
}关键行为
每个配置只能有一个 events 块,常与 worker_connections、multi_accept 一起配置。
验证
sudo nginx -t相关指令: worker_connections、multi_accept
定义 HTTP 服务的顶层配置上下文。
http
定义 HTTP 服务的顶层配置上下文。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
http { ... }上下文: main
推荐配置
http {
include /etc/nginx/conf.d/*.conf;
}关键行为
server、upstream、map、log_format 等 HTTP 指令通常放在该块或其子上下文中。
验证
sudo nginx -t相关指令: server、upstream、map
定义一个 HTTP/HTTPS 虚拟主机。
server(虚拟主机)
当一个端口需要承载独立域名、静态站点或反向代理服务时查这个指令。server 是 HTTP 配置的核心边界,监听地址、域名匹配、TLS 与 location 都在这里组合。
语法
server { ... }上下文: http
推荐配置
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
root /srv/www/example;
index index.html;
access_log /var/log/nginx/example.access.log;
error_log /var/log/nginx/example.error.log warn;
location / {
try_files $uri $uri/ =404;
}
}关键行为
- 请求先按
address:port选出候选虚拟主机,再根据Host/server_name选择具体server。 - 同一监听地址最好明确一个
default_server,避免未知域名误入业务站点。 - HTTPS 的证书选择发生在请求头解析之前,默认 443 虚拟主机的 TLS 配置尤其重要。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -H 'Host: example.com' http://127.0.0.1/常见问题
- 请求进入了错误站点:检查
listen、server_name和默认虚拟主机。 - 配置文件存在但不生效:先用
nginx -T确认文件确实被 include。
相关指令: listen、server_name、location
设置 Nginx worker 进程数量。
worker_processes
设置 Nginx worker 进程数量。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
worker_processes number | auto;上下文: main
推荐配置
worker_processes auto;关键行为
auto 会按可用 CPU 自动选择数量;它不是请求并发上限。
验证
sudo nginx -t相关指令: worker_connections、worker_rlimit_nofile
提高 worker 可打开文件描述符的资源上限。
worker_rlimit_nofile
提高 worker 可打开文件描述符的资源上限。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
worker_rlimit_nofile number;上下文: main
推荐配置
worker_rlimit_nofile 65535;关键行为
它不能突破操作系统或 systemd 的更低限制;调整后应检查实际进程 limits。
验证
sudo nginx -t相关指令: worker_connections
设置单个 worker 可同时打开的最大连接数。
worker_connections
设置单个 worker 可同时打开的最大连接数。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
worker_connections number;上下文: events
推荐配置
events {
worker_connections 4096;
}关键行为
反向代理场景一次客户端请求可能同时占用客户端和上游连接,因此不能简单把该值等同于最大用户数。
验证
sudo nginx -t相关指令: worker_processes、worker_rlimit_nofile
multi_accept on | off;控制 worker 收到新连接事件后是否一次尽可能接受多个连接。
multi_accept
控制 worker 收到新连接事件后是否一次尽可能接受多个连接。这类基础指令会影响配置结构或进程行为,先确认它所在的配置层级,再修改。
语法
multi_accept on | off;上下文: events
推荐配置
events {
multi_accept on;
}关键行为
开启后可能提高突发连接处理速度,但不应把它当作常规性能优化开关;先依据负载测试。
相关指令: worker_connections
站点与路由
设置虚拟主机监听的地址、端口和协议参数。
listen
需要决定 Nginx 在哪个地址、端口和协议上接收连接时查这个指令。重点关注 default_server、IPv6、TLS 和现代 HTTP/2 写法。
语法
listen address[:port] [parameters];上下文: server
推荐配置
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
return 444;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name example.com;
ssl_certificate /etc/nginx/tls/example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/example.com/privkey.pem;
}关键行为
default_server只属于具体的address:port,不是整个 Nginx 的全局默认站点。- 现代 Nginx 已弃用
listen ... http2参数,优先使用独立的http2 on;。 - 同时服务 IPv4 与 IPv6 时应分别声明监听,除非已确认系统的双栈 socket 行为。
验证
sudo nginx -t
sudo ss -lntp | grep nginx常见问题
- 443 已监听但 HTTPS 失败:继续检查证书、SNI 与安全组。
- 多个
default_server报冲突:同一地址端口只能有一个默认虚拟主机。
相关指令: server、server_name、http2
声明虚拟主机匹配的域名,可使用精确名、通配符和正则。
server_name
一个监听端口承载多个域名时,用它定义 Host/SNI 对应的虚拟主机。查这个指令时重点看匹配优先级,而不是只看字符串是否“看起来匹配”。
语法
server_name name ...;上下文: server
推荐配置
server {
listen 80;
server_name example.com www.example.com;
location / {
return 200 "matched example.com\n";
}
}关键行为
- 优先级依次是:精确名称、最长前置通配符、最长后置通配符、按配置顺序命中的第一个正则。
server_name _;只是常见占位写法,本身没有“兜底”语义;真正的兜底由listen ... default_server决定。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -H 'Host: example.com' http://127.0.0.1/常见问题
- 域名命中错误:先确认请求实际到达的 IP/端口,再检查默认虚拟主机。
- 正则域名配置应谨慎,能用精确名或通配符时优先不用正则。
相关指令: listen、server
根据请求 URI 选择配置块。
location
需要判断某个 URI 最终会进入哪个配置块时查这个指令。它决定静态文件、反向代理、重写和鉴权等后续行为,是 Nginx 最容易出现“配置看着对但没有命中”的地方。
语法
location [= | ~ | ~* | ^~] uri { ... }上下文: server、location
推荐配置
server {
listen 80;
server_name example.com;
location = /health {
return 200 "ok\n";
}
location ^~ /static/ {
root /srv/www;
}
location ~* \.(?:jpg|jpeg|png|css|js)$ {
expires 30d;
}
location / {
try_files $uri $uri/ /index.html;
}
}关键行为
=精确匹配命中后直接停止。- 普通前缀会先选最长匹配;如果该前缀带
^~,当前层级不再检查正则 location。 - 正则 location 按配置出现顺序匹配,第一个命中即生效;不是“最长正则优先”。
rewrite、try_files或内部重定向可能触发新的 URI 选择,排障时不能只看第一次 location。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -H 'Host: example.com' http://127.0.0.1/health
curl -i -H 'Host: example.com' http://127.0.0.1/static/app.css常见问题
- 请求总进错块:检查精确/前缀/正则之间的优先级。
- SPA 回退误伤 API:把
/api/放进独立 location,不要让它落入/index.html。
相关指令: try_files、rewrite、proxy_pass
把请求 URI 追加到指定目录形成实际文件路径。
root
URI 与磁盘目录结构基本一致时优先查 root。它会把规范化后的完整 URI 追加到指定目录后面形成文件路径。
语法
root path;上下文: http、server、location、if in location
推荐配置
server {
listen 80;
server_name static.example.com;
root /srv/www;
location /static/ {
try_files $uri =404;
}
}关键行为
location /static/ { root /srv/www; }中,请求/static/app.css对应/srv/www/static/app.css。- 需要“去掉公开 URI 前缀再映射目录”时通常应使用
alias,不要靠重复改 root 试错。
验证
sudo nginx -t && sudo systemctl reload nginx
test -r /srv/www/static/app.css
curl -I -H 'Host: static.example.com' http://127.0.0.1/static/app.css常见问题
- 404:先还原 URI→文件路径,再检查文件是否存在和父目录执行权限。
- 把
root与alias的拼接规则混淆,是静态文件 404 的常见原因。
相关指令: alias、try_files
用指定目录替换 location 已匹配的 URI 前缀。
alias
公开 URI 前缀与真实目录名称不一致时查 alias。它会用指定目录替换已匹配的 location 前缀,而不是把完整 URI 直接追加到目录后。
语法
alias path;上下文: location
推荐配置
server {
listen 80;
server_name static.example.com;
location /assets/ {
alias /srv/cdn/;
try_files $uri =404;
}
}关键行为
- 目录型 location 与 alias 通常都以
/结尾,减少边界路径错误。 /assets/app.css会映射到/srv/cdn/app.css。- 正则 location 使用
alias时通常需要捕获组并在 alias 中引用,维护成本更高。
验证
sudo nginx -t && sudo systemctl reload nginx
test -r /srv/cdn/app.css
curl -I -H 'Host: static.example.com' http://127.0.0.1/assets/app.css常见问题
- 出现重复目录或目录缺失:先确认你需要的是
root + URI还是alias + 剩余 URI。 - 403 不一定是路径错误,还要检查 Unix 权限、SELinux/AppArmor。
相关指令: root、location
index file ...;指定目录请求的默认首页文件。
index
指定目录请求的默认首页文件。排查路由问题时,重点确认请求实际命中的 server / location,不要只看文件里“写了什么”。
语法
index file ...;上下文: http、server、location
推荐配置
index index.html index.htm;关键行为
只对以 / 结尾的目录请求参与处理;找不到首页时是否列目录由 autoindex 决定。
相关指令: try_files、autoindex
按顺序检查文件或目录是否存在,并选择第一个命中项或执行最终回退。
try_files
需要“先检查本地文件,找不到再回退到另一个 URI/状态码”时查这个指令。静态站点和 SPA 都常用,但 API 路由不要无条件回退到前端首页。
语法
try_files file ... uri | =code;上下文: server、location
推荐配置
server {
listen 80;
server_name app.example.com;
root /srv/www/app;
location /api/ {
proxy_pass http://127.0.0.1:8080;
}
location / {
try_files $uri $uri/ /index.html;
}
}关键行为
- 候选路径按当前
root/alias规则检查,前面的候选都不存在时才执行最后一个参数。 - SPA 常用
/index.html,传统静态站点可直接使用=404。 - 最后一个 URI 会触发内部重定向,可能进入新的 location。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I -H 'Host: app.example.com' http://127.0.0.1/
curl -I -H 'Host: app.example.com' http://127.0.0.1/not-a-real-file常见问题
- API 返回前端 HTML:说明
/api/没有被独立 location 截住。 - 文件明明存在仍 404:检查实际 root/alias 和 URI 拼接结果。
相关指令: root、alias、error_page
控制目录没有首页文件时是否生成目录列表。
autoindex
控制目录没有首页文件时是否生成目录列表。排查路由问题时,重点确认请求实际命中的 server / location,不要只看文件里“写了什么”。
语法
autoindex on | off;上下文: http、server、location
推荐配置
location /downloads/ {
autoindex on;
}关键行为
开启会暴露目录内容,不应对包含源码、备份或私密文件的目录使用。
验证
sudo nginx -t相关指令: index、root
为指定 HTTP 状态码设置内部错误页或状态转换。
error_page
为指定 HTTP 状态码设置内部错误页或状态转换。排查路由问题时,重点确认请求实际命中的 server / location,不要只看文件里“写了什么”。
语法
error_page code ... [=response] uri;上下文: http、server、location、if in location
推荐配置
error_page 404 /404.html;
location = /404.html {
internal;
}关键行为
默认会内部重定向到目标 URI;使用 =code 可改变最终状态码。
验证
sudo nginx -t相关指令: internal、return
限制 location 只能由 Nginx 内部重定向或子请求访问。
internal
限制 location 只能由 Nginx 内部重定向或子请求访问。排查路由问题时,重点确认请求实际命中的 server / location,不要只看文件里“写了什么”。
语法
internal;上下文: location
推荐配置
location = /404.html {
internal;
root /srv/www/errors;
}关键行为
外部直接访问该 location 会返回 404,常用于 error_page 等内部资源。
验证
sudo nginx -t相关指令: error_page、try_files
立即返回状态码、文本或重定向地址。
return
只需要固定状态码、短文本或简单重定向时优先查 return。能用它完成的规则通常比 rewrite 更容易读、也更不容易产生循环。
语法
return code [text | URL];上下文: server、location、if
推荐配置
server {
listen 80;
server_name example.com www.example.com;
return 301 https://example.com$request_uri;
}关键行为
- 301 会被浏览器和中间缓存长期记住;规则尚未稳定时可以先用 302/307 验证。
$request_uri保留原始路径和查询串,适合整站 HTTP→HTTPS 跳转。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I -H 'Host: example.com' http://127.0.0.1/demo?a=1常见问题
- 重定向循环:检查 HTTPS 终止是否在上游负载均衡器,以及
$scheme是否反映真实外部协议。
相关指令: rewrite