手把手拆解Web技术与Nginx网站部署从底层原理到生产环境实战我接触Nginx差不多有七八年了。最早是在某公司实习时导师扔给我一台服务器说“把前端项目部署上去”我当时连Nginx是什么都不知道只会用npm run build然后打开一个index.html。后来踩过的坑多了才慢慢明白Web技术再怎么花哨最后都要落到“服务器怎么把页面和服务安全、高效地送到用户浏览器里”这件事上。这中间的桥梁绝大多数时候就是Nginx。这篇内容适合以下几类人刚学会HTML/CSS/JavaScript、想把自己的项目上线到服务器上的前端初学者懂后端接口但不太清楚怎么用Nginx做反向代理的后端开发者以及被各种配置指令搞到头大、想系统梳理一遍的运维新手。我会从Web技术的基础链路讲起再一步步带你把Nginx配置完整、跑通静态站点和反向代理最后分享一些生产环境下常用的优化和排错手段。不是纯文档翻译是我自己实操后的经验总结。1. Web技术与部署对象先搞清楚你要部署的是什么1.1 Web技术栈的基本构成一个完整的Web系统往简单了说就是“浏览器输入网址服务器返回内容”。但背后实际跑起来的链条远比这句话复杂。现代Web技术栈通常分为三层前端层浏览器里运行的一切。HTML负责结构CSS负责样式JavaScript负责交互。再往后发展出了Vue、React这类框架但无论框架怎么封装最终浏览器拿到的还是静态资源文件——JS、CSS、图片、字体。服务端层真正处理业务逻辑的地方。典型的是Java的Spring Boot、Python的Django/Flask、Node.js的Express/Koa、Go的Gin等。服务端监听某个端口接收HTTP请求处理数据返回JSON或渲染后的HTML。数据层存储和读取数据常见的是MySQL、PostgreSQL、Redis这些。服务端会去数据层取数据组织成响应返回给前端。这中间有一个很容易被新手忽略的关键点前端静态资源和后端动态服务本质上是两种完全不同的传输对象。静态资源是文件适合用服务器直接读文件、快速返回动态服务是需要计算的必须由后端程序处理。Nginx的厉害之处就是能同时把这两件事都干好。1.2 前端静态资源和后端动态服务我把这两者的区别讲得再直白一点。静态资源请求的特点是高频、无状态、内容固定。比如用户访问首页时加载的logo.png一万个人来访问这个文件的内容都是一样的。Nginx收到这个请求后只需要根据URL路径找到对应的文件然后以最快的速度返回连后端都不用碰。动态服务请求的特点是状态频繁变化、依赖计算和数据库。比如用户登录后请求“我的订单列表”这个请求必须交给后端程序去处理后端查数据库、拼数据、返回JSON。如果让Nginx直接返回一个写死的JSON文件那所有用户看到的数据就都一样了这显然不对。所以一个合理的Nginx配置往往同时包含两种角色当URL匹配静态资源如/static/、/assets/、图片后缀时Nginx自己处理直接返回文件当URL匹配API接口如/api/时Nginx把请求转发给后端服务拿到响应后再还给客户端。这个“转交”的动作在Nginx里叫反向代理。后面我会详细讲。1.3 部署前需要准备哪些东西在动手写Nginx配置之前先把准备工作列一下。省得到时候一会儿缺这个一会儿缺那个一台服务器云服务器或本地虚拟机都可以系统建议用Ubuntu 22.04或Debian 12资料多、坑少。如果只是学习用虚拟机完全够。域名可选学习阶段用IP访问也行。但正式部署一定要有域名因为后面配HTTPS证书时证书要绑定域名。前端构建产物如果你的项目是Vue或React写的记得先执行npm run build生成dist目录。这个目录里的东西就是要部署的静态资源。后端服务可选如果你要部署含后端的完整项目需要把后端程序跑起来确认它在某个端口上监听比如8080。SSH连接工具Windows上用Xshell或TermiusmacOS直接用Terminal即可。这些准备好之后我们就可以开始真正接触Nginx了。2. Nginx是什么为什么网站部署都爱用它2.1 Nginx相比其他Web服务器好在哪市面上的Web服务器不少老牌的有Apache轻量的有Caddy新兴的有CloudFlare的各类边缘服务。但Nginx能成为默认首选主要靠三点。第一是性能。Nginx处理静态文件和并发请求的能力非常强。同样一台低配的1核2G服务器用Apache可能会在高并发下内存飙满用Nginx则可以相对轻松地扛住几千个并发连接。这不是玄学而是架构设计决定的下一节我会展开讲。第二是灵活。Nginx配置里可以让你通过location块精准控制请求的走向。哪个路径返回静态文件哪个路径代理给后端哪个路径需要加访问限制都可以用几行配置搞定。这种灵活性让我在接手各种项目时几乎不需要换服务器。第三是生态成熟。网上关于Nginx的教程、问题排查、配置模板多到看不完。这意味着你遇到任何问题搜一下基本都能找到方案对学习者和一线运维来说这非常重要。2.2 Nginx的核心工作模型事件驱动Nginx为什么快要理解这个问题得先看看传统的Web服务器是怎么工作的。老一代服务器如Apache的prefork模式采用的是“一个进程处理一个连接”的模式。想象一下一个饭店来一个客人就雇一个服务员全程盯着客人多了就得雇几百个服务员人力成本当然爆炸。Nginx采用的事件驱动模型则完全不一样。它用少量的worker进程每个worker能够同时监听成千上万个连接。当某个连接上有数据来了worker就去处理没有数据时就去做别的事情。还是那个饭店这次只保留几个非常高效的服务员他们同时照看很多桌客人哪桌菜上好了就去上菜哪桌要结账就去结账空闲时不会干等着。用官方的话说这叫“异步非阻塞”。具体到配置上你会在nginx.conf里看到worker_processes和worker_connections这两个参数它们分别控制worker进程数和每个worker能打开的最大连接数。实际调优我后面会专门写这里只要记住核心模型就足够了。2.3 Nginx作为反向代理和静态资源服务器的典型角色理解Nginx的角色其实只需要记住两个词静态服务器和反向代理。静态服务器好理解你把前端构建好的dist目录放在服务器的某个路径下Nginx配置一个root指向它。当用户访问http://你的IP/时Nginx自动找到dist/index.html返回给浏览器。反向代理稍微绕一点。正常情况下浏览器直接请求后端服务的地址比如http://服务器IP:8080/api/getUser。但直接暴露端口会有两个问题一是端口管理混乱不同项目占用不同端口用户记不住二是安全性差直接把后端服务暴露给外部容易成为攻击目标。用Nginx做反向代理后结构就变成了这样浏览器 → Nginx443端口 → 后端服务8080端口用户访问的是https://你的域名/api/getUserNginx收到请求后自己转发到http://127.0.0.1:8080/api/getUser拿到后端返回的JSON再原样回给浏览器。用户完全感知不到后端的存在只看到Nginx在对外服务。这样做的好处很多可以做负载均衡、可以统一加HTTPS、可以隐藏内部服务细节。3. 从零开始配置Nginx网站部署3.1 安装与环境准备我用Ubuntu系统举例。登录服务器后先更新一下软件源索引sudo apt update然后安装Nginxsudo apt install nginx -y安装完成后Nginx服务会自动启动。验证一下状态sudo systemctl status nginx如果看到active (running)说明安装成功。这时候你在浏览器里访问服务器IP应该能看到Nginx的默认欢迎页。有些云厂商的安全组默认不放行80端口如果访问不通先去控制台把入方向的TCP 80端口和后面的443端口放行。这一步经常被忽略配置了半天发现是防火墙问题特别浪费时间。我个人的习惯是安装完先看一眼Nginx版本nginx -v不同版本的默认配置路径和指令支持会有细微差别但主流发行版基本都是/etc/nginx/目录。Ubuntu下这个目录里有几个关键文件nginx.conf主配置、sites-available/站点可用配置、sites-enabled/站点启用配置、conf.d/全局配置片段。Ubuntu的这套管理方式非常舒服每个站点一个文件放在sites-available里然后通过软链接到sites-enabled实现启用。比全堆在conf.d里清晰得多。3.2 配置文件的核心结构与常用指令新手打开nginx.conf看到一大片配置往往会懵。我教你先忽略注释只看这些核心块events {} http { server { listen 80; server_name example.com; root /var/www/html; } }理解Nginx配置其实只需要三层结构events块定义全局事件处理属性比如worker_connections。一般很少动。http块所有Web配置都在这里面可以定义多个server。server块一个server就是一个站点。listen指定监听端口server_name指定域名或IProot指定静态文件根目录location则精确控制某个URL路径的行为。我把新手最常用的指令整理了一张表方便对照指令作用示例listen监听端口listen 80;server_name站点域名server_name example.com;root静态文件根目录root /var/www/myapp;index默认首页文件index index.html;locationURL路径匹配块location /api/ { proxy_pass ...; }proxy_pass反向代理目标地址proxy_pass http://127.0.0.1:8080;return直接返回响应码return 301 https://$host$request_uri;配置修改之后先不要急着重启服务。因为Nginx配置写错重启可能导致服务挂掉。正确做法是先测试配置nginx -t看到syntax is ok和test is successful再执行sudo systemctl reload nginx。reload和restart不一样reload会平滑重载配置不会中断正在进行的请求这在生产环境非常重要。3.3 静态网站部署第一个可访问页面假设你已经把项目构建产物上传到了服务器的/var/www/myapp目录目录里有index.html、assets等文件。现在要配置Nginx让它对外服务。在Ubuntu下我推荐在sites-available里新建一个站点文件sudo vim /etc/nginx/sites-available/myapp写入以下配置server { listen 80; server_name _; root /var/www/myapp; index index.html; location / { try_files $uri $uri/ /index.html; } }这里说明几个关键点。server_name _;表示匹配任何域名或IP适合还没有绑域名的场景。root指向项目目录。index定义默认首页。最核心的是这一行try_files $uri $uri/ /index.html;它是什么意思$uri是用户请求的路径。比如用户访问/aboutNginx先尝试找/var/www/myapp/about这个文件。如果找不到再尝试找/var/www/myapp/about/目录。如果还是找不到就回退到/var/www/myapp/index.html。这个配置对前端路由特别重要。因为Vue或React项目里/about、/detail/1这些都是前端由JavaScript处理的路由服务器上根本不存在对应的物理文件。如果不写try_files这一行用户直接访问/about会得到404。加上之后所有找不到的文件都会回到index.html由前端路由接管页面就能正常渲染了。写完之后启用这个站点并重载sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp sudo nginx -t sudo systemctl reload nginx这时候访问http://你的IP/应该就能看到你的前端页面了。第一个Nginx网站部署成功说容易也容易说难也确实有细节。3.4 反向代理部署对接后端服务如果你的项目还有后端接口比如后端跑在127.0.0.1:8080那么前端请求/api时需要交给后端去处理。我们在刚才的配置基础上加一个location块server { listen 80; server_name _; root /var/www/myapp; index index.html; location / { try_files $uri $uri/ /index.html; } 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_pass后面到底要不要带路径比如proxy_pass http://127.0.0.1:8080;和proxy_pass http://127.0.0.1:8080/;有什么区别答案是如果proxy_pass后面不带路径那么Nginx会把完整的原始请求URI传给后端。也就是说前端请求/api/getUser后端收到的也是/api/getUser。如果proxy_pass后面带了路径比如proxy_pass http://127.0.0.1:8080/;那么Nginx会用location匹配到的URI部分替换掉原URI再传给后端——也就是说前端请求/api/getUser后端收到的是/getUser。实际项目中如果前后端约定好了接口路径都带/api前缀那就用不带路径的写法后端接口定义也保持/api/xxx省得乱。如果你后端接口本来就不带/api前缀那可以用带路径的写法做一次“剥掉前缀”的处理。我个人偏好在后端不做前缀处理时用这种写法但大多数时候为了让前后端协调简单会让后端也保留/api前缀然后proxy_pass不带路径。关于反向代理还有三个请求头是必须设置的很多人不写也能跑但生产环境不写会出问题Host $host把浏览器的域名透传给后端。否则后端在生成绝对链接或做域名校验时会拿到127.0.0.1导致各种奇怪问题。X-Real-IP $remote_addr把真实客户端IP告诉后端。否则后端看到的IP永远是Nginx所在服务器的IP也就是127.0.0.1这会导致拿不到用户真实IP、日志统计不准、风控误判。X-Forwarded-For $proxy_add_x_forwarded_for记录完整的代理转发链。如果前面有CDN这个头会累加CDN节点IP和真实IP方便排查链路。顺手再说一个和HTTPS透传有关的配置项。如果你的后端需要通过请求头判断用户只是HTTPS还是HTTP可以在location里加一行proxy_set_header X-Forwarded-Proto $scheme;$scheme是Nginx自动识别的协议如果用户是用HTTPS访问的它就是https。后端拿这个头可以做强制跳转或混合内容判断。3.5 HTTPS与证书配置让网站更安全现在大部分浏览器对未加密的HTTP站点都会默默降低权重甚至某些功能会被拦截。所以给网站配HTTPS已经是部署的默认动作不是可选项。HTTPS的核心是证书。如果你有一个域名我推荐用Let‘s Encrypt免费证书全程自动化90天有效期到期自动续。用什么工具签发首推certbot。安装certbotsudo apt install certbot python3-certbot-nginx -y如果你的Nginx站点已经配置好且能正常通过HTTP访问直接执行sudo certbot --nginx -d 你的域名certbot会自动检测Nginx配置向Let’s Encrypt申请证书并帮你把Nginx配置里的HTTP自动改造成HTTPS还会加上自动续期的定时任务。整个过程基本上不需要手动干预。验证续期任务是否存在sudo systemctl status certbot.timer看到active就说明定时续期已经生效。如果你是全手动流也可以申请证书后手动改Nginx配置。常规的HTTPS server块长这样server { listen 443 ssl; server_name 你的域名; ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem; root /var/www/myapp; index index.html; location / { try_files $uri $uri/ /index.html; } 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; } } server { listen 80; server_name 你的域名; return 301 https://$host$request_uri; }第二个server块的作用是把用户输入的HTTP地址永久重定向到HTTPS。注意这里用的是return 301而不是return 302。301是永久重定向浏览器会缓存以后用户再输HTTP就直接跳HTTPS了302是临时跳转每次都会重新请求。证书文件路径在/etc/letsencrypt/live/你的域名/下fullchain.pem是证书链privkey.pem是私钥。千万别把私钥泄露出去。4. 部署过程中的常见问题与排查方案4.1 端口占用与权限问题Nginx默认跑在80端口上。如果你在启动Nginx时发现提示bind() to 0.0.0.0:80 failed说明80端口已经被占用。最常见的元凶是Apache或者另一个Nginx实例。排查方式sudo netstat -tulpn | grep :80 sudo lsof -i :80看到占用的进程PID后可以确认是哪个程序占的。如果是系统自带的其他Web服务直接停掉并禁止开机自启sudo systemctl stop apache2 sudo systemctl disable apache2还有一个权限类问题新手遇到得也多Nginx的worker进程以www-data用户运行如果站点根目录的权限设置不当比如放在/root下或者目录权限是700Nginx会报Permission denied。解决方式很简单把站点目录放到Nginx能访问的地方然后设置合理的属主sudo chown -R www-data:www-data /var/www/myapp sudo chmod -R 755 /var/www/myapp注意如果你是用部署用户比如ubuntu上传的文件直接把www-data属主改过去可能会导致你以后更新文件不方便。更稳妥的方式是把部署用户加入www-data组然后用775权限。这样上传文件和Nginx读取文件两不耽误。4.2 504/502错误排查思路代理模式下经常碰到两个HTTP错误码502 Bad GatewayNginx连接不上后端服务。504 Gateway TimeoutNginx能连上后端但后端超过Nginx默认的等待时间没返回响应。这两种问题的排查思路我建议按从简到繁按序处理先确认后端服务是不是还活着。用curl http://127.0.0.1:8080/health直接访问一下。如果连不上说明后端根本没起来或者端口配错了。如果通了那问题大概率在Nginx配置上。检查Nginx的proxy_pass地址是不是写错了。比如后端端口从8080换成了9090Nginx里没同步改那必然502。检查后端服务的监听地址。有些后端程序默认只监听127.0.0.1有些监听0.0.0.0。Nginx代理时写127.0.0.1就行但如果你后端的框架比如Django绑定了127.0.0.1:8000那没问题如果绑定的是0.0.0.0:8000Nginx写127.0.0.1:8000也能通。如果502是偶发性的高峰时出现非高峰时正常那多半是后端线程池被占满或者数据库慢查询导致超时。这时候可以适当调大Nginx的代理超时时间location /api/ { proxy_pass http://127.0.0.1:8080; proxy_connect_timeout 10s; proxy_read_timeout 60s; proxy_send_timeout 60s; }proxy_read_timeout是重点。改这个之前要先了解你的后端接口最长可能耗时多久。60秒不够就改成120秒但不能无限调大否则很慢的接口会把后端线程都拖住形成雪崩效应。4.3 缓存与刷新策略部署成功后很多人会在“为什么我更新了前端代码浏览器还是显示旧页面”这个问题上卡住。这其实是缓存策略不合理导致的。当你改了dist里的index.html但index.html里引用的JS和CSS文件名没变比如一直叫app.js浏览器会因为强缓存而继续用旧的app.js。常规解法有两个让前端构建工具给静态文件名加哈希。Vue或React的打包工具默认就会生成如app-7c3f2d.js这样的带哈希文件名。文件内容变了文件名就变了浏览器自然请求新文件。所以如果你发现构建产物文件名不带哈希先检查构建配置。给Nginx配置更精细的缓存控制。对于index.html这种入口文件不要让它缓存对于带哈希的静态资源让它缓存很久。配置示例location / { try_files $uri $uri/ /index.html; } location /assets/ { expires 30d; add_header Cache-Control public, immutable; }注意我这样写的前提是assets目录下的文件都是带哈希的。如果你把不带哈希的文件也放在这个目录发布新版本时就会面临缓存劫持的坑。这里给新手的建议入口HTML不缓存带哈希资源长缓存不带哈希的资源短缓存比如1天。4.4 日志分析从访问日志中找线索Nginx的日志是排查问题最直接的信息源。默认访问日志在/var/log/nginx/access.log错误日志在/var/log/nginx/error.log。遇到接口报错时先看错误日志sudo tail -n 100 /var/log/nginx/error.log如果里面有connect() failed (111: Connection refused)说明后端没起来。如果里面有upstream timed out说明后端响应太慢或卡死。日志里每一行都有具体时间、报错原因和后端地址把这些信息读明白绝大多数问题都能定位。访问日志里的状态码统计也能帮你快速判断网站整体健康度sudo awk {print $9} /var/log/nginx/access.log | sort | uniq -c | sort -rn这个命令会统计最近日志中每个HTTP状态码的数量。如果发现500/502/504特别多说明后端或依赖服务出了大问题如果404很多可能是URL rewrite规则写错了。5. Nginx部署后的性能优化与日常维护5.1 开启Gzip压缩减少传输体积页面加载慢很多时候不是网速问题而是传输体积太大。一个未压缩的JS文件可能有1MBgzip之后能降到200KB左右加载速度自然快好几倍。在http块里开启gzip通常放在/etc/nginx/conf.d/gzip.confgzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript image/svgxml; gzip_min_length 1024; gzip_vary on;这里的逻辑是对指定MIME类型的文件启用压缩小于1024字节的文件不压太小的文件压缩后反而更大。gzip_vary on会在响应头里加Vary: Accept-Encoding让CDN和浏览器正确处理压缩版本和原始版本。开启后可以用curl验证curl -H Accept-Encoding: gzip -I http://你的域名/app.js如果响应头里出现Content-Encoding: gzip说明启用成功。5.2 静态资源缓存策略缓存是提升性能的大杀器。前面我提到过入口HTML和带哈希资源的处理方式这里再给一个更通用的配置建议location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ { expires 30d; add_header Cache-Control public, immutable; }expires 30d会自动生成Expires和Cache-Control: max-age2592000响应头告诉浏览器这个资源可以缓存30天。immutable表示资源内容不变浏览器一旦缓存就不会再向服务器发起任何验证请求。这里提醒一句如果某个目录下的资源不是带哈希的文件名谨慎使用immutable。否则修改了文件内容文件名没变用户还是会加载到旧文件。生产环境中我一般只对构建产物目录开启这种策略其他动态生成的图片接口不做强缓存。5.3 进程与连接数调优Nginx默认配置比较保守如果想在高并发场景下提升吞吐量可以调整这几个参数。在nginx.conf的events块里events { worker_connections 4096; multi_accept on; }worker_connections表示每个worker进程最多能同时处理多少连接。默认值通常是1024。如果你的服务器内存充足上调到4096甚至8192问题不大。在http块里或主配置文件顶部还可以设置worker_processes一般和建议的写法是worker_processes auto;auto让Nginx根据CPU核心数自动决定worker进程数。对于大多数Web服务来说auto就是最优解。设置之后记得测试并reloadsudo nginx -t sudo systemctl reload nginx还有一个容易忽略的参数是系统级的连接限制。如果你的机器上并发连接数很大还可能需要调整ulimit。我在生产环境遇到过进程报Too many open files就是noulimit限制太低造成的。建议把这个值调大只要内存够并发连接数通常越多越好。5.4 配置自动重启与备份生产环境中最怕的事情是什么是服务器重启后Nginx没起来网站挂了没人知道。我给自己的服务器加了一套简单的自愈机制。方法一用systemd管理Nginx。Ubuntu安装Nginx后默认就会注册systemd服务会自动跟随系统启动sudo systemctl is-enabled nginx如果输出enabled说明开机自启已经打开了。方法二加一个定时健康检查脚本。比如每五分钟访问一次本地端口如果失败就恢复*/5 * * * * curl -fsS http://127.0.0.1/ /dev/null || sudo systemctl restart nginx这个方法不能解决所有故障比如后端挂了Nginx也起不来或者是域名解析问题但能在Nginx“意外死亡”时第一时间让它恢复。配置备份同样重要。Nginx的配置改动频繁万一手滑删了一个文件或者改错一行再想恢复就麻烦了。我的习惯是每次改动前先把整份配置打一个带日期的包sudo tar czf ~/nginx-backup-$(date %F).tar.gz /etc/nginx然后把备份包下载到本地或云盘保留最近一个月。实际使用中这个操作救过我很多次尤其是要批量改多个server块的时候。写在最后我在实际配置Nginx的过程中最有感触的一点是大部分问题不是配置写不出来而是对链路理解不够。你只要把“浏览器请求到Nginx、Nginx决定自己处理还是转交后端、后端返回后Nginx再交回浏览器”整条链路在脑子里跑通很多配置项的用途就自己浮出来了。比如为什么要设置Host请求头因为后端需要知道真正的域名。为什么入口HTML不缓存因为要保证用户及时拿到新版本。这些都不是死记硬背的指令而是链路中的一环。最后再分享一个我常用的排查小技巧当你怀疑Nginx配置或者后端接口返回的内容不对劲时直接在服务器上跨过Nginx访问后端再和通过域名访问的结果对比一下# 直接访问后端 curl http://127.0.0.1:8080/api/getUser # 通过域名的HTTPS访问 curl https://你的域名/api/getUser两边的响应体如果有差异差异点往往就是问题所在——要么是Nginx改了请求头或响应头要么是后端的域名校验机制在作祟。这种对比法比对着配置逐行找快得多。Nginx本身不复杂复杂的是它连接起来的Web世界。希望你读完这篇能少走点我之前走过的弯路。如果有拿不准的配置先用nginx -t验证再reload别重启保留好日志它能告诉你所有真相。 
长河君 · 2026/10/18 9:32:01 · 阅读 1.2k Web技术基础与Nginx部署实战：静态资源、反向代理与HTTPS配置详解
手把手拆解Web技术与Nginx网站部署从底层原理到生产环境实战我接触Nginx差不多有七八年了。最早是在某公司实习时导师扔给我一台服务器说“把前端项目部署上去”我当时连Nginx是什么都不知道只会用npm run build然后打开一个index.html。后来踩过的坑多了才慢慢明白Web技术再怎么花哨最后都要落到“服务器怎么把页面和服务安全、高效地送到用户浏览器里”这件事上。这中间的桥梁绝大多数时候就是Nginx。这篇内容适合以下几类人刚学会HTML/CSS/JavaScript、想把自己的项目上线到服务器上的前端初学者懂后端接口但不太清楚怎么用Nginx做反向代理的后端开发者以及被各种配置指令搞到头大、想系统梳理一遍的运维新手。我会从Web技术的基础链路讲起再一步步带你把Nginx配置完整、跑通静态站点和反向代理最后分享一些生产环境下常用的优化和排错手段。不是纯文档翻译是我自己实操后的经验总结。1. Web技术与部署对象先搞清楚你要部署的是什么1.1 Web技术栈的基本构成一个完整的Web系统往简单了说就是“浏览器输入网址服务器返回内容”。但背后实际跑起来的链条远比这句话复杂。现代Web技术栈通常分为三层前端层浏览器里运行的一切。HTML负责结构CSS负责样式JavaScript负责交互。再往后发展出了Vue、React这类框架但无论框架怎么封装最终浏览器拿到的还是静态资源文件——JS、CSS、图片、字体。服务端层真正处理业务逻辑的地方。典型的是Java的Spring Boot、Python的Django/Flask、Node.js的Express/Koa、Go的Gin等。服务端监听某个端口接收HTTP请求处理数据返回JSON或渲染后的HTML。数据层存储和读取数据常见的是MySQL、PostgreSQL、Redis这些。服务端会去数据层取数据组织成响应返回给前端。这中间有一个很容易被新手忽略的关键点前端静态资源和后端动态服务本质上是两种完全不同的传输对象。静态资源是文件适合用服务器直接读文件、快速返回动态服务是需要计算的必须由后端程序处理。Nginx的厉害之处就是能同时把这两件事都干好。1.2 前端静态资源和后端动态服务我把这两者的区别讲得再直白一点。静态资源请求的特点是高频、无状态、内容固定。比如用户访问首页时加载的logo.png一万个人来访问这个文件的内容都是一样的。Nginx收到这个请求后只需要根据URL路径找到对应的文件然后以最快的速度返回连后端都不用碰。动态服务请求的特点是状态频繁变化、依赖计算和数据库。比如用户登录后请求“我的订单列表”这个请求必须交给后端程序去处理后端查数据库、拼数据、返回JSON。如果让Nginx直接返回一个写死的JSON文件那所有用户看到的数据就都一样了这显然不对。所以一个合理的Nginx配置往往同时包含两种角色当URL匹配静态资源如/static/、/assets/、图片后缀时Nginx自己处理直接返回文件当URL匹配API接口如/api/时Nginx把请求转发给后端服务拿到响应后再还给客户端。这个“转交”的动作在Nginx里叫反向代理。后面我会详细讲。1.3 部署前需要准备哪些东西在动手写Nginx配置之前先把准备工作列一下。省得到时候一会儿缺这个一会儿缺那个一台服务器云服务器或本地虚拟机都可以系统建议用Ubuntu 22.04或Debian 12资料多、坑少。如果只是学习用虚拟机完全够。域名可选学习阶段用IP访问也行。但正式部署一定要有域名因为后面配HTTPS证书时证书要绑定域名。前端构建产物如果你的项目是Vue或React写的记得先执行npm run build生成dist目录。这个目录里的东西就是要部署的静态资源。后端服务可选如果你要部署含后端的完整项目需要把后端程序跑起来确认它在某个端口上监听比如8080。SSH连接工具Windows上用Xshell或TermiusmacOS直接用Terminal即可。这些准备好之后我们就可以开始真正接触Nginx了。2. Nginx是什么为什么网站部署都爱用它2.1 Nginx相比其他Web服务器好在哪市面上的Web服务器不少老牌的有Apache轻量的有Caddy新兴的有CloudFlare的各类边缘服务。但Nginx能成为默认首选主要靠三点。第一是性能。Nginx处理静态文件和并发请求的能力非常强。同样一台低配的1核2G服务器用Apache可能会在高并发下内存飙满用Nginx则可以相对轻松地扛住几千个并发连接。这不是玄学而是架构设计决定的下一节我会展开讲。第二是灵活。Nginx配置里可以让你通过location块精准控制请求的走向。哪个路径返回静态文件哪个路径代理给后端哪个路径需要加访问限制都可以用几行配置搞定。这种灵活性让我在接手各种项目时几乎不需要换服务器。第三是生态成熟。网上关于Nginx的教程、问题排查、配置模板多到看不完。这意味着你遇到任何问题搜一下基本都能找到方案对学习者和一线运维来说这非常重要。2.2 Nginx的核心工作模型事件驱动Nginx为什么快要理解这个问题得先看看传统的Web服务器是怎么工作的。老一代服务器如Apache的prefork模式采用的是“一个进程处理一个连接”的模式。想象一下一个饭店来一个客人就雇一个服务员全程盯着客人多了就得雇几百个服务员人力成本当然爆炸。Nginx采用的事件驱动模型则完全不一样。它用少量的worker进程每个worker能够同时监听成千上万个连接。当某个连接上有数据来了worker就去处理没有数据时就去做别的事情。还是那个饭店这次只保留几个非常高效的服务员他们同时照看很多桌客人哪桌菜上好了就去上菜哪桌要结账就去结账空闲时不会干等着。用官方的话说这叫“异步非阻塞”。具体到配置上你会在nginx.conf里看到worker_processes和worker_connections这两个参数它们分别控制worker进程数和每个worker能打开的最大连接数。实际调优我后面会专门写这里只要记住核心模型就足够了。2.3 Nginx作为反向代理和静态资源服务器的典型角色理解Nginx的角色其实只需要记住两个词静态服务器和反向代理。静态服务器好理解你把前端构建好的dist目录放在服务器的某个路径下Nginx配置一个root指向它。当用户访问http://你的IP/时Nginx自动找到dist/index.html返回给浏览器。反向代理稍微绕一点。正常情况下浏览器直接请求后端服务的地址比如http://服务器IP:8080/api/getUser。但直接暴露端口会有两个问题一是端口管理混乱不同项目占用不同端口用户记不住二是安全性差直接把后端服务暴露给外部容易成为攻击目标。用Nginx做反向代理后结构就变成了这样浏览器 → Nginx443端口 → 后端服务8080端口用户访问的是https://你的域名/api/getUserNginx收到请求后自己转发到http://127.0.0.1:8080/api/getUser拿到后端返回的JSON再原样回给浏览器。用户完全感知不到后端的存在只看到Nginx在对外服务。这样做的好处很多可以做负载均衡、可以统一加HTTPS、可以隐藏内部服务细节。3. 从零开始配置Nginx网站部署3.1 安装与环境准备我用Ubuntu系统举例。登录服务器后先更新一下软件源索引sudo apt update然后安装Nginxsudo apt install nginx -y安装完成后Nginx服务会自动启动。验证一下状态sudo systemctl status nginx如果看到active (running)说明安装成功。这时候你在浏览器里访问服务器IP应该能看到Nginx的默认欢迎页。有些云厂商的安全组默认不放行80端口如果访问不通先去控制台把入方向的TCP 80端口和后面的443端口放行。这一步经常被忽略配置了半天发现是防火墙问题特别浪费时间。我个人的习惯是安装完先看一眼Nginx版本nginx -v不同版本的默认配置路径和指令支持会有细微差别但主流发行版基本都是/etc/nginx/目录。Ubuntu下这个目录里有几个关键文件nginx.conf主配置、sites-available/站点可用配置、sites-enabled/站点启用配置、conf.d/全局配置片段。Ubuntu的这套管理方式非常舒服每个站点一个文件放在sites-available里然后通过软链接到sites-enabled实现启用。比全堆在conf.d里清晰得多。3.2 配置文件的核心结构与常用指令新手打开nginx.conf看到一大片配置往往会懵。我教你先忽略注释只看这些核心块events {} http { server { listen 80; server_name example.com; root /var/www/html; } }理解Nginx配置其实只需要三层结构events块定义全局事件处理属性比如worker_connections。一般很少动。http块所有Web配置都在这里面可以定义多个server。server块一个server就是一个站点。listen指定监听端口server_name指定域名或IProot指定静态文件根目录location则精确控制某个URL路径的行为。我把新手最常用的指令整理了一张表方便对照指令作用示例listen监听端口listen 80;server_name站点域名server_name example.com;root静态文件根目录root /var/www/myapp;index默认首页文件index index.html;locationURL路径匹配块location /api/ { proxy_pass ...; }proxy_pass反向代理目标地址proxy_pass http://127.0.0.1:8080;return直接返回响应码return 301 https://$host$request_uri;配置修改之后先不要急着重启服务。因为Nginx配置写错重启可能导致服务挂掉。正确做法是先测试配置nginx -t看到syntax is ok和test is successful再执行sudo systemctl reload nginx。reload和restart不一样reload会平滑重载配置不会中断正在进行的请求这在生产环境非常重要。3.3 静态网站部署第一个可访问页面假设你已经把项目构建产物上传到了服务器的/var/www/myapp目录目录里有index.html、assets等文件。现在要配置Nginx让它对外服务。在Ubuntu下我推荐在sites-available里新建一个站点文件sudo vim /etc/nginx/sites-available/myapp写入以下配置server { listen 80; server_name _; root /var/www/myapp; index index.html; location / { try_files $uri $uri/ /index.html; } }这里说明几个关键点。server_name _;表示匹配任何域名或IP适合还没有绑域名的场景。root指向项目目录。index定义默认首页。最核心的是这一行try_files $uri $uri/ /index.html;它是什么意思$uri是用户请求的路径。比如用户访问/aboutNginx先尝试找/var/www/myapp/about这个文件。如果找不到再尝试找/var/www/myapp/about/目录。如果还是找不到就回退到/var/www/myapp/index.html。这个配置对前端路由特别重要。因为Vue或React项目里/about、/detail/1这些都是前端由JavaScript处理的路由服务器上根本不存在对应的物理文件。如果不写try_files这一行用户直接访问/about会得到404。加上之后所有找不到的文件都会回到index.html由前端路由接管页面就能正常渲染了。写完之后启用这个站点并重载sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp sudo nginx -t sudo systemctl reload nginx这时候访问http://你的IP/应该就能看到你的前端页面了。第一个Nginx网站部署成功说容易也容易说难也确实有细节。3.4 反向代理部署对接后端服务如果你的项目还有后端接口比如后端跑在127.0.0.1:8080那么前端请求/api时需要交给后端去处理。我们在刚才的配置基础上加一个location块server { listen 80; server_name _; root /var/www/myapp; index index.html; location / { try_files $uri $uri/ /index.html; } 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_pass后面到底要不要带路径比如proxy_pass http://127.0.0.1:8080;和proxy_pass http://127.0.0.1:8080/;有什么区别答案是如果proxy_pass后面不带路径那么Nginx会把完整的原始请求URI传给后端。也就是说前端请求/api/getUser后端收到的也是/api/getUser。如果proxy_pass后面带了路径比如proxy_pass http://127.0.0.1:8080/;那么Nginx会用location匹配到的URI部分替换掉原URI再传给后端——也就是说前端请求/api/getUser后端收到的是/getUser。实际项目中如果前后端约定好了接口路径都带/api前缀那就用不带路径的写法后端接口定义也保持/api/xxx省得乱。如果你后端接口本来就不带/api前缀那可以用带路径的写法做一次“剥掉前缀”的处理。我个人偏好在后端不做前缀处理时用这种写法但大多数时候为了让前后端协调简单会让后端也保留/api前缀然后proxy_pass不带路径。关于反向代理还有三个请求头是必须设置的很多人不写也能跑但生产环境不写会出问题Host $host把浏览器的域名透传给后端。否则后端在生成绝对链接或做域名校验时会拿到127.0.0.1导致各种奇怪问题。X-Real-IP $remote_addr把真实客户端IP告诉后端。否则后端看到的IP永远是Nginx所在服务器的IP也就是127.0.0.1这会导致拿不到用户真实IP、日志统计不准、风控误判。X-Forwarded-For $proxy_add_x_forwarded_for记录完整的代理转发链。如果前面有CDN这个头会累加CDN节点IP和真实IP方便排查链路。顺手再说一个和HTTPS透传有关的配置项。如果你的后端需要通过请求头判断用户只是HTTPS还是HTTP可以在location里加一行proxy_set_header X-Forwarded-Proto $scheme;$scheme是Nginx自动识别的协议如果用户是用HTTPS访问的它就是https。后端拿这个头可以做强制跳转或混合内容判断。3.5 HTTPS与证书配置让网站更安全现在大部分浏览器对未加密的HTTP站点都会默默降低权重甚至某些功能会被拦截。所以给网站配HTTPS已经是部署的默认动作不是可选项。HTTPS的核心是证书。如果你有一个域名我推荐用Let‘s Encrypt免费证书全程自动化90天有效期到期自动续。用什么工具签发首推certbot。安装certbotsudo apt install certbot python3-certbot-nginx -y如果你的Nginx站点已经配置好且能正常通过HTTP访问直接执行sudo certbot --nginx -d 你的域名certbot会自动检测Nginx配置向Let’s Encrypt申请证书并帮你把Nginx配置里的HTTP自动改造成HTTPS还会加上自动续期的定时任务。整个过程基本上不需要手动干预。验证续期任务是否存在sudo systemctl status certbot.timer看到active就说明定时续期已经生效。如果你是全手动流也可以申请证书后手动改Nginx配置。常规的HTTPS server块长这样server { listen 443 ssl; server_name 你的域名; ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem; root /var/www/myapp; index index.html; location / { try_files $uri $uri/ /index.html; } 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; } } server { listen 80; server_name 你的域名; return 301 https://$host$request_uri; }第二个server块的作用是把用户输入的HTTP地址永久重定向到HTTPS。注意这里用的是return 301而不是return 302。301是永久重定向浏览器会缓存以后用户再输HTTP就直接跳HTTPS了302是临时跳转每次都会重新请求。证书文件路径在/etc/letsencrypt/live/你的域名/下fullchain.pem是证书链privkey.pem是私钥。千万别把私钥泄露出去。4. 部署过程中的常见问题与排查方案4.1 端口占用与权限问题Nginx默认跑在80端口上。如果你在启动Nginx时发现提示bind() to 0.0.0.0:80 failed说明80端口已经被占用。最常见的元凶是Apache或者另一个Nginx实例。排查方式sudo netstat -tulpn | grep :80 sudo lsof -i :80看到占用的进程PID后可以确认是哪个程序占的。如果是系统自带的其他Web服务直接停掉并禁止开机自启sudo systemctl stop apache2 sudo systemctl disable apache2还有一个权限类问题新手遇到得也多Nginx的worker进程以www-data用户运行如果站点根目录的权限设置不当比如放在/root下或者目录权限是700Nginx会报Permission denied。解决方式很简单把站点目录放到Nginx能访问的地方然后设置合理的属主sudo chown -R www-data:www-data /var/www/myapp sudo chmod -R 755 /var/www/myapp注意如果你是用部署用户比如ubuntu上传的文件直接把www-data属主改过去可能会导致你以后更新文件不方便。更稳妥的方式是把部署用户加入www-data组然后用775权限。这样上传文件和Nginx读取文件两不耽误。4.2 504/502错误排查思路代理模式下经常碰到两个HTTP错误码502 Bad GatewayNginx连接不上后端服务。504 Gateway TimeoutNginx能连上后端但后端超过Nginx默认的等待时间没返回响应。这两种问题的排查思路我建议按从简到繁按序处理先确认后端服务是不是还活着。用curl http://127.0.0.1:8080/health直接访问一下。如果连不上说明后端根本没起来或者端口配错了。如果通了那问题大概率在Nginx配置上。检查Nginx的proxy_pass地址是不是写错了。比如后端端口从8080换成了9090Nginx里没同步改那必然502。检查后端服务的监听地址。有些后端程序默认只监听127.0.0.1有些监听0.0.0.0。Nginx代理时写127.0.0.1就行但如果你后端的框架比如Django绑定了127.0.0.1:8000那没问题如果绑定的是0.0.0.0:8000Nginx写127.0.0.1:8000也能通。如果502是偶发性的高峰时出现非高峰时正常那多半是后端线程池被占满或者数据库慢查询导致超时。这时候可以适当调大Nginx的代理超时时间location /api/ { proxy_pass http://127.0.0.1:8080; proxy_connect_timeout 10s; proxy_read_timeout 60s; proxy_send_timeout 60s; }proxy_read_timeout是重点。改这个之前要先了解你的后端接口最长可能耗时多久。60秒不够就改成120秒但不能无限调大否则很慢的接口会把后端线程都拖住形成雪崩效应。4.3 缓存与刷新策略部署成功后很多人会在“为什么我更新了前端代码浏览器还是显示旧页面”这个问题上卡住。这其实是缓存策略不合理导致的。当你改了dist里的index.html但index.html里引用的JS和CSS文件名没变比如一直叫app.js浏览器会因为强缓存而继续用旧的app.js。常规解法有两个让前端构建工具给静态文件名加哈希。Vue或React的打包工具默认就会生成如app-7c3f2d.js这样的带哈希文件名。文件内容变了文件名就变了浏览器自然请求新文件。所以如果你发现构建产物文件名不带哈希先检查构建配置。给Nginx配置更精细的缓存控制。对于index.html这种入口文件不要让它缓存对于带哈希的静态资源让它缓存很久。配置示例location / { try_files $uri $uri/ /index.html; } location /assets/ { expires 30d; add_header Cache-Control public, immutable; }注意我这样写的前提是assets目录下的文件都是带哈希的。如果你把不带哈希的文件也放在这个目录发布新版本时就会面临缓存劫持的坑。这里给新手的建议入口HTML不缓存带哈希资源长缓存不带哈希的资源短缓存比如1天。4.4 日志分析从访问日志中找线索Nginx的日志是排查问题最直接的信息源。默认访问日志在/var/log/nginx/access.log错误日志在/var/log/nginx/error.log。遇到接口报错时先看错误日志sudo tail -n 100 /var/log/nginx/error.log如果里面有connect() failed (111: Connection refused)说明后端没起来。如果里面有upstream timed out说明后端响应太慢或卡死。日志里每一行都有具体时间、报错原因和后端地址把这些信息读明白绝大多数问题都能定位。访问日志里的状态码统计也能帮你快速判断网站整体健康度sudo awk {print $9} /var/log/nginx/access.log | sort | uniq -c | sort -rn这个命令会统计最近日志中每个HTTP状态码的数量。如果发现500/502/504特别多说明后端或依赖服务出了大问题如果404很多可能是URL rewrite规则写错了。5. Nginx部署后的性能优化与日常维护5.1 开启Gzip压缩减少传输体积页面加载慢很多时候不是网速问题而是传输体积太大。一个未压缩的JS文件可能有1MBgzip之后能降到200KB左右加载速度自然快好几倍。在http块里开启gzip通常放在/etc/nginx/conf.d/gzip.confgzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript image/svgxml; gzip_min_length 1024; gzip_vary on;这里的逻辑是对指定MIME类型的文件启用压缩小于1024字节的文件不压太小的文件压缩后反而更大。gzip_vary on会在响应头里加Vary: Accept-Encoding让CDN和浏览器正确处理压缩版本和原始版本。开启后可以用curl验证curl -H Accept-Encoding: gzip -I http://你的域名/app.js如果响应头里出现Content-Encoding: gzip说明启用成功。5.2 静态资源缓存策略缓存是提升性能的大杀器。前面我提到过入口HTML和带哈希资源的处理方式这里再给一个更通用的配置建议location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ { expires 30d; add_header Cache-Control public, immutable; }expires 30d会自动生成Expires和Cache-Control: max-age2592000响应头告诉浏览器这个资源可以缓存30天。immutable表示资源内容不变浏览器一旦缓存就不会再向服务器发起任何验证请求。这里提醒一句如果某个目录下的资源不是带哈希的文件名谨慎使用immutable。否则修改了文件内容文件名没变用户还是会加载到旧文件。生产环境中我一般只对构建产物目录开启这种策略其他动态生成的图片接口不做强缓存。5.3 进程与连接数调优Nginx默认配置比较保守如果想在高并发场景下提升吞吐量可以调整这几个参数。在nginx.conf的events块里events { worker_connections 4096; multi_accept on; }worker_connections表示每个worker进程最多能同时处理多少连接。默认值通常是1024。如果你的服务器内存充足上调到4096甚至8192问题不大。在http块里或主配置文件顶部还可以设置worker_processes一般和建议的写法是worker_processes auto;auto让Nginx根据CPU核心数自动决定worker进程数。对于大多数Web服务来说auto就是最优解。设置之后记得测试并reloadsudo nginx -t sudo systemctl reload nginx还有一个容易忽略的参数是系统级的连接限制。如果你的机器上并发连接数很大还可能需要调整ulimit。我在生产环境遇到过进程报Too many open files就是noulimit限制太低造成的。建议把这个值调大只要内存够并发连接数通常越多越好。5.4 配置自动重启与备份生产环境中最怕的事情是什么是服务器重启后Nginx没起来网站挂了没人知道。我给自己的服务器加了一套简单的自愈机制。方法一用systemd管理Nginx。Ubuntu安装Nginx后默认就会注册systemd服务会自动跟随系统启动sudo systemctl is-enabled nginx如果输出enabled说明开机自启已经打开了。方法二加一个定时健康检查脚本。比如每五分钟访问一次本地端口如果失败就恢复*/5 * * * * curl -fsS http://127.0.0.1/ /dev/null || sudo systemctl restart nginx这个方法不能解决所有故障比如后端挂了Nginx也起不来或者是域名解析问题但能在Nginx“意外死亡”时第一时间让它恢复。配置备份同样重要。Nginx的配置改动频繁万一手滑删了一个文件或者改错一行再想恢复就麻烦了。我的习惯是每次改动前先把整份配置打一个带日期的包sudo tar czf ~/nginx-backup-$(date %F).tar.gz /etc/nginx然后把备份包下载到本地或云盘保留最近一个月。实际使用中这个操作救过我很多次尤其是要批量改多个server块的时候。写在最后我在实际配置Nginx的过程中最有感触的一点是大部分问题不是配置写不出来而是对链路理解不够。你只要把“浏览器请求到Nginx、Nginx决定自己处理还是转交后端、后端返回后Nginx再交回浏览器”整条链路在脑子里跑通很多配置项的用途就自己浮出来了。比如为什么要设置Host请求头因为后端需要知道真正的域名。为什么入口HTML不缓存因为要保证用户及时拿到新版本。这些都不是死记硬背的指令而是链路中的一环。最后再分享一个我常用的排查小技巧当你怀疑Nginx配置或者后端接口返回的内容不对劲时直接在服务器上跨过Nginx访问后端再和通过域名访问的结果对比一下# 直接访问后端 curl http://127.0.0.1:8080/api/getUser # 通过域名的HTTPS访问 curl https://你的域名/api/getUser两边的响应体如果有差异差异点往往就是问题所在——要么是Nginx改了请求头或响应头要么是后端的域名校验机制在作祟。这种对比法比对着配置逐行找快得多。Nginx本身不复杂复杂的是它连接起来的Web世界。希望你读完这篇能少走点我之前走过的弯路。如果有拿不准的配置先用nginx -t验证再reload别重启保留好日志它能告诉你所有真相。