Nginx + HTTPS 部署问题分析与解决

记录时间2026-09-06 涉及环境阿里云 ECSUbuntu/ nginx 1.24.0 / Spring Boot:8080/ Vite 前端---## 1. 问题现象本次一共经历了两个阶段的问题表象不同但根子都在服务器上的 nginx 配置/文件与预期不一致1. **前端改动部署后页面无变化**- 本地已重新构建 dist上传后浏览器刷新仍是旧页面。2. **配置 SSL443后后端接口不加载**- 按模板新增 hpxwind.top 站点并启用 HTTPS 后网页静态资源正常但所有 /api/** 请求返回 404 Not Foundnginx 报错页后台数据全部加载不出来。---## 2. 排查过程### 2.1 阶段一部署后无变化的定位| 步骤 | 操作 | 结论 ||---|---|---|| 1 | 对比本地 dist 产物与 src 源码的修改时间 | dist 构建时间晚于源码改动本地产物是新的 || 2 | npm run build 重新构建 | 产物 hash 与上次**完全相同**index-QZznvyml.js说明此前删除的孤儿组件从未进过 bundle本地产物确实已包含全部 UI 改动 → **问题不在本地代码** || 3 | 服务器 curl -s http://127.0.0.1/ 抓首页引用的资源名 | 返回 index-s5MNAjZ0.js旧 hash本地最新为 index-QZznvyml.js → **服务器上的文件是旧的** || 4 | nginx -T 查看生效配置 | root /var/www/hpxblog指向旧目录 |**关键结论**本地构建产物正确问题出在服务器端nginx root 指向的目录内容过期/被删未指向最新上传的 dist。### 2.2 阶段二配置 SSL 后后端不加载的定位新增的 SSL 站点配置模板得来包含以下致命缺陷1. root /var/www/hpxwind; —— 是模板遗留路径注释写招新网页存放路径并非真实前端目录。2. **缺失 /api 反向代理** —— 前端所有请求都走 /api/**没有反代时 nginx 把它当静态文件查找必然 404。3. try_files $uri $uri/ 404; —— 没有 SPA 回退 /index.html深层路由直接访问会 404。随后验证到的实际报错与事实bash# nginx -t 报错当前 nginx 不支持新语法nginx: [emerg] unknown directive http2 in /etc/nginx/sites-enabled/hpxwind.top:11nginx: configuration file /etc/nginx/nginx.conf test failedbash# 后端本身是正常的直连 :8080 返回 JSONcurl -s http://127.0.0.1:8080/api/public/settings# {siteTitle:我的博客, ...}# HTTPS 页面正常接口 404curl -sk https://127.0.0.1/ | grep -o assets/index-[^]* # index-QZznvyml.js ✓curl -sk https://127.0.0.1/api/public/settings # nginx 404 ✗ 注意nginx -t 失败时 systemctl reload nginx 不会生效服务器仍跑着**旧配置**会加剧排查困扰。---## 3. 根因汇总| # | 根因 | 说明 ||---|---|---|| 1 | root 指错目录 | 指向模板遗留的 /var/www/hpxwind真实前端产物在 /home/ubuntu/hpxblog/frontend || 2 | 缺少 /api 反代 | nginx 未把 /api/** 转发到 Spring Boot 127.0.0.1:8080接口全部 404 || 3 | http2 语法不兼容 | 本机 nginx 为 **1.24.0**不支持 http2 on;≥1.25.1 才支持需用 listen 443 ssl http2; || 4 | 无 SPA 回退 | try_files ... 404 使前端路由直接访问 404 || 5 | reload 未生效的假象 | nginx -t 失败后 reload 静默无效运行中的仍是旧配置 |---## 4. 解决方案最终生效配置完整替换 /etc/nginx/sites-available/hpxwind.topnginx# ---------- HTTP 80 → HTTPS ----------server {listen 80;server_name hpxwind.top www.hpxwind.top;return 301 https://$host$request_uri;}# ---------- HTTPS 443 主站 ----------server {listen 443 ssl http2; # nginx 1.25.1 用此写法 1.25.1 可拆成 listen 443 ssl; http2 on;server_name hpxwind.top www.hpxwind.top;ssl_certificate /etc/nginx/cert/hpxwind.top.pem;ssl_certificate_key /etc/nginx/cert/hpxwind.top.key;ssl_session_cache shared:SSL:1m;ssl_session_timeout 5m;ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;ssl_prefer_server_ciphers on;# 前端静态产物根目录里面必须直接有 index.html 和 assets/root /home/ubuntu/hpxblog/frontend;index index.html;# -------- 后端 API / 上传文件反代到 Spring Boot :8080 --------location /api/ {proxy_pass http://127.0.0.1:8080; # 不带 URI无尾斜杠保留 /api 前缀原样转发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_read_timeout 60s;}location /avatars/ {proxy_pass http://127.0.0.1:8080;proxy_set_header Host $host;}location /images/ {proxy_pass http://127.0.0.1:8080;proxy_set_header Host $host;}# 缓存策略index.html 不强缓存hash 资源可长缓存location /index.html { add_header Cache-Control no-cache, no-store, must-revalidate; }location /assets/ { expires 30d; add_header Cache-Control public, immutable; }# SPA 路由回退重要location / {try_files $uri $uri/ /index.html;}}启用并重载bashln -sf /etc/nginx/sites-available/hpxwind.top /etc/nginx/sites-enabled/hpxwind.topnginx -t systemctl reload nginx若报 duplicate server_name说明旧的 80 站点配置仍在 sites-enabled停用旧文件后再重载。---## 5. 验证清单全部通过即部署成功bash# 1) 后端在跑ss -lntp | grep 8080# 2) HTTPS 页面返回最新产物hash 与本地 dist 一致curl -sk https://127.0.0.1/ | grep -o assets/index-[^]*# assets/index-QZznvyml.js / index-DYj3IfB2.css# 3) HTTPS 下 API 可达返回 JSON而非 nginx 404curl -sk https://127.0.0.1/api/public/settings | head -c 200# 4) HTTP 80 强制跳转 HTTPScurl -sI http://127.0.0.1/ | head -1浏览器侧无痕窗口 / CtrlShiftR 强刷验证最终效果。---## 6. 经验与教训下次部署可对照1. **改了没变化先看服务器实际返回了什么**不要只看浏览器curl 域名/ | grep -o assets/index-[^]* 一条命令即可区分文件没传上去与浏览器缓存。2. **root 必须指向目录里直接有 index.html assets/的那一层**dist 目录或解压后的产物目录指向含 src/ 的源码根会导致白屏。3. **前端以 /api 为前缀时nginx 配置必须有对应的 location /api/ 反代**且 proxy_pass 不要带尾斜杠否则会丢失 /api 前缀。4. **语法版本差异**http2 on; 需要 nginx ≥ 1.25.1老版本用 listen 443 ssl http2;。配置前先 nginx -v 确认。5. **nginx -t 失败后 reload 不生效**服务器跑的是旧配置——每次改完务必 nginx -t 确认 OK 再 reload并以 curl 实测为准。6. **SSL 证书路径**放在 /etc/nginx/cert/nginx -t 会直接校验 pem/key 是否可读证书缺失时会在语法检查阶段报错。7. **SPA 项目必须配 try_files $uri $uri/ /index.html;** 否则深层路由 404观感上像后端挂了。8. **/home/ubuntu 等用户目录默认权限 750**nginxwww-data无权限访问会 403需 chmod 755 /home/ubuntu 并 chmod -R orX 站点目录。