以前带前端项目上线最怕听到的一句话是“你那个服务挂了”。排查半天发现是后端进程直接暴露在公网扛不住并发或者前端静态资源加载慢得像老牛拉车。后来我把Nginx纳入所有Web全栈项目的标配之后这些烦恼一下少了大半。这篇东西就是我从零开始部署Nginx、把它揉进实际业务的完整记录包括安装选型、配置逻辑、反向代理、负载均衡和上线前必须做的安全检查所有内容都来自真实项目和踩过的坑适合刚接触部署、或者准备把项目从开发机挪到服务器的朋友直接照着操作。1. 先说清楚一件事Nginx在Web全栈项目里到底扮演什么角色1.1 为什么放着好好的后端服务不用非要加Nginx很多刚开始写全栈项目的朋友会有个疑问我的后端是Golang、Node.js或者Java它们自己都能监听端口处理请求为什么还要在外面套一层Nginx我最初也这么想直到把一个Vue3 Golang项目部署到阿里云服务器上直接用Gin框架监听8080端口提供服务结果遇到三个问题第一前端打包后的静态文件没有合适的服务程序总不能写个Go代码专门读HTML返回第二浏览器直接访问8080端口跨域问题立刻冒出来前端调API各种报错第三单台后端进程一旦重启或者崩溃整个站点就不可用了。Nginx的存在就是把这三件事统一接管静态文件由它来读写动态API请求由它转发给后端程序多台后端机器的流量调度也由它完成。它做的事情用一句话概括就是“入口调度员”所有外部请求先进Nginx再由它决定是直接返回文件还是转交给后端的某个服务。1.2 静态文件、反向代理、负载均衡三种能力一个进程全包用一个实际场景来理解你的项目由前端工程和后端工程组成前端跑在9000端口后端跑在8080端口。如果没有Nginx用户就得记两个地址还要处理跨域。有了Nginx之后统一对外暴露80端口当请求路径是/、/index.html、/assets/xxx.js这些静态资源时Nginx直接去服务器磁盘上找文件返回不需要后端介入。当请求路径以/api/开头时Nginx把请求转发给后端的localhost:8080拿到结果再返回给前端。当后端部署了两台机器、需要分摊压力时Nginx按照配置的策略把请求轮流分给不同节点。这三种能力是Nginx这个进程本身自带的不需要额外装插件。高并发场景下它能保持很低的资源占用靠的是事件驱动的异步架构一个worker进程能同时处理成千上万个连接所以即使你的后端服务没做太复杂的优化前面的Nginx也能先把流量稳稳接住。1.3 和Caddy、Apache比Nginx为什么依然是首选市面上做反向代理的工具不少比如Apache、Caddy、Traefik。Apache配置稍显笨重动态模块加载方式在流量大的时候性能调优比较费劲Caddy主打配置简单、自动HTTPS但生态和文档规模不如NginxTraefik跟容器编排绑定紧密偏向Kubernetes环境。国内主流的生产环境里Nginx的出镜率最高网上能搜到的案例、报错解决方案、结合云服务器的教程数量都远多于其他几个。对普通全栈开发者来说选Nginx不是因为它最先进而是因为它信息密度最高踩坑时更容易找到前人的经验。等到你真正掌握了Nginx的配置逻辑再去接触Caddy或Traefik会发现一通百通。2. 安装前先把三条路线摆出来少走半年弯路2.1 包管理器安装最快也最适合新手我第一台服务器装Nginx用的就是系统包管理器Linux发行版各有各的包管理器Ubuntu和Debian用aptCentOS和Rocky Linux用yum或dnf# Ubuntu / Debian sudo apt update sudo apt install nginx -y # CentOS / Rocky Linux / AlmaLinux sudo dnf install nginx -y装完之后Nginx会自己注册成系统服务直接启动就行sudo systemctl start nginx sudo systemctl enable nginx浏览器访问服务器IP看到Welcome to nginx的欢迎页就说明成功了。这种安装方式的优点是省心所有依赖、初始化脚本、日志目录都帮你安排好了连开机自启都写进了systemd。缺点是版本可能不是最新的但生产环境恰恰需要保守稳定版足够用。2.2 Docker跑一个Nginx适合快速验证和隔离环境如果你的服务器上已经装了Docker或者希望测试环境跟宿主机的系统环境完全隔离那就用Docker的方式docker run -d --name nginx-web \ -p 80:80 \ -p 443:443 \ -v /srv/nginx/html:/usr/share/nginx/html \ -v /srv/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \ nginx:stable这里把宿主机的/srv/nginx/html目录挂载到容器内的HTML目录把宿主机的一份nginx.conf挂载进去这样不需要进入容器就能改配置。--name给了容器一个固定名字重启时好操作。Docker方式的优势是干净想换版本一个命令就能重新起容器不需要担心污染系统环境。缺点是网络模型在端口转发、容器间通信时稍微绕一点初学者可能会觉得日志查看不如直接看文件方便。我的习惯是本地折腾测试用Docker生产服务器用系统包管理器。2.3 源码编译确实麻烦但某些场景绕不开源码编译安装适合要加特殊模块、或者系统特别精简的场景。比如需要集成nginx-rtmp-module做流媒体或者需要某些第三方模块包管理器版本不带时就得走源码编译。# 下载Nginx稳定版源码 wget https://nginx.org/download/nginx-1.26.2.tar.gz tar -zxvf nginx-1.26.2.tar.gz cd nginx-1.26.2 # 配置编译选项prefix指定安装路径 ./configure --prefix/usr/local/nginx \ --with-http_ssl_module \ --with-http_gzip_static_module \ --with-stream make sudo make install编译完成后可执行文件在/usr/local/nginx/sbin/nginx配置目录在/usr/local/nginx/conf/。最大的坑是编译需要装好gcc、pcre、zlib等依赖缺一个就卡住sudo apt install build-essential libpcre3-dev libssl-dev zlib1g-dev -y源码安装的进程不会自动注册为systemd服务要么手动写一个service文件要么直接用/usr/local/nginx/sbin/nginx启停。我一般不建议新手上来就编译除非确实有特殊模块需求。2.4 三个方案怎么选我的建议把选择标准列出来对照一下安装方式难度适合场景注意事项包管理器低大部分生产环境、新手入门版本保守但稳定Docker中快速验证、测试环境注意端口映射和挂载目录源码编译高需要自定义模块依赖多、维护成本高如果让我推荐一条路第一台服务器用包管理器安装先跑通业务等熟悉了再考虑要不要用Docker统一管理。源码编译除非有硬性需求否则放到后期再说。3. 动手写第一个server块把静态站点跑起来3.1 nginx.conf的分层结构懂了这个就懂了一半用一句话概括Nginx配置文件的组织方式外面是全局配置中间是events事件模型里面是http块http块里挂着server虚拟主机server里再挂location路由匹配。我习惯用一个类比帮助记忆nginx.conf是一座大厦的物业中心。main上下文是整个物业的管理条例events是安保系统的接线方式http是楼里所有住户的公共规约每个server是一户人家的门牌号每个location是这户人家里不同房间的功能划分。默认配置文件一般长这样user nginx; worker_processes auto; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; } } }不要被这么多行吓到真正需要经常动的就是server和location这两层。全局的worker_processes和events块默认配置通常够用改动优先级可以放得很低。3.2 手写你的第一个server块这里我带你实际操作一遍。先把你的项目打包好前端项目的构建产物一般是一个dist目录里面有index.html和静态资源文件夹。在服务器上建一个目录把dist里的内容传上去sudo mkdir -p /var/www/my-site sudo cp -r ./dist/* /var/www/my-site/然后写一个干净的server块放到/etc/nginx/conf.d/my-site.confserver { listen 80; server_name your-domain.com; root /var/www/my-site; index index.html; location / { try_files $uri $uri/ /index.html; } }try_files $uri $uri/ /index.html这一行是关键。它的意思是先找有没有对应该路径的真实文件再找有没有对应的目录都找不到就把请求交给/index.html。这个写法专门适配Vue、React这种单页应用因为前端路由用的是history模式用户直接刷新/about页面时服务器上并不存在这个物理文件必须由index.html接管再由前端脚本渲染出对应页面。3.3 改完配置先别急着reload养成nginx -t的习惯我见过不少同事改完nginx.conf直接systemctl restart nginx结果配置里一个分号漏写了整个服务起不来在线业务全断。正确流程必须是先检查语法再重载sudo nginx -t它会输出这样一段结果nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful看到syntax is ok之后再用sudo systemctl reload nginx重载配置。reload和restart有本质区别reload是平滑重载不需要中断正在处理的请求生产环境尽量用reload而不是restart。3.4 几个静态文件相关的性能开关静态站点跑起来之后可以顺手开几个默认配置里没有但是很有效的参数它们都在http块里设置sendfile on; tcp_nopush on; tcp_nodelay on; gzip on; gzip_comp_level 5; gzip_types text/plain text/css application/javascript application/json image/svgxml;sendfile把这个文件读取过程从用户态切换到内核态减少拷贝次数静态文件响应速度会有明显提升。tcp_nopush和tcp_nodelay调整TCP数据包的发送策略让网络传输更高效。gzip对文本类资源压缩效果非常明显JS和CSS文件经常能压缩掉一半以上体积。4. 前后端分离项目反向代理的写法与踩坑记录4.1 反向代理的工作方式一句话讲明白反向代理的概念对新手来说容易理解关键在于反向两个字。一般的代理服务器帮客户端访问外部资源称为正向代理放在服务器侧帮内部后端程序接收外部请求就是反向代理。用户的请求到达Nginx后Nginx再把请求转发给后端的某台机器拿到响应再还给用户。对用户来说他只跟Nginx打交道后端机器的真实地址被藏起来了。4.2 Vue Golang 的典型代理配置现在把前端静态站点的server块扩展一下加入接口转发逻辑。假设后端Gin服务跑在本机8080端口server { listen 80; server_name your-domain.com; root /var/www/my-site; index index.html; # 静态资源直接返回文件 location /assets/ { expires 7d; add_header Cache-Control public, no-transform; } # 后端API转发 location /api/ { 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; } # 单页应用路由回退 location / { try_files $uri $uri/ /index.html; } }这样前端页面里的请求路径如果是/api/loginNginx会原样转发到http://127.0.0.1:8080/api/login后端不用做任何路径适配。请求头里的X-Real-IP和X-Forwarded-For是让后端能拿到用户的真实IP因为经过Nginx转发后直接读remote_addr拿到的永远是Nginx的地址。4.3 最容易翻车的proxy_pass结尾斜杠代理配置里最坑的一个细节就是proxy_pass后面到底要不要加斜杠。关键在于它直接影响转发路径是否带上location匹配的前缀不加斜杠location /api/ { proxy_pass http://127.0.0.1:8080; } # /api/user 转发给后端 /api/user加了斜杠location /api/ { proxy_pass http://127.0.0.1:8080/; } # /api/user 转发给后端 /user如果你是后端的接口路径是/users前端请求是/api/users那proxy_pass就不能带斜杠否则后端收到的路径是/users但接口定义是/api/users直接404。我实际开发中因为这个问题排查了一下午最后用nginx -t加日志才定位到非常典型。4.4 一个WebSocket代理把实时通信也接进来全栈项目碰到即时通信、实时通知是常事比如用WebSocket做聊天室或者消息推送。Nginx代理WebSocket有一些额外的参数必须配置否则连接会被切断location /ws/ { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; }Upgrade和Connection这两个请求头是WebSocket建立连接的关键握手信息少了它浏览器会发现连接一直连不上或者连上就断。proxy_read_timeout也要调大默认60秒的话心跳间隔稍长就会被Nginx当作超时才掉连接。4.5 跨域问题Nginx这边还能再推一把很多前端新手被跨域折磨过微信公众号里已经讲了不少方案这里只说Nginx能做的事情。如果你的前端域名是a.com后端接口用了另一个域名b.com浏览器会拦截跨域请求。在Nginx的API代理配置里加上几个响应头就能解决location /api/ { proxy_pass http://127.0.0.1:8080; add_header Access-Control-Allow-Origin https://a.com always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers Authorization, Content-Type, X-Requested-With always; if ($request_method OPTIONS) { return 204; } }OPTIONS预检请求直接返回204不需要转发给后端。always关键字保证即使后端返回错误响应这些头也会加上。5. 多台后端一起扛流量upstream的三种策略怎么选5.1 先在upstream里定义后端节点池当单台后端撑不住流量或者需要做高可用时就在Nginx层先把后端节点定义为一个组这个组在Nginx里叫upstreamupstream backend_servers { server 127.0.0.1:8080; server 10.0.0.2:8080; server 10.0.0.3:8080; } server { listen 80; server_name your-domain.com; location /api/ { proxy_pass http://backend_servers; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }注意这里proxy_pass指向的是backend_servers这个名字后面不需要加端口因为端口在upstream里的server指令中已经指定了。5.2 轮询带权重照顾性能不同的机器默认情况下Nginx用轮询策略每个请求依次分配给不同节点。但如果你有一台高配机器和一台低配机器想让高配的多承担一些请求就给每台机器加weight权重upstream backend_servers { server 127.0.0.1:8080 weight3; server 10.0.0.2:8080 weight1; server 10.0.0.3:8080 weight1; }请求分配比例大约是3:1:1Nginx按照权重随机选择而不是严格的轮流来所以短时间内的分布不是绝对均等但总趋势符合权重。5.3 ip_hash让Session不再到处乱跑如果你的后端服务用了本地Session也就是登录状态存在某台机器内存里请求一旦被分到另一台机器就会丢失登录态。这时候需要ip_hash策略让同一用户的请求固定打到同一台后端upstream backend_servers { ip_hash; server 127.0.0.1:8080; server 10.0.0.2:8080; }ip_hash按客户端IP的哈希值做取模通常多个请求都会落在同一节点上。当然如果用户数量极少且IP不多会发现请求集中在某一台机器上这是哈希取模的正常现象流量足够大之后分布会均匀。5.4 least_conn与健康检查动态感知后端状态当每个请求的处理时长差异很大时轮询和ip_hash都不够智能least_conn会优先把请求分给当前连接数最少的节点适合长连接或者耗时接口较多的场景upstream backend_servers { least_conn; server 127.0.0.1:8080; server 10.0.0.2:8080; }Nginx默认没有主动健康检查模块它靠max_fails和fail_timeout做被动判断upstream backend_servers { server 127.0.0.1:8080 max_fails3 fail_timeout30s; server 10.0.0.2:8080 max_fails3 fail_timeout30s; }意思是30秒内请求某台节点失败3次就把这台标记为不可用30秒后再重新试探。这个配置在生产环境几乎是必写的否则某台后端崩溃后Nginx还会继续往它转发请求。6. 上线前这一圈检查做完才敢把配置扔到生产6.1 用免费证书把HTTP升级成HTTPS现在浏览器对HTTP站点已经不太友好了很多新特性函数在非安全上下文里不可用。配置HTTPS我推荐用免费证书方案比如Let’s Encrypt搭配Certbot工具自动申请、自动续期sudo apt install certbot python3-certbot-nginx -y sudo certbot --nginx -d your-domain.comCertbot会自动修改Nginx配置把listen 80扩展成443并加上SSL证书路径还会自动配置重定向。它的默认配置已经很合理自动续期任务也会装好。如果不想用Certbot也可以手动写HTTPS的server块server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; root /var/www/my-site; index index.html; location / { try_files $uri $uri/ /index.html; } } server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }ssl_protocols TLSv1.2 TLSv1.3这是禁用已经不安全的旧版TLS。return 301那个server块负责把所有HTTP流量强制跳到HTTPS用户输入http://域名也会自动变成https://域名。6.2 gzip压缩页面体量瞬间小一半很多静态站点了不起问题就出在没开压缩。一个几百KB的JS文件gzip后可能只有100多KB网络传输时间少一大截。生产环境用这个组合比较保险gzip on; gzip_comp_level 6; gzip_min_length 1k; gzip_buffers 16 8k; gzip_http_version 1.1; gzip_types text/plain text/css application/json application/javascript application/xml image/svgxml;gzip_min_length 1k小于1KB的文件不压缩因为压缩本身的CPU开销可能比传输还贵。gzip_http_version配1.1兼容性最好。6.3 静态资源的Cache-Control缓存头打包产物文件名通常带hash比如app.8f3a2b.js文件名一变就说明内容变了这类资源完全可以让浏览器缓存很久。配合上面说过的location设置location /assets/ { expires 30d; add_header Cache-Control public, immutable; } location /index.html { add_header Cache-Control no-cache; }index.html不能强缓存因为它每次都要检查有没有新版本no-cache的意思是浏览器每次都会向服务器确认但服务器返回304时不重复下载内容。而带hash的静态资源用immutable表示这个文件永远不会变浏览器连重新验证都省了。6.4 学会看日志才是真正开始懂NginxNginx默认的访问日志和错误日志在/var/log/nginx/目录下排查问题时这两个文件比任何工具都直接。# 查看最近20条错误日志 sudo tail -n 20 /var/log/nginx/error.log # 实时跟踪访问日志 sudo tail -f /var/log/nginx/access.log我曾经遇到过前端页面能打开但接口全部超时的情况一看错误日志发现里面刷满了upstream timed out定位到后端接口确实响应慢增加proxy_read_timeout后问题消失。如果当时不看日志只盯着代码找问题恐怕到第二天也找不着原因。项目访问量稳定后建议把日志按天切分避免单个文件无限膨胀。安装logrotate并确保Nginx日志有独立配置sudo cat /etc/logrotate.d/nginx6.5 常见的启动失败与502/504排查经验配置Nginx过程中有几个报错频率极高我给出排查顺序第一个nginx: [emerg] bind() to 0.0.0.0:80 failed说明80端口被占用。跑一下sudo lsof -i:80看看是哪个进程占用了端口可能是Apache或者其他Web服务停掉冲突进程再启动Nginx。第二个connect() failed (111: Connection refused)Nginx能启动但转发给后端时连接被拒绝。先确认后端服务有没有启动比如直接访问curl http://127.0.0.1:8080看通不通再检查监听地址是不是只绑了localhost或0.0.0.0。第三个upstream timed out while reading response headerNginx等后端响应超时。优先检查后端接口逻辑有没有死循环或慢SQL再决定要不要调整proxy_read_timeout。第四个Permission denied经常出现在Nginx读取静态文件时。检查路径权限Nginx的worker进程是以nginx用户运行的需要保证/var/www/my-site目录对nginx用户有r-x权限sudo chown -R nginx:nginx /var/www/my-site sudo chmod -R 755 /var/www/my-site第五个修改配置后reload报[emerg] unknown directive九成是配置文件里漏了分号或者引号没闭合。这时候nginx -t的输出会精确告诉你在第几行出错直接打开文件看那一行就行。写到这里Nginx从零部署的路径差不多完整了。安装方式选最简单的包管理器先跑通静态站点再加反向代理再多机负载均衡最后补上安全和性能配置这个顺序和项目成长阶段是完全贴合的。凭我个人的经验Nginx配置不像写业务代码那样每行都充满逻辑它更像堆积木基础模块就那些关键是要理解每一块在请求链路里的位置。你自己动手配一个前后端分离项目把静态文件、API转发、日志这三个基本盘跑顺之后后面加SSL、加缓存、加负载均衡都是水到渠成的事。