Nginx 静态资源挂载与前端部署实战笔记

前言本文从零带你掌握 Nginx 静态资源托管、root/alias 区别、单页应用（Vue/React）部署、前后端分离代理、缓存优化、权限与常见报错排查，适用于生产环境，复制即用。

一、Nginx 安装与目录结构（Linux）

bash 复制代码

# 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（拼接路径，最常用）

bash 复制代码

location /static/ {
    root /voy/v1/web-sls;
    # 访问 /static/img.png → /voy/v1/web-sls/static/img.png
}

2. alias（精确替换路径）

bash 复制代码

location /static/ {
    alias /voy/v1/web-sls/assets/;
    # 访问 /static/img.png → /voy/v1/web-sls/assets/img.png
}

3. 对比速查表

指令	路径规则	适用场景
root	root + location	站点根目录、常规静态资源
alias	直接替换	路径重命名、多级目录映射

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

1. 纯静态站点

bash 复制代码

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

python 复制代码

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 Found root/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
配置不生效优先看日志与权限