Nginx 是一款高性能的 HTTP 服务器和反向代理服务器，广泛用于 Web 服务架构中。它的配置文件 nginx.conf 是其核心配置文件，控制着 Nginx 的运行行为、模块加载方式以及站点的路由规则。本文将深入解析 nginx.conf 的结构与常用指令，帮助你全面掌握 Nginx 的配置方法。

一、语法介绍

指令

Nginx 配置文件由一系列指令组成，每个指令以分号 ; 结尾。

指令可以单独成行，也可以一行包含多个指令。

块

大部分指令可以包含在块中，块用 {} 括起来。

块可以包含其他指令或者其他块。

注释

使用 # 符号表示注释，注释可以出现在行的任何位置。

上下文

Nginx 的配置指令可以根据上下文来决定其作用范围。

常见的上下文有 http、server、location 等。

变量

Nginx 支持内置变量和自定义变量。

内置变量表示请求的相关信息，例如 、args 等。

自定义变量通过 set 指令定义，例如 set $my_var value。

通配符

Nginx 支持通配符 *、? 和 ~ 等来匹配 URL。

重定向和重写

rewrite 指令用于重写 URL，可以实现 URL 的修改和重定向。

return 指令用于直接返回指定的 HTTP 状态码和响应内容。

变量和指令的嵌套

Nginx 允许在指令中使用变量，也允许在变量中使用其他变量。

include 指令

include 指令用于在配置文件中包含其他文件的内容。

日志配置

Nginx 允许配置访问日志和错误日志，可以通过 access_log 和 error_log 指令来配置。

二、常用变量参数

# 常用的

$host #请求信息中的Host，如果请求中没有Host行，则等于设置的服务器名

$request_method #客户端的请求类型。如GET、POST

$remote_addr #客户端中的IP地址

$remote_port #客户端端口

$args #请求中的参数

$content_length #请求中的Content-length字段

$http_user_agent #客户端agent信息

$http_cookie #客户端cookie

$server_protovol #请求协议，如HTTP/1.0、HTTP/1.1

$server_addr #服务器地址

$server_name #服务器名称

$server_port #服务器端口

# 其他的

$args #请求中的参数值

$query_string #同 $args

$arg_NAME #GET请求中NAME的值

$is_args #如果请求中有参数，值为"?"，否则为空字符串

$uri #请求中的当前URI(不带请求参数，参数位于$args)，可以不同于浏览器传递的$request_uri的值，它可以通过内部重定向，或者使用index指令进行修改，$uri不包含主机名，如"/foo/bar.html"。

$document_uri #同 $uri

$document_root #当前请求的文档根目录或别名

$host #优先级：HTTP请求行的主机名>"HOST"请求头字段>符合请求的服务器名.请求中的主机头字段，如果请求中的主机头不可用，则为服务器处理请求的服务器名称

$hostname #主机名

$https #如果开启了SSL安全模式，值为"on"，否则为空字符串。

$binary_remote_addr #客户端地址的二进制形式，固定长度为4个字节

$body_bytes_sent #传输给客户端的字节数，响应头不计算在内；这个变量和Apache的mod_log_config模块中的"%B"参数保持兼容

$bytes_sent #传输给客户端的字节数

$connection #TCP连接的序列号

$connection_requests #TCP连接当前的请求数量

$content_length #"Content-Length" 请求头字段

$content_type #"Content-Type" 请求头字段

$cookie_name #cookie名称

$limit_rate #用于设置响应的速度限制

$msec #当前的Unix时间戳

$nginx_version #nginx版本

$pid #工作进程的PID

$pipe #如果请求来自管道通信，值为"p"，否则为"."

$proxy_protocol_addr #获取代理访问服务器的客户端地址，如果是直接访问，该值为空字符串

$realpath_root #当前请求的文档根目录或别名的真实路径，会将所有符号连接转换为真实路径

$remote_addr #客户端地址

$remote_port #客户端端口

$remote_user #用于HTTP基础认证服务的用户名

$request #代表客户端的请求地址

$request_body #客户端的请求主体：此变量可在location中使用，将请求主体通过proxy_pass，fastcgi_pass，uwsgi_pass和scgi_pass传递给下一级的代理服务器

$request_body_file #将客户端请求主体保存在临时文件中。文件处理结束后，此文件需删除。如果需要之一开启此功能，需要设置client_body_in_file_only。如果将次文件传 递给后端的代理服务器，需要禁用request body，即设置proxy_pass_request_body off，fastcgi_pass_request_body off，uwsgi_pass_request_body off，or scgi_pass_request_body off

$request_completion #如果请求成功，值为"OK"，如果请求未完成或者请求不是一个范围请求的最后一部分，则为空

$request_filename #当前连接请求的文件路径，由root或alias指令与URI请求生成

$request_length #请求的长度 (包括请求的地址，http请求头和请求主体)

$request_method #HTTP请求方法，通常为"GET"或"POST"

$request_time #处理客户端请求使用的时间,单位为秒，精度毫秒； 从读入客户端的第一个字节开始，直到把最后一个字符发送给客户端后进行日志写入为止。

$request_uri #这个变量等于包含一些客户端请求参数的原始URI，它无法修改，请查看$uri更改或重写URI，不包含主机名，例如："/cnphp/test.php?arg=freemouse"

$scheme #请求使用的Web协议，"http" 或 "https"

$server_addr #服务器端地址，需要注意的是：为了避免访问linux系统内核，应将ip地址提前设置在配置文件中

$server_name #服务器名

$server_port #服务器端口

$server_protocol #服务器的HTTP版本，通常为 "HTTP/1.0" 或 "HTTP/1.1"

$status #HTTP响应代码

$time_iso8601 #服务器时间的ISO 8610格式

$time_local #服务器时间（LOG Format 格式）

$cookie_NAME #客户端请求Header头中的cookie变量，前缀"$cookie_"加上cookie名称的变量，该变量的值即为cookie名称的值

$http_NAME #匹配任意请求头字段；变量名中的后半部分NAME可以替换成任意请求头字段，如在配置文件中需要获取http请求头："Accept-Language"，$http_accept_language即可

$http_cookie

$http_host #请求地址，即浏览器中你输入的地址（IP或域名）

$http_referer #url跳转来源,用来记录从那个页面链接访问过来的

$http_user_agent #用户终端浏览器等信息

$http_x_forwarded_for

$sent_http_NAME #可以设置任意http响应头字段；变量名中的后半部分NAME可以替换成任意响应头字段，如需要设置响应头Content-length，$sent_http_content_length即可

$sent_http_cache_control

$sent_http_connection

$sent_http_content_type

$sent_http_keep_alive

$sent_http_last_modified

$sent_http_location

$sent_http_transfer_encoding

三、配置文件位置

默认情况下，Nginx 的主配置文件位于：/etc/nginx/nginx.conf，此外，Nginx 支持通过 include 指令引入其他配置文件，例如站点配置通常放在 /etc/nginx/conf.d/ 或 /etc/nginx/sites-available/ 目录下。

四、配置文件结构

nginx.conf 的结构采用块级嵌套语法，主要分为以下几个层级：

main { # 全局设置

events { # 网络连接相关配置

...

}

http { # HTTP 协议相关配置

upstream myapp {

...

}

server { # 虚拟主机配置（站点）

location / {

...

}

}

server {

# 第二个虚拟主机配置

}

}

}

main 块（全局配置）

作用于整个 Nginx 进程，包括进程数、用户权限、日志路径等。

user nginx; # 指定运行 Nginx 的用户

worker_processes auto; # 工作进程数，一般设为 CPU 核心数或 auto

error_log /var/log/nginx/error.log notice; # 错误日志路径及级别

pid /var/run/nginx.pid; # PID 文件路径

events 块（事件处理模型）

控制 Nginx 的网络连接机制，如连接数、多路复用模型等。

events {

worker_connections 1024; # 每个 worker 进程最大连接数

use epoll; # 使用 epoll 多路复用（Linux 推荐）

multi_accept on; # 启用一次接收多个新连接

}

说明：

worker_connections 控制单个 worker 可以同时处理的最大连接数。

use 指定使用的 I/O 模型，常见值有 epoll（Linux）、kqueue（BSD）等。

multi_accept 提升高并发场景下的性能。

http 块（HTTP 服务配置）

这是最复杂的部分，包含 MIME 类型定义、日志格式、虚拟主机（server）配置、负载均衡（upstream）等。

http {

include /etc/nginx/mime.types; # 包含 MIME 类型定义

default_type application/octet-stream;

log_format main '$remote_addr - $remote_user [$time_local] "$request" '

'$status $body_bytes_sent "$http_referer" '

'"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;

sendfile on; # 开启高效文件传输模式

keepalive_timeout 65; # 长连接超时时间

gzip on; # 启用 GZIP 压缩

gzip_types text/plain application/json text/css application/javascript;

upstream backend {

least_conn;

server 127.0.0.1:8080 weight=3;

server 127.0.0.1:8081;

server 127.0.0.1:8082 backup;

}

server {

listen 80;

server_name example.com;

location / {

proxy_pass http://backend;

}

error_page 500 502 503 504 /50x.html;

location = /50x.html {

root /usr/share/nginx/html;

}

}

}

五、关键配置项详解

server

每个 server 表示一个独立的网站（虚拟主机），可以监听不同的端口和域名。

server {

# 配置指令

}

listen

listen 是 Nginx 配置中用于指定服务器监听的 IP 地址和端口的指令。它的作用是告诉 Nginx 在哪个地址和端口上监听传入的连接。

# ----------------语法

server {

listen [地址]:端口 [参数];

}

# -----------------例子

# 监听所有地址（IPv4 和 IPv6）的 80 端口

listen 80;

# 只监听 IPv4 地址的 443 端口，并启用 SSL：

listen 443 ssl;

# 同时监听 IPv4 和 IPv6 地址的 8080 端口

listen [::]:8080;

listen 8080;

参数：

地址：可选参数，用于指定监听的 IP 地址。如果不指定，则默认监听所有地址（即 0.0.0.0）。

端口：必选参数，用于指定监听的端口号。

参数：可选参数，用于指定监听的额外选项，例如 SSL、HTTP2 等。

server_name

server_name 是 Nginx 配置中用于指定虚拟主机的域名或者 IP 地址的指令。它的作用是告诉 Nginx 哪些域名或 IP 地址对应于当前的虚拟主机配置。

# --------------------语法

server {

server_name 域名1 [域名2 ...];

}

# --------------------例子

# 指定单个域名

server_name example.com;

# 指定多个域名

server_name example.com www.example.com;

# 使用通配符

server_name *.example.com;

# 使用 IP 地址

server_name 192.168.1.1;

参数：

域名：可以是完整的域名，也可以是通配符或者 IP 地址。可以使用空格分隔多个域名。

通配符：* 表示匹配任意字符，例如 *.example.com 可以匹配 www.example.com、sub.example.com 等。

IP 地址：可以是具体的 IPv4 或 IPv6 地址，例如 192.168.1.1、[2001:0db8::1]。

location

在 Nginx 配置中，location 指令用于定义请求的匹配规则和处理逻辑，它允许你根据请求的 URL 路径对请求进行分类，并在不同的路径下应用不同的配置。

语法：

location [修饰符] 匹配规则 {

# 配置指令

}

修饰符：

=：精确匹配，只有当请求的 URL 完全等于指定的路径时才会匹配。

~：正则表达式匹配，区分大小写。

~*：正则表达式匹配，不区分大小写。

^~：普通字符匹配，优先于正则匹配。

/ ：通用匹配, 如果没有其它匹配,任何请求都会匹配到。

匹配规则：

普通字符串：可以是具体的 URL 路径，例如 /images/。

正则表达式：使用 ~ 或 ~* 修饰符定义，例如 ~ ^/images/.+.(jpg|png)$。

特殊字符：例如 / 表示匹配所有请求，~ .php$ 表示匹配所有以 .php 结尾的请求。

匹配规则优先级：

精确匹配（=）优先于其他匹配规则。

普通字符匹配（^~）优先于正则表达式匹配（~ 和 ~*）。

正则表达式匹配按照定义的顺序进行匹配，优先匹配在前面的规则。

“

location 块可以嵌套，允许在更细粒度的路径上定义更具体的配置。

域名匹配的四种写法：

精确匹配：server_name www.mingongge.com ;

左侧通配：server_name *.mingongge.com ;

右侧统配：server_name www.mingongge.* ;

正则匹配：server_name ~^www.mingongge.*$ ;

“

匹配优先级：精确匹配 > 左侧通配符匹配 > 右侧通配符匹配 > 正则表达式匹配

proxy_pass

proxy_pass 指令用于将请求转发给另一个服务器处理，并将该服务器的响应返回给客户端。它通常用于配置 Nginx 作为反向代理服务器，将请求转发给后端的应用服务器或者其他 Web 服务器。

# 语法：

proxy_pass URL;

# 参数：

# URL：必选参数，用于指定后端服务器的地址。可以是 IP 地址、主机名、或者带有协议和端口的完整 URL。

# 例子：

location /proxy/ {

proxy_pass http://127.0.0.1; #代理到URL：http://127.0.0.1/proxy/test.html

proxy_pass http://127.0.0.1/; #代理到URL：http://127.0.0.1/test.html

proxy_pass http://127.0.0.1/aaa; #代理到URL：http://127.0.0.1/aaatest.html

proxy_pass http://127.0.0.1/aaa/; #代理到URL：http://127.0.0.1/aaa/test.html

}

# proxy_pass 指令通常与其他配置指令一起使用

location / {

proxy_pass http://172.17.106.235:18000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

}

root

location中root指定的只是相对路径，需要和路径结合起来映射地址，比如

# 这里的root需要和路径结合使用，即是映射的文件位置为 /usr/html/static

# 例如，对于请求 /static/a.css ，那么就会找到 /usr/html/static/a.css

location ^~/static/ {

root /usr/html/;

index index.html

}

location /web {

root /usr/local/;

index index.html index.htm;

}

“

注意：server下也有root，server是全局的，location是局部的，location会覆盖server的

alias

alias 指令用于在 Nginx 的 server 块中创建一个与请求 URL 不同的文件路径映射。它允许你将请求的 URL 路径替换为指定的别名，并指定一个实际的文件系统路径，alias指定的是绝对路径，不会和location中的路径结合使用，而是直接使用地址映射到文件。

# 在这个示例中，location /images/ 定义了一个 alias，

# 它将 URI 中的 /images/ 映射到文件系统中的 /var/www/images/。

# 例如，对于请求 /images/photo.jpg，Nginx 将查找文件 /var/www/images/photo.jpg。

server {

listen 80;

server_name example.com;

location /images/ {

alias /var/www/images/;

index index.html;

}

}

# 不会路径结合映射地址，那么这里就会直接映射到/usr/html/文件夹下的文件

location ^~/static/ {

alias /usr/html/;

index index.html

}

# 后面不加/会把location的去掉

location /bb {

alias /usr/local/web;

index index.html index.htm;

}

# 后面加了/也会把location的拼接上 如：/data/pages

location /pages/ {

alias /data;

}

try_files

try_files 指令是 Nginx 配置中用于指定文件检查顺序的指令。它用于配置 Nginx 在处理请求时尝试查找文件的顺序，如果文件存在则将其返回给客户端，否则执行指定的操作。

try_files 文件路径1 [文件路径2 ...] 请求处理动作;

参数：

文件路径：必选参数，用于指定要尝试查找的文件路径。可以指定多个文件路径，Nginx 将按照指定的顺序依次尝试查找这些文件。

请求处理动作：必选参数，用于指定当文件不存在时的请求处理动作，可以是以下几种值之一：

uri：将请求重定向到指定的 URI。

return code：返回指定的 HTTP 状态码。

@name：将请求转发到指定的命名位置。

例子：

location / {

try_files $uri $uri/ /index.php?$query_string;

}

在这个例子中，当客户端请求的 URL 匹配 / 路径时，Nginx 将会按照以下顺序尝试查找文件：

首先尝试查找请求的 URI 对应的文件（例如 /path/to/file）。

如果找不到对应的文件，则尝试查找以请求的 URI 结尾的目录（例如 /path/to/file/）。

如果仍然找不到对应的文件，则将请求重定向到 /index.php 并附带原始的查询参数。

index

在 Nginx 中，index 指令用于指定默认的索引文件，当客户端请求的 URL 是一个目录时，Nginx 将会尝试在该目录下寻找指定的索引文件，并将其返回给客户端。

index 文件名 [文件名 ...];

# 例子：

index index.html index.htm;

“

注意：

如果没有明确指定 index 指令，默认的索引文件是 index.html。

如果请求的目录下没有任何指定的索引文件，或者没有权限访问这些文件，则 Nginx 将会返回一个 403 Forbidden 或者 404 Not Found 错误。

server下也有index，server是全局的，location是局部的，location会覆盖server的

autoindex

autoindex 指令是 Nginx 配置中用于开启或关闭目录列表显示的指令。当客户端请求的 URL 是一个目录时，如果开启了 autoindex，Nginx 将会自动列出该目录下的文件和子目录，并生成一个目录列表页面返回给客户端；如果关闭了 autoindex，Nginx 将会返回一个 403 Forbidden 或者 404 Not Found 错误。

autoindex on | off;

# 例子

location /files/ {

autoindex on;

}

# 以通过在 autoindex 指令后面加上额外的参数来定制目录列表显示的样式，例如 autoindex on html; 将会以 HTML 格式显示目录列表。

location /files/ {

autoindex on html;

}

error_page

定义错误页面处理逻辑

error_page 404 /404.html;

error_page 500 502 /50x.html;

access_log 和 error_log

定义访问日志和错误日志路径

error_log /var/log/nginx/error.log;

log_format main '$remote_addr - $remote_user [$time_local] "$request" '

'$status $body_bytes_sent "$http_referer" '

'"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;