Nginx 静态资源挂载与前端部署实战笔记
前言本文从零带你掌握 Nginx 静态资源托管、root/alias 区别、单页应用（Vue/React）部署、前后端分离代理、缓存优化、权限与常见报错排查，适用于生产环境，复制即用。
一、Nginx 安装与目录结构（Linux）
# CentOS/RHEL yum install -y nginx # Ubuntu/Debian apt update && apt install -y nginx # 启动&开机自启 systemctl start nginx systemctl enable nginx # 核心目录 # 主配置：/etc/nginx/nginx.conf # 子配置：/etc/nginx/conf.d/*.conf # 默认站点：/usr/share/nginx/html # 日志：/var/log/nginx/二、静态资源挂载核心：root vs alias
1. root（拼接路径，最常用）
location /static/ { root /voy/v1/web-sls; # 访问 /static/img.png → /voy/v1/web-sls/static/img.png }2. alias（精确替换路径）
location /static/ { alias /voy/v1/web-sls/assets/; # 访问 /static/img.png → /voy/v1/web-sls/assets/img.png }3. 对比速查表
| 指令 | 路径规则 | 适用场景 |
|---|---|---|
| root | root + location | 站点根目录、常规静态资源 |
| alias | 直接替换 | 路径重命名、多级目录映射 |
三、前端项目挂载标准配置（推荐）
1. 纯静态站点
server { listen 80; server_name sls.voyagers.work; root /voy/v1/web-sls; index index.html; charset utf-8; location / { try_files $uri $uri/ /index.html; } # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ { expires 7d; add_header Cache-Control public; } }2. SPA 路由刷新 404 解决
location / { try_files $uri $uri/ /index.html; }四、前后端分离代理配置（你的项目专用）
1. 80 端口托管前端 + API 转发 9999
server { listen 80; server_name sls.voyagers.work; root /voy/v1/web-sls; index index.html; charset utf-8; # 后端接口 location /v1/ { proxy_pass http://127.0.0.1:9999; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # 接口文档 location /docs { proxy_pass http://127.0.0.1:9999; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /openapi.json { proxy_pass http://127.0.0.1:9999; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location / { try_files $uri $uri/ /index.html; } location ~* \.(js|css|png|jpg|svg|woff2)$ { expires 7d; add_header Cache-Control public; } }2. proxy_pass 斜杠坑点
# 带 /：去除前缀 location /api/ { proxy_pass http://ip:port/; } # /api/user → /user # 不带 /：保留前缀 location /api/ { proxy_pass http://ip:port; } # /api/user → /api/user五、多站点共用 80 端口（关键知识点）
Nginx 靠 server_name 区分多站点，同一 80 端口可托管无数项目，互不冲突！
# 项目A server { listen 80; server_name a.com; root /web/a; } # 项目B server { listen 80; server_name b.com; root /web/b; }六、权限与安全（必看）
# 目录权限 chmod -R 755 /voy/v1/web-sls chown -R nginx:nginx /voy/v1/web-sls # SELinux 放行（CentOS） setenforce 0 # 永久 sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config # 防火墙开放 80 firewall-cmd --add-service=http --permanent firewall-cmd --reload七、配置生效命令
bash
运行
# 检查语法 nginx -t # 平滑重启 nginx -s reload # 重启服务 systemctl restart nginx八、高频报错速查
- 403 Forbidden权限不足、index 缺失、SELinux 拦截、目录无执行权限。
- 404 Not Foundroot/alias 路径错误、文件不存在、try_files 缺失。
- 502 Bad Gateway后端未启动、端口错误、防火墙拦截。
- 刷新页面 404缺少
try_files $uri $uri/ /index.html;。
九、生产最佳实践
- 站点配置独立放
/etc/nginx/conf.d/ - 静态资源启用长期缓存
- API 统一前缀
/v1/ - 日志按站点拆分
- 禁止目录遍历、隐藏版本号
- 配置前必跑
nginx -t
十、总结
- root适合站点根目录，alias适合路径映射
- SPA 必须加 try_files
- 80 端口多域名靠 server_name 隔离
- 前后端分离用 location 转发 API
- 配置不生效优先看日志与权限