1. 先搞清楚Nginx到底是什么以及为什么大家都在用它如果你接触过网站部署、接口联调或者任何前后端分离的项目大概率逃不开 Nginx。简单说Nginx 是一个高性能的 HTTP 服务器和反向代理服务器最早由 Igor Sysoev 在 2004 年发布最初就是为了解决 C10K 问题——也就是单机同时处理一万个并发连接的老大难。十几年下来它已经成了互联网架构里的标配组件从静态文件服务、反向代理、负载均衡到 HTTPS 终结、灰度发布、流媒体推流Nginx 几乎样样都能干。我自己最早接触 Nginx 是在一次给客户部署前后端分离项目的时候。前端打包出来的 dist 目录要有人托管后端 Java 服务要有人转发测试环境还要解决跨域问题。当时搜了一圈发现 Nginx 就是干这个的把静态页面直接吐给浏览器把 /api 开头的请求转发给后端服务顺带把跨域、压缩、缓存全部解决掉。从那以后我基本每次部署新项目都会优先考虑 Nginx不管是几台机器的集群还是单机小服务它都能稳稳接住。这篇文章不打算写成官方文档那种逐行翻译的教程而是按照我平时排查问题、部署服务时的真实路径来组织内容。你会看到如何安装 Nginx、如何读懂 nginx.conf 里每一段配置的含义、如何配置反向代理和负载均衡、如何部署前端打包产物、如何排查状态码异常以及一些 Docker 环境下的实用操作。适合刚接触 Nginx 的新手也适合已经会用但想搞清楚原理的运维和开发同学。2. 环境准备不同操作系统和部署方式下的安装方法与取舍2.1 Linux 下的三种安装方式包管理器、源码编译、离线安装Linux 是 Nginx 的主场绝大多数生产环境跑的都是 Linux。安装方式主要看你的网络环境和诉求。最省事的是用系统自带的包管理器。Ubuntu/Debian 系执行apt install nginxCentOS/RHEL 系执行yum install nginx或者dnf install nginx。这种方式装出来的版本可能不是最新的但胜在稳定而且 systemd 服务脚本都给你配好了装完就能systemctl start nginx日志轮转、开机自启这些也都顺手搞定。如果追求最新特性比如 HTTP/3、新的负载均衡指令那就可以去 Nginx 官网添加官方源或者自己编译。源码编译适合需要定制模块的场景。比如你要用 RTMP 模块做直播推流或者要集成一些第三方插件就必须在编译时通过--add-module带进去。编译安装的基本顺序是先装依赖gcc、pcre、zlib、openssl然后解压源码包执行 configure 配置想要的模块最后 make 和 make install。Nginx 默认安装目录是/usr/local/nginx启动文件在/usr/local/nginx/sbin/nginx配置文件在/usr/local/nginx/conf/nginx.conf。离线安装是我在实际项目中经常要面对的场景尤其是银行、政务、内网环境生产机器根本不连外网。这时候提前准备好 RPM 或者 DEB 包就很关键。找一台能联网的同版本系统用yumdownloader或apt download把 Nginx 以及所有依赖包拉下来传到目标机器上再装。依赖树复杂的话可以用yum install --downloadonly --downloaddir/path/to/dir nginx一键把全部依赖包都下载好省得来回折腾。注意离线安装的版本一定要和目标系统的 glibc 版本兼容。之前我遇到过在一台 CentOS 7 的机器上装了在 CentOS 8 上打好的 RPM 包结果直接报version GLIBC_2.18 not found白折腾半小时。2.2 Windows 下的 Nginx本地联调足够用Windows 版的 Nginx 官方一直在发虽然不推荐在生产环境跑但作为本地开发联调工具完全够用。下载 zip 包之后解压nginx.exe就在根目录下。启动方式是直接双击 exe 或者在命令行执行start nginx此时会有一个黑窗口一闪而过不用害怕进程已经起来了。Windows 下有几个坑需要提前知道。一是 Nginx 在 Windows 下是基于原生 Win32 API 跑的性能表现不如 Linux并发高的时候明显吃力所以生产环境别用 Windows 版扛流量。二是路径写法要用正斜杠或者转义反斜杠比如root D:/nginx/html这样。三是配置文件改完之后在 Windows 下执行nginx.exe -s reload有时候会失效最稳的办法是nginx.exe -s stop然后重新start nginx。四是 Windows 版的 Nginx 不支持user指令也不需要配置不然启动直接报错。2.3 Docker 部署最常用的容器化方案与多项目目录挂载现在新项目绝大多数都是容器化部署Nginx 官方在 Docker Hub 上有维护良好的镜像我用的最多的就是nginx:stable-alpine因为 Alpine 基础镜像体积小只有几十 MB而且官方做了精简跑起来内存占用很低。Docker 部署 Nginx 的核心思路是把配置文件、日志、网站根目录全部挂载到宿主机这样容器随便重建数据不丢。我常用的命令大概是这样的docker run -d --name nginx-web \ -p 80:80 -p 443:443 \ -v /data/nginx/conf.d:/etc/nginx/conf.d \ -v /data/nginx/html:/usr/share/nginx/html \ -v /data/nginx/logs:/var/log/nginx \ -v /data/nginx/ssl:/etc/nginx/ssl \ --restartalways \ nginx:stable-alpine这里的-v把四个关键目录挂出来conf.d放站点配置html放静态文件logs放日志ssl放证书。这样你就完全不用进容器改文件了在宿主机上编辑然后执行docker exec nginx-web nginx -s reload就能让新配置生效。多项目目录挂载的路径规划也很重要。我之前在一个网关机器上用单个 Nginx 容器挂了三个前端项目每个项目对应一个 server 块按域名或者端口区分。目录结构是这样的/data/nginx/ ├── conf.d/ │ ├── project-a.conf │ ├── project-b.conf │ └── project-c.conf ├── html/ │ ├── project-a/ # 存放 A 项目打包产物 │ ├── project-b/ # 存放 B 项目打包产物 │ └── project-c/ # 存放 C 项目打包产物 ├── logs/ └── ssl/每个conf.d下的配置文件就是一个完整的 server 块互不干扰新增项目只需要加一个 conf 文件再加一个 html 子目录。这种方式的优点是隔离性好某个项目的配置出问题不会连累其他项目而且排错时只要看对应文件就好。2.4 K8s 集群里的 NginxIngress Controller 与独立 Pod 的取舍K8s 环境里 Nginx 的出场方式有两种。第一种是部署一个独立的 Nginx Pod 作为集群内某个服务的反向代理这种用法本质上就是上面 Docker 部署的 K8s 版只不过用 Deployment 和 Service 管理起来配置挂载用 ConfigMap 或者 PV。第二种是部署 Nginx Ingress Controller让 Nginx 充当整个集群的流量入口配合 Ingress 资源对象实现按域名和路径路由到不同的 Service。如果你是在 K8s 里部署 MySQL 又部署 Nginx我的建议是 Nginx 用 Deployment 跑MySQL 用 StatefulSet 跑因为后者需要稳定的网络标识和持久化存储。至于 Nginx 的配置管理如果只在集群内部用可以直接用 ConfigMap 挂载/etc/nginx/conf.d如果是给外部提供服务的入口那直接用 Nginx Ingress Controller 是更成熟的方案毕竟它本身就针对云原生场景做了很多优化比如自动 watch Service 变化、原生支持 TLS 证书管理、配合 Cert-Manager 可以自动签发续期证书。3. 配置文件详解从整体结构到每个指令的含义3.1 nginx.conf 的五层结构main、events、http、server、location很多初学者第一次打开 nginx.conf 会有点懵里面密密麻麻全是配置项不知道从哪看起。其实 Nginx 的配置是有严格的层级结构的理解了层级关系后面所有配置都能顺下来。最外层是 main 块作用于全局比如user nginx;、worker_processes auto;、error_log /var/log/nginx/error.log;这些它们控制的是进程运行属性和全局日志路径。接着是events块里面的worker_connections 1024;指定每个 worker 进程可以同时维持的最大连接数。然后是http块所有 HTTP 相关的配置都包在这里面比如include /etc/nginx/mime.types;、sendfile on;、keepalive_timeout 65;。在 http 块里可以包含多个server块每个 server 块就是一台虚拟主机用listen指定监听端口用server_name指定匹配的域名。server 块里还可以再嵌套多个location块用来匹配不同的请求路径。用一句话概括main 管全局进程events 管连接模型http 管 HTTP 协议server 管站点location 管路径。这个结构层级一旦清楚你在网上看到的任何一段 Nginx 配置都能快速定位到它属于哪一层改起来也就有方向感了。3.2 最小可用配置 vs 真实生产配置抄作业的正确姿势网上搜 Nginx 配置的时候能看到各种各样的“最全配置”“终极配置”但很多其实不适合新手直接抄。我建议先从一个最小可用的配置入手跑通了再逐步往上加东西。# /etc/nginx/nginx.conf user nginx; worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; server_tokens off; server { listen 80; server_name example.com; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } } }这里有一个非常关键的指令是try_files $uri $uri/ /index.html;如果你部署的是 Vue 或 React 这类单页应用这个配置能解决刷新页面 404 的问题。原理是用户请求/about路径时服务器发现物理上不存在这个文件就尝试找/about/目录还是找不到最后直接返回/index.html让前端路由接管路径解析。生产环境的真实配置会比这个长很多但基本结构是一样的在 http 块里加上 gzip 压缩、静态资源缓存、日志格式定义在 server 块里加上 HTTPS 证书、HTTP 跳转、反向代理、安全响应头在 location 块里根据路径做不同处理。先掌握这个小配置理解每一行再去看复杂的配置就不会一头雾水。3.3 静态资源服务的核心配置与缓存策略Nginx 最初就是做静态文件服务器起家的处理静态资源的效率至今没有多少同类产品能超越。静态资源服务的核心配置主要围绕三件事展开文件路径映射、内容协商、浏览器缓存。文件路径映射用root和alias两个指令。root是追加路径比如location /static/ { root /data/nginx; }请求/static/img/logo.png时实际查找的文件是/data/nginx/static/img/logo.png。alias是替换路径比如location /static/ { alias /data/files/; }请求/static/img/logo.png时实际查找的是/data/files/img/logo.png。两者差别很容易搞混我写的时候都会在注释里标注当前用的是哪种语义。浏览器缓存策略靠的是expires和Cache-Control响应头。对于图片、JS、CSS 这类带版本号的静态资源可以放心让浏览器缓存配置方式就是一行location ~* \.(js|css|png|jpg)$ { expires 30d; add_header Cache-Control public, no-transform; }。对于 index.html 这种首页文件反而要设置为no-cache否则用户上线新版本之后浏览器还拿旧页面就会出现“明明发布了新版本用户却看不到变化”的问题。我通常是给 index.html 单独配一个 location设置add_header Cache-Control no-cache, must-revalidate;配合前端打包时给文件名加 hash 的手段就能做到静态资源缓存和页面即时更新的最佳平衡。3.4 gzip、日志格式与性能调优的常规操作gzip 压缩是性价比最高的性能优化手段开启后传输体积能减少 60% 以上。核心配置是这几行gzip on; gzip_min_length 1k; gzip_comp_level 5; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript image/svgxml; gzip_vary on;gzip_comp_level是压缩等级范围是 1 到 9。等级越高压缩率越高但 CPU 开销也越大。我自己实测下来等级 5 和 9 的压缩率差距可能就 5% 左右但 CPU 占用差很多所以长期保持在 5 是稳妥的选择。另外gzip_min_length 1k表示小于 1KB 的文件不压缩因为压缩这些小文件的收益太低反而浪费 CPU。日志是排查问题的第一手信息来源。生产环境建议用自定义的日志格式把响应时间、请求时长、上游响应时间这些关键指标打出来log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for $request_time $upstream_response_time;$request_time是 Nginx 处理请求的总耗时$upstream_response_time是后端服务响应耗时。两者一对比就能判断瓶颈是在 Nginx 本身还是后端服务。如果$upstream_response_time很大问题大概率在后端如果两者差不多可能是网络链路有损耗如果$request_time大但$upstream_response_time小可能是 Nginx 在等待后端响应或者发生了日志阻塞。worker_processes 和 worker_connections 是影响性能的两个核心参数。worker_processes auto会按照 CPU 核心数自动设置 worker 进程数量。worker_connections决定单个 worker 能同时处理的连接数上限两者相乘就是理论上限。对于常规 Web 服务设置成auto加10240一般就够了不用盲目调大因为超过系统文件描述符限制反而会报错。4. 反向代理与负载均衡实战从单机到集群4.1 反向代理到底是什么和正向代理有什么区别反向代理这个概念很多人刚开始学的时候容易和正向代理搞混。正向代理是帮客户端转发请求比如你在公司内网访问外网流量先经过公司代理服务器再由它去访问互联网客户端知道自己配置了代理。反向代理是帮服务端接收请求客户端不知道请求最终被转发到哪台真实的服务器上。用生活化的例子说正向代理是“你找中介帮你买东西”中介代表你的利益反向代理是“你打电话到公司总机总机帮你转接到具体部门”总机代表公司的利益。对用户来说他访问的永远是你的域名至于这个域名背后是哪台服务器、哪个端口的服务在处理完全是 Nginx 内部的事情。反向代理是 Nginx 最核心的使用场景。一个典型的配置是server { listen 80; server_name api.example.com; location / { proxy_pass http://127.0.0.1:8080; 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; } }proxy_pass指定请求要转发到的后端地址。proxy_set_header的作用是把客户端的原始信息传递到后端这样后端的 Java、Python 或 Node 服务就能拿到真实的用户 IP、协议和 Host。如果后端是 HTTPS 应用还要加上proxy_set_header X-Forwarded-Proto https;否则后端的重定向逻辑可能会把 HTTPS 请求重定向到 HTTP导致死循环。4.2 upstream 负载均衡四种策略与权重配置当后端服务从一台变成多台就需要负载均衡。Nginx 用upstream指令定义一组后端服务器然后在proxy_pass里指向这个组upstream backend_servers { server 192.168.1.10:8080 weight3; server 192.168.1.11:8080 weight1; server 192.168.1.12:8080 backup; } server { listen 80; server_name api.example.com; location /api/ { proxy_pass http://backend_servers; } }Nginx 默认使用轮询策略请求按顺序轮流分发给每台后端。weight参数可以调整权重weight3表示这台机器承担 3/4 的流量backup表示它是备用节点平时不参与分发只有其他节点都挂了才切上去。除了轮询还有三种常用策略ip_hash按客户端 IP 的哈希值分配同一个 IP 的请求永远打到同一台后端解决了需要会话保持的场景least_conn优先分发连接数最少的后端适合后端处理能力不均的情况hash $request_uri按自定义 key 做哈希常用于缓存场景。我在实际项目里最常遇到的问题是 session 失效。如果你的后端架构没有做 session 共享也就是用户登录状态存在单台服务器的内存里那么用了轮询之后用户第一次请求打到 A 服务器登录了第二次请求被分到 B 服务器B 没有他的登录状态就直接踢回登录页了。解决方式要么后端改造做 Redis session 共享要么前端 Nginx 侧用ip_hash保证用户固定访问一台机器。如果后端机器在云环境且出口 IP 不固定ip_hash就不太靠谱建议用sticky模块做基于 Cookie 的会话保持。4.3 HTTPS 配置证书格式、私钥类型与双向认证HTTPS 是现在所有线上业务的标配Nginx 配置 HTTPS 的核心就是改 listen 和证书路径server { listen 443 ssl http2; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com.pem; ssl_certificate_key /etc/nginx/ssl/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; }关于私钥类型Nginx 支持 PEM 格式的 RSA、ECDSA 和 Ed25519 私钥。一般证书提供商给的.key文件就是 PEM 格式直接能用。如果私钥文件是带密码保护的需要先用 openssl 把密码去掉否则 Nginx 启动时会卡住要你输入密码这在生产环境根本没法接受。这里给出两个常用的转换命令openssl rsa -in encrypted.key -out decrypted.key用来去掉 RSA 私钥的密码如果是 ECDSA 私钥把rsa换成ec即可。双向认证在需要极高安全级别的场景下使用比如某些政企系统要求不仅服务端向客户端证明自己客户端也要向服务端证明身份。Nginx 的双向认证配置一般长这样server { listen 443 ssl; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key; # 开启客户端证书验证 ssl_client_certificate /etc/nginx/ssl/ca.crt; ssl_verify_client on; ssl_verify_depth 2; location / { if ($ssl_client_verify ! SUCCESS) { return 403; } proxy_pass http://backend; } }注意这里ssl_client_certificate填的是签发客户端证书的 CA 根证书不是客户端证书本身。ssl_verify_depth控制证书链的验证深度一般 2 就够了。开启双向认证之后没有安装合法客户端证书的浏览器访问会直接报错后端服务就完全不用关心身份认证的问题可以在更受信任的网络环境下对外提供服务。4.4 部署前后端分离项目pnpm run build 的产物怎么用 Nginx 启动这个问题在网站上搜的人非常多说明很多人都卡在了“前端构建产物怎么托管”这一步。用 Vite 或 Webpack 的项目执行pnpm run build或npm run build之后打包产物默认在dist目录下。这个目录里的 index.html 和静态资源需要一个 Web 服务器来托管Nginx 是最合适的角色。完整的前后端分离部署方案前端静态资源由 Nginx 直接返回后端 API 请求通过反向代理转发server { listen 80; server_name front.example.com; # 前端静态资源 location / { root /data/www/frontend/dist; index index.html; try_files $uri $uri/ /index.html; } # 后端 API 反向代理 location /api/ { proxy_pass http://backend_servers; 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; } }这里有一个容易踩的坑proxy_pass后端的地址末尾带不带/效果完全不同。如果不带/请求/api/login会原样转发成http://backend/api/login如果带/请求/api/login会去掉/api前缀再转发变成http://backend/login。很多新手配置完发现接口 404基本都是这个原因。我的习惯是后端接口都统一带/api前缀Nginx 配置里proxy_pass不带斜杠这样转发路径和后端路由一致好排查。另外开发环境常见的跨域问题在 Nginx 层也可以直接解决。如果后端没有开 CORS你可以在反向代理的 location 里加上几个响应头add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS; add_header Access-Control-Allow-Headers Authorization, Content-Type, Accept; add_header Access-Control-Allow-Credentials true; if ($request_method OPTIONS) { return 204; }OPTIONS预检请求直接返回 204实际业务请求正常转发前后端联调时的跨域问题在 Nginx 层就消掉了。5. 启动、切换、状态码与日常问题排查5.1 启动、停止、平滑重载Nginx 如何迅速切换配置Nginx 的进程管理命令是每个使用者必须背下来的基本功。常规操作有这么几个# 启动 nginx # 或者 systemctl start nginx # 停止 nginx -s stop # 或者 systemctl stop nginx # 平滑退出 nginx -s quit # 重载配置平滑生效不中断服务 nginx -s reload # 或者 systemctl reload nginx # 检查配置文件语法 nginx -t这里必须强调nginx -s reload和重启的区别。reload 是平滑重载Nginx 的 master 进程会重新读取配置文件然后启动新的 worker 进程再优雅地关闭旧的 worker 进程整个过程不会中断正在处理的请求。所以我平时修改任何配置都是先nginx -t检查语法再nginx -s reload让配置生效生产环境几乎不用 stop 再 start因为这样会短暂中断服务。到了容器环境命令变成了docker exec 容器名 nginx -t和docker exec 容器名 nginx -s reload。要注意的是Docker 容器里没有 systemd所以不能用systemctl直接调用 Nginx 二进制就行。如果改了容器外的宿主机文件发现 reload 后没生效先确认挂载的路径是不是正确映射到了/etc/nginx/conf.d。在 Windows 上迅速切换配置的方式有点特殊因为 Windows 没有信号机制nginx -s reload有时候不生效保险的操作是nginx -s stop再nginx。另外 Windows 下 Nginx 也支持nginx -T命令可以输出完整解析后的配置用来排查 include 引入的配置到底解析成什么样了这个命令在 Linux 下同样适用排查问题时非常好用。5.2 常见状态码含义与处理思路Nginx 返回的状态码是判断问题在哪一层的第一手线索。我整理了一份高频状态码速查表状态码含义典型场景与排查思路200请求成功正常无需处理301永久重定向一般出现在 HTTP 跳 HTTPS 或域名迁移检查 server_name 和 return 指令302临时重定向后端服务返回的跳转检查 Location 头是否符合预期304未修改命中协商缓存浏览器用了本地缓存正常现象400请求语法错误前端发了畸形请求或者请求头太大检查 client_header_buffer_size401未认证需要身份验证检查 auth_basic 或后端认证逻辑403禁止访问权限或防火墙问题检查文件和目录权限、防火墙、禁止 IP 规则404找不到资源路径配置错误、root/alias 混淆、前端 history 路由未配置 try_files499客户端关闭连接后端处理太慢客户端等不及断开重点优化后端响应速度500服务端内部错误后端服务崩溃或配置异常去后端日志里查详细堆栈502网关错误后端服务没启动、端口不通、进程崩溃检查后端进程和网络连通性503服务不可用后端过载或正在重启检查后端健康状态和 max_fails 配置504网关超时后端响应时间超过 proxy_read_timeout调大超时或优化后端我每次排查问题时会先看状态码结合 Nginx 的error.log和后端服务的$upstream_response_time来判断。拿 502 来说先确认后端进程是否存活、端口是否监听、防火墙是否放行按顺序查下来一般都能定位。如果是 504那就是后端真的处理太慢或者 Nginx 到后端的链路有延迟先把proxy_read_timeout调大到 60 秒再看后端日志。5.3 常见问题与排查技巧实录这里整理几个我在实际运维中反复遇到的经典问题每个都是踩过坑之后得出的经验。第一个问题是配置文件修改后 reload 报错。报错信息五花八门但 90% 的原因是语法错误比如漏了分号、括号不匹配、路径写错。解决方式是永远改完配置先跑nginx -t它会提示错误具体在第几行按提示修就行。剩下 10% 是系统问题比如磁盘满了日志写不进去可以用df -h查一下。第二个问题是浏览器强制缓存导致页面不更新。部署了新版本用户访问还是旧页面根因是 index.html 被浏览器缓存了。解决办法是我在前面提到的给 index.html 设置Cache-Control: no-cache静态资源文件名带 hash这样每次发布新版本HTML 都是实时请求引用的 JS/CSS 又是带新 hash 的文件浏览器只会缓存新文件。第三个问题是上传大文件时报 413 Request Entity Too Large。这个错误非常典型Nginx 默认client_max_body_size是 1m超过就报错。在 http、server 或 location 块里加上client_max_body_size 50m;就能解决具体大小根据业务来定同时要确认后端服务的对应参数是否也调整过。第四个问题是 Docker 容器里的 Nginx 修改配置文件不生效。先检查挂载目录是否正确执行docker exec nginx-web ls /etc/nginx/conf.d看看文件是否同步到容器里了再看是否真的 reload 了docker exec nginx-web nginx -s reload执行后没有报错才算成功最后用docker exec nginx-web nginx -T把最终生效的配置打出来看看。这三个步骤走完99% 的不生效问题都能找到端倪。第五个问题是无法访问 Nginx 服务但进程还在。这种情况排查思路是先用curl 127.0.0.1本机测一下通说明 Nginx 没问题问题在防火墙或安全组再检查netstat -tlnp | grep 80看端口是否被占用有时候你改了端口但忘了开防火墙对应的端口也会导致外部无法访问。在云服务器上一定记得检查安全组规则这个是最容易被忽略的。最后再补一个很多人问过的 Tengine 或 TongWeb 和 Nginx 的关系。Tengine 是淘宝基于 Nginx 做的增强版TongWeb 是东方通的应用服务器它俩和原生 Nginx 并不冲突。很多项目里 Nginx 在最外层做流量入口TongWeb 在中间层运行 Java 业务应用Nginx 通过proxy_pass把请求转发给 TongWeb 监听端口这种组合在政企项目里非常常见。我自己这些年用下来最大的体会是 Nginx 的稳定性和灵活性远超过一般人的想象。理解它的核心配置结构和运行机制之后你可以在极短时间内完成一个新站点的上线、一个老项目的流量切换甚至在不过度依赖图形化运维平台的前提下搞定大部分 Web 层治理工作。如果你正在学这个建议手边放一台虚拟机把文章里提到的配置都亲手敲一遍只有真正踩过配置错误的坑才会对每一行配置背后的含义有更深的体感。 Nginx 核心配置实战：从反向代理到负载均衡的完整指南
1. 先搞清楚Nginx到底是什么以及为什么大家都在用它如果你接触过网站部署、接口联调或者任何前后端分离的项目大概率逃不开 Nginx。简单说Nginx 是一个高性能的 HTTP 服务器和反向代理服务器最早由 Igor Sysoev 在 2004 年发布最初就是为了解决 C10K 问题——也就是单机同时处理一万个并发连接的老大难。十几年下来它已经成了互联网架构里的标配组件从静态文件服务、反向代理、负载均衡到 HTTPS 终结、灰度发布、流媒体推流Nginx 几乎样样都能干。我自己最早接触 Nginx 是在一次给客户部署前后端分离项目的时候。前端打包出来的 dist 目录要有人托管后端 Java 服务要有人转发测试环境还要解决跨域问题。当时搜了一圈发现 Nginx 就是干这个的把静态页面直接吐给浏览器把 /api 开头的请求转发给后端服务顺带把跨域、压缩、缓存全部解决掉。从那以后我基本每次部署新项目都会优先考虑 Nginx不管是几台机器的集群还是单机小服务它都能稳稳接住。这篇文章不打算写成官方文档那种逐行翻译的教程而是按照我平时排查问题、部署服务时的真实路径来组织内容。你会看到如何安装 Nginx、如何读懂 nginx.conf 里每一段配置的含义、如何配置反向代理和负载均衡、如何部署前端打包产物、如何排查状态码异常以及一些 Docker 环境下的实用操作。适合刚接触 Nginx 的新手也适合已经会用但想搞清楚原理的运维和开发同学。2. 环境准备不同操作系统和部署方式下的安装方法与取舍2.1 Linux 下的三种安装方式包管理器、源码编译、离线安装Linux 是 Nginx 的主场绝大多数生产环境跑的都是 Linux。安装方式主要看你的网络环境和诉求。最省事的是用系统自带的包管理器。Ubuntu/Debian 系执行apt install nginxCentOS/RHEL 系执行yum install nginx或者dnf install nginx。这种方式装出来的版本可能不是最新的但胜在稳定而且 systemd 服务脚本都给你配好了装完就能systemctl start nginx日志轮转、开机自启这些也都顺手搞定。如果追求最新特性比如 HTTP/3、新的负载均衡指令那就可以去 Nginx 官网添加官方源或者自己编译。源码编译适合需要定制模块的场景。比如你要用 RTMP 模块做直播推流或者要集成一些第三方插件就必须在编译时通过--add-module带进去。编译安装的基本顺序是先装依赖gcc、pcre、zlib、openssl然后解压源码包执行 configure 配置想要的模块最后 make 和 make install。Nginx 默认安装目录是/usr/local/nginx启动文件在/usr/local/nginx/sbin/nginx配置文件在/usr/local/nginx/conf/nginx.conf。离线安装是我在实际项目中经常要面对的场景尤其是银行、政务、内网环境生产机器根本不连外网。这时候提前准备好 RPM 或者 DEB 包就很关键。找一台能联网的同版本系统用yumdownloader或apt download把 Nginx 以及所有依赖包拉下来传到目标机器上再装。依赖树复杂的话可以用yum install --downloadonly --downloaddir/path/to/dir nginx一键把全部依赖包都下载好省得来回折腾。注意离线安装的版本一定要和目标系统的 glibc 版本兼容。之前我遇到过在一台 CentOS 7 的机器上装了在 CentOS 8 上打好的 RPM 包结果直接报version GLIBC_2.18 not found白折腾半小时。2.2 Windows 下的 Nginx本地联调足够用Windows 版的 Nginx 官方一直在发虽然不推荐在生产环境跑但作为本地开发联调工具完全够用。下载 zip 包之后解压nginx.exe就在根目录下。启动方式是直接双击 exe 或者在命令行执行start nginx此时会有一个黑窗口一闪而过不用害怕进程已经起来了。Windows 下有几个坑需要提前知道。一是 Nginx 在 Windows 下是基于原生 Win32 API 跑的性能表现不如 Linux并发高的时候明显吃力所以生产环境别用 Windows 版扛流量。二是路径写法要用正斜杠或者转义反斜杠比如root D:/nginx/html这样。三是配置文件改完之后在 Windows 下执行nginx.exe -s reload有时候会失效最稳的办法是nginx.exe -s stop然后重新start nginx。四是 Windows 版的 Nginx 不支持user指令也不需要配置不然启动直接报错。2.3 Docker 部署最常用的容器化方案与多项目目录挂载现在新项目绝大多数都是容器化部署Nginx 官方在 Docker Hub 上有维护良好的镜像我用的最多的就是nginx:stable-alpine因为 Alpine 基础镜像体积小只有几十 MB而且官方做了精简跑起来内存占用很低。Docker 部署 Nginx 的核心思路是把配置文件、日志、网站根目录全部挂载到宿主机这样容器随便重建数据不丢。我常用的命令大概是这样的docker run -d --name nginx-web \ -p 80:80 -p 443:443 \ -v /data/nginx/conf.d:/etc/nginx/conf.d \ -v /data/nginx/html:/usr/share/nginx/html \ -v /data/nginx/logs:/var/log/nginx \ -v /data/nginx/ssl:/etc/nginx/ssl \ --restartalways \ nginx:stable-alpine这里的-v把四个关键目录挂出来conf.d放站点配置html放静态文件logs放日志ssl放证书。这样你就完全不用进容器改文件了在宿主机上编辑然后执行docker exec nginx-web nginx -s reload就能让新配置生效。多项目目录挂载的路径规划也很重要。我之前在一个网关机器上用单个 Nginx 容器挂了三个前端项目每个项目对应一个 server 块按域名或者端口区分。目录结构是这样的/data/nginx/ ├── conf.d/ │ ├── project-a.conf │ ├── project-b.conf │ └── project-c.conf ├── html/ │ ├── project-a/ # 存放 A 项目打包产物 │ ├── project-b/ # 存放 B 项目打包产物 │ └── project-c/ # 存放 C 项目打包产物 ├── logs/ └── ssl/每个conf.d下的配置文件就是一个完整的 server 块互不干扰新增项目只需要加一个 conf 文件再加一个 html 子目录。这种方式的优点是隔离性好某个项目的配置出问题不会连累其他项目而且排错时只要看对应文件就好。2.4 K8s 集群里的 NginxIngress Controller 与独立 Pod 的取舍K8s 环境里 Nginx 的出场方式有两种。第一种是部署一个独立的 Nginx Pod 作为集群内某个服务的反向代理这种用法本质上就是上面 Docker 部署的 K8s 版只不过用 Deployment 和 Service 管理起来配置挂载用 ConfigMap 或者 PV。第二种是部署 Nginx Ingress Controller让 Nginx 充当整个集群的流量入口配合 Ingress 资源对象实现按域名和路径路由到不同的 Service。如果你是在 K8s 里部署 MySQL 又部署 Nginx我的建议是 Nginx 用 Deployment 跑MySQL 用 StatefulSet 跑因为后者需要稳定的网络标识和持久化存储。至于 Nginx 的配置管理如果只在集群内部用可以直接用 ConfigMap 挂载/etc/nginx/conf.d如果是给外部提供服务的入口那直接用 Nginx Ingress Controller 是更成熟的方案毕竟它本身就针对云原生场景做了很多优化比如自动 watch Service 变化、原生支持 TLS 证书管理、配合 Cert-Manager 可以自动签发续期证书。3. 配置文件详解从整体结构到每个指令的含义3.1 nginx.conf 的五层结构main、events、http、server、location很多初学者第一次打开 nginx.conf 会有点懵里面密密麻麻全是配置项不知道从哪看起。其实 Nginx 的配置是有严格的层级结构的理解了层级关系后面所有配置都能顺下来。最外层是 main 块作用于全局比如user nginx;、worker_processes auto;、error_log /var/log/nginx/error.log;这些它们控制的是进程运行属性和全局日志路径。接着是events块里面的worker_connections 1024;指定每个 worker 进程可以同时维持的最大连接数。然后是http块所有 HTTP 相关的配置都包在这里面比如include /etc/nginx/mime.types;、sendfile on;、keepalive_timeout 65;。在 http 块里可以包含多个server块每个 server 块就是一台虚拟主机用listen指定监听端口用server_name指定匹配的域名。server 块里还可以再嵌套多个location块用来匹配不同的请求路径。用一句话概括main 管全局进程events 管连接模型http 管 HTTP 协议server 管站点location 管路径。这个结构层级一旦清楚你在网上看到的任何一段 Nginx 配置都能快速定位到它属于哪一层改起来也就有方向感了。3.2 最小可用配置 vs 真实生产配置抄作业的正确姿势网上搜 Nginx 配置的时候能看到各种各样的“最全配置”“终极配置”但很多其实不适合新手直接抄。我建议先从一个最小可用的配置入手跑通了再逐步往上加东西。# /etc/nginx/nginx.conf user nginx; worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; server_tokens off; server { listen 80; server_name example.com; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } } }这里有一个非常关键的指令是try_files $uri $uri/ /index.html;如果你部署的是 Vue 或 React 这类单页应用这个配置能解决刷新页面 404 的问题。原理是用户请求/about路径时服务器发现物理上不存在这个文件就尝试找/about/目录还是找不到最后直接返回/index.html让前端路由接管路径解析。生产环境的真实配置会比这个长很多但基本结构是一样的在 http 块里加上 gzip 压缩、静态资源缓存、日志格式定义在 server 块里加上 HTTPS 证书、HTTP 跳转、反向代理、安全响应头在 location 块里根据路径做不同处理。先掌握这个小配置理解每一行再去看复杂的配置就不会一头雾水。3.3 静态资源服务的核心配置与缓存策略Nginx 最初就是做静态文件服务器起家的处理静态资源的效率至今没有多少同类产品能超越。静态资源服务的核心配置主要围绕三件事展开文件路径映射、内容协商、浏览器缓存。文件路径映射用root和alias两个指令。root是追加路径比如location /static/ { root /data/nginx; }请求/static/img/logo.png时实际查找的文件是/data/nginx/static/img/logo.png。alias是替换路径比如location /static/ { alias /data/files/; }请求/static/img/logo.png时实际查找的是/data/files/img/logo.png。两者差别很容易搞混我写的时候都会在注释里标注当前用的是哪种语义。浏览器缓存策略靠的是expires和Cache-Control响应头。对于图片、JS、CSS 这类带版本号的静态资源可以放心让浏览器缓存配置方式就是一行location ~* \.(js|css|png|jpg)$ { expires 30d; add_header Cache-Control public, no-transform; }。对于 index.html 这种首页文件反而要设置为no-cache否则用户上线新版本之后浏览器还拿旧页面就会出现“明明发布了新版本用户却看不到变化”的问题。我通常是给 index.html 单独配一个 location设置add_header Cache-Control no-cache, must-revalidate;配合前端打包时给文件名加 hash 的手段就能做到静态资源缓存和页面即时更新的最佳平衡。3.4 gzip、日志格式与性能调优的常规操作gzip 压缩是性价比最高的性能优化手段开启后传输体积能减少 60% 以上。核心配置是这几行gzip on; gzip_min_length 1k; gzip_comp_level 5; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript image/svgxml; gzip_vary on;gzip_comp_level是压缩等级范围是 1 到 9。等级越高压缩率越高但 CPU 开销也越大。我自己实测下来等级 5 和 9 的压缩率差距可能就 5% 左右但 CPU 占用差很多所以长期保持在 5 是稳妥的选择。另外gzip_min_length 1k表示小于 1KB 的文件不压缩因为压缩这些小文件的收益太低反而浪费 CPU。日志是排查问题的第一手信息来源。生产环境建议用自定义的日志格式把响应时间、请求时长、上游响应时间这些关键指标打出来log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for $request_time $upstream_response_time;$request_time是 Nginx 处理请求的总耗时$upstream_response_time是后端服务响应耗时。两者一对比就能判断瓶颈是在 Nginx 本身还是后端服务。如果$upstream_response_time很大问题大概率在后端如果两者差不多可能是网络链路有损耗如果$request_time大但$upstream_response_time小可能是 Nginx 在等待后端响应或者发生了日志阻塞。worker_processes 和 worker_connections 是影响性能的两个核心参数。worker_processes auto会按照 CPU 核心数自动设置 worker 进程数量。worker_connections决定单个 worker 能同时处理的连接数上限两者相乘就是理论上限。对于常规 Web 服务设置成auto加10240一般就够了不用盲目调大因为超过系统文件描述符限制反而会报错。4. 反向代理与负载均衡实战从单机到集群4.1 反向代理到底是什么和正向代理有什么区别反向代理这个概念很多人刚开始学的时候容易和正向代理搞混。正向代理是帮客户端转发请求比如你在公司内网访问外网流量先经过公司代理服务器再由它去访问互联网客户端知道自己配置了代理。反向代理是帮服务端接收请求客户端不知道请求最终被转发到哪台真实的服务器上。用生活化的例子说正向代理是“你找中介帮你买东西”中介代表你的利益反向代理是“你打电话到公司总机总机帮你转接到具体部门”总机代表公司的利益。对用户来说他访问的永远是你的域名至于这个域名背后是哪台服务器、哪个端口的服务在处理完全是 Nginx 内部的事情。反向代理是 Nginx 最核心的使用场景。一个典型的配置是server { listen 80; server_name api.example.com; location / { proxy_pass http://127.0.0.1:8080; 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; } }proxy_pass指定请求要转发到的后端地址。proxy_set_header的作用是把客户端的原始信息传递到后端这样后端的 Java、Python 或 Node 服务就能拿到真实的用户 IP、协议和 Host。如果后端是 HTTPS 应用还要加上proxy_set_header X-Forwarded-Proto https;否则后端的重定向逻辑可能会把 HTTPS 请求重定向到 HTTP导致死循环。4.2 upstream 负载均衡四种策略与权重配置当后端服务从一台变成多台就需要负载均衡。Nginx 用upstream指令定义一组后端服务器然后在proxy_pass里指向这个组upstream backend_servers { server 192.168.1.10:8080 weight3; server 192.168.1.11:8080 weight1; server 192.168.1.12:8080 backup; } server { listen 80; server_name api.example.com; location /api/ { proxy_pass http://backend_servers; } }Nginx 默认使用轮询策略请求按顺序轮流分发给每台后端。weight参数可以调整权重weight3表示这台机器承担 3/4 的流量backup表示它是备用节点平时不参与分发只有其他节点都挂了才切上去。除了轮询还有三种常用策略ip_hash按客户端 IP 的哈希值分配同一个 IP 的请求永远打到同一台后端解决了需要会话保持的场景least_conn优先分发连接数最少的后端适合后端处理能力不均的情况hash $request_uri按自定义 key 做哈希常用于缓存场景。我在实际项目里最常遇到的问题是 session 失效。如果你的后端架构没有做 session 共享也就是用户登录状态存在单台服务器的内存里那么用了轮询之后用户第一次请求打到 A 服务器登录了第二次请求被分到 B 服务器B 没有他的登录状态就直接踢回登录页了。解决方式要么后端改造做 Redis session 共享要么前端 Nginx 侧用ip_hash保证用户固定访问一台机器。如果后端机器在云环境且出口 IP 不固定ip_hash就不太靠谱建议用sticky模块做基于 Cookie 的会话保持。4.3 HTTPS 配置证书格式、私钥类型与双向认证HTTPS 是现在所有线上业务的标配Nginx 配置 HTTPS 的核心就是改 listen 和证书路径server { listen 443 ssl http2; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com.pem; ssl_certificate_key /etc/nginx/ssl/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; }关于私钥类型Nginx 支持 PEM 格式的 RSA、ECDSA 和 Ed25519 私钥。一般证书提供商给的.key文件就是 PEM 格式直接能用。如果私钥文件是带密码保护的需要先用 openssl 把密码去掉否则 Nginx 启动时会卡住要你输入密码这在生产环境根本没法接受。这里给出两个常用的转换命令openssl rsa -in encrypted.key -out decrypted.key用来去掉 RSA 私钥的密码如果是 ECDSA 私钥把rsa换成ec即可。双向认证在需要极高安全级别的场景下使用比如某些政企系统要求不仅服务端向客户端证明自己客户端也要向服务端证明身份。Nginx 的双向认证配置一般长这样server { listen 443 ssl; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key; # 开启客户端证书验证 ssl_client_certificate /etc/nginx/ssl/ca.crt; ssl_verify_client on; ssl_verify_depth 2; location / { if ($ssl_client_verify ! SUCCESS) { return 403; } proxy_pass http://backend; } }注意这里ssl_client_certificate填的是签发客户端证书的 CA 根证书不是客户端证书本身。ssl_verify_depth控制证书链的验证深度一般 2 就够了。开启双向认证之后没有安装合法客户端证书的浏览器访问会直接报错后端服务就完全不用关心身份认证的问题可以在更受信任的网络环境下对外提供服务。4.4 部署前后端分离项目pnpm run build 的产物怎么用 Nginx 启动这个问题在网站上搜的人非常多说明很多人都卡在了“前端构建产物怎么托管”这一步。用 Vite 或 Webpack 的项目执行pnpm run build或npm run build之后打包产物默认在dist目录下。这个目录里的 index.html 和静态资源需要一个 Web 服务器来托管Nginx 是最合适的角色。完整的前后端分离部署方案前端静态资源由 Nginx 直接返回后端 API 请求通过反向代理转发server { listen 80; server_name front.example.com; # 前端静态资源 location / { root /data/www/frontend/dist; index index.html; try_files $uri $uri/ /index.html; } # 后端 API 反向代理 location /api/ { proxy_pass http://backend_servers; 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; } }这里有一个容易踩的坑proxy_pass后端的地址末尾带不带/效果完全不同。如果不带/请求/api/login会原样转发成http://backend/api/login如果带/请求/api/login会去掉/api前缀再转发变成http://backend/login。很多新手配置完发现接口 404基本都是这个原因。我的习惯是后端接口都统一带/api前缀Nginx 配置里proxy_pass不带斜杠这样转发路径和后端路由一致好排查。另外开发环境常见的跨域问题在 Nginx 层也可以直接解决。如果后端没有开 CORS你可以在反向代理的 location 里加上几个响应头add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS; add_header Access-Control-Allow-Headers Authorization, Content-Type, Accept; add_header Access-Control-Allow-Credentials true; if ($request_method OPTIONS) { return 204; }OPTIONS预检请求直接返回 204实际业务请求正常转发前后端联调时的跨域问题在 Nginx 层就消掉了。5. 启动、切换、状态码与日常问题排查5.1 启动、停止、平滑重载Nginx 如何迅速切换配置Nginx 的进程管理命令是每个使用者必须背下来的基本功。常规操作有这么几个# 启动 nginx # 或者 systemctl start nginx # 停止 nginx -s stop # 或者 systemctl stop nginx # 平滑退出 nginx -s quit # 重载配置平滑生效不中断服务 nginx -s reload # 或者 systemctl reload nginx # 检查配置文件语法 nginx -t这里必须强调nginx -s reload和重启的区别。reload 是平滑重载Nginx 的 master 进程会重新读取配置文件然后启动新的 worker 进程再优雅地关闭旧的 worker 进程整个过程不会中断正在处理的请求。所以我平时修改任何配置都是先nginx -t检查语法再nginx -s reload让配置生效生产环境几乎不用 stop 再 start因为这样会短暂中断服务。到了容器环境命令变成了docker exec 容器名 nginx -t和docker exec 容器名 nginx -s reload。要注意的是Docker 容器里没有 systemd所以不能用systemctl直接调用 Nginx 二进制就行。如果改了容器外的宿主机文件发现 reload 后没生效先确认挂载的路径是不是正确映射到了/etc/nginx/conf.d。在 Windows 上迅速切换配置的方式有点特殊因为 Windows 没有信号机制nginx -s reload有时候不生效保险的操作是nginx -s stop再nginx。另外 Windows 下 Nginx 也支持nginx -T命令可以输出完整解析后的配置用来排查 include 引入的配置到底解析成什么样了这个命令在 Linux 下同样适用排查问题时非常好用。5.2 常见状态码含义与处理思路Nginx 返回的状态码是判断问题在哪一层的第一手线索。我整理了一份高频状态码速查表状态码含义典型场景与排查思路200请求成功正常无需处理301永久重定向一般出现在 HTTP 跳 HTTPS 或域名迁移检查 server_name 和 return 指令302临时重定向后端服务返回的跳转检查 Location 头是否符合预期304未修改命中协商缓存浏览器用了本地缓存正常现象400请求语法错误前端发了畸形请求或者请求头太大检查 client_header_buffer_size401未认证需要身份验证检查 auth_basic 或后端认证逻辑403禁止访问权限或防火墙问题检查文件和目录权限、防火墙、禁止 IP 规则404找不到资源路径配置错误、root/alias 混淆、前端 history 路由未配置 try_files499客户端关闭连接后端处理太慢客户端等不及断开重点优化后端响应速度500服务端内部错误后端服务崩溃或配置异常去后端日志里查详细堆栈502网关错误后端服务没启动、端口不通、进程崩溃检查后端进程和网络连通性503服务不可用后端过载或正在重启检查后端健康状态和 max_fails 配置504网关超时后端响应时间超过 proxy_read_timeout调大超时或优化后端我每次排查问题时会先看状态码结合 Nginx 的error.log和后端服务的$upstream_response_time来判断。拿 502 来说先确认后端进程是否存活、端口是否监听、防火墙是否放行按顺序查下来一般都能定位。如果是 504那就是后端真的处理太慢或者 Nginx 到后端的链路有延迟先把proxy_read_timeout调大到 60 秒再看后端日志。5.3 常见问题与排查技巧实录这里整理几个我在实际运维中反复遇到的经典问题每个都是踩过坑之后得出的经验。第一个问题是配置文件修改后 reload 报错。报错信息五花八门但 90% 的原因是语法错误比如漏了分号、括号不匹配、路径写错。解决方式是永远改完配置先跑nginx -t它会提示错误具体在第几行按提示修就行。剩下 10% 是系统问题比如磁盘满了日志写不进去可以用df -h查一下。第二个问题是浏览器强制缓存导致页面不更新。部署了新版本用户访问还是旧页面根因是 index.html 被浏览器缓存了。解决办法是我在前面提到的给 index.html 设置Cache-Control: no-cache静态资源文件名带 hash这样每次发布新版本HTML 都是实时请求引用的 JS/CSS 又是带新 hash 的文件浏览器只会缓存新文件。第三个问题是上传大文件时报 413 Request Entity Too Large。这个错误非常典型Nginx 默认client_max_body_size是 1m超过就报错。在 http、server 或 location 块里加上client_max_body_size 50m;就能解决具体大小根据业务来定同时要确认后端服务的对应参数是否也调整过。第四个问题是 Docker 容器里的 Nginx 修改配置文件不生效。先检查挂载目录是否正确执行docker exec nginx-web ls /etc/nginx/conf.d看看文件是否同步到容器里了再看是否真的 reload 了docker exec nginx-web nginx -s reload执行后没有报错才算成功最后用docker exec nginx-web nginx -T把最终生效的配置打出来看看。这三个步骤走完99% 的不生效问题都能找到端倪。第五个问题是无法访问 Nginx 服务但进程还在。这种情况排查思路是先用curl 127.0.0.1本机测一下通说明 Nginx 没问题问题在防火墙或安全组再检查netstat -tlnp | grep 80看端口是否被占用有时候你改了端口但忘了开防火墙对应的端口也会导致外部无法访问。在云服务器上一定记得检查安全组规则这个是最容易被忽略的。最后再补一个很多人问过的 Tengine 或 TongWeb 和 Nginx 的关系。Tengine 是淘宝基于 Nginx 做的增强版TongWeb 是东方通的应用服务器它俩和原生 Nginx 并不冲突。很多项目里 Nginx 在最外层做流量入口TongWeb 在中间层运行 Java 业务应用Nginx 通过proxy_pass把请求转发给 TongWeb 监听端口这种组合在政企项目里非常常见。我自己这些年用下来最大的体会是 Nginx 的稳定性和灵活性远超过一般人的想象。理解它的核心配置结构和运行机制之后你可以在极短时间内完成一个新站点的上线、一个老项目的流量切换甚至在不过度依赖图形化运维平台的前提下搞定大部分 Web 层治理工作。如果你正在学这个建议手边放一台虚拟机把文章里提到的配置都亲手敲一遍只有真正踩过配置错误的坑才会对每一行配置背后的含义有更深的体感。