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. 对比速查表

三、前端项目挂载标准配置（推荐）

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

八、高频报错速查

1. 403 Forbidden权限不足、index 缺失、SELinux 拦截、目录无执行权限。
2. 404 Not Foundroot/alias 路径错误、文件不存在、try_files 缺失。
3. 502 Bad Gateway后端未启动、端口错误、防火墙拦截。
4. 刷新页面 404缺少try_files $uri $uri/ /index.html;。

九、生产最佳实践

1. 站点配置独立放/etc/nginx/conf.d/
2. 静态资源启用长期缓存
3. API 统一前缀/v1/
4. 日志按站点拆分
5. 禁止目录遍历、隐藏版本号
6. 配置前必跑nginx -t

十、总结

• root适合站点根目录，alias适合路径映射
• SPA 必须加 try_files
• 80 端口多域名靠 server_name 隔离
• 前后端分离用 location 转发 API
• 配置不生效优先看日志与权限