Nginx 单页应用配置详解

在现代 Web 开发中，单页应用（SPA）架构越来越常见，如 Vue、React、Angular 等前端框架都会生成一套静态资源，用于构建完整的前端页面。而 Nginx 则是部署这类应用最常见、最轻量、最稳定的 Web 服务器之一。

本文将详细讲解如何使用 Nginx 部署和配置单页应用，并解决常见问题如刷新 404、前后端分离跨域、缓存配置等。

目录

• 一、什么是单页应用（SPA）
• 二、Nginx 作为静态服务器的作用
• 三、基本部署配置
• 四、防止刷新 404 的 history 路由兼容
• 五、跨域请求处理（前后端分离）
• 六、缓存优化配置
• 七、完整配置示例
• 总结

一、什么是单页应用（SPA）

单页应用（Single Page Application）指的是前端页面在首次加载后，页面不会整体刷新，所有页面切换都通过前端 JavaScript 动态完成，页面结构由路由管理，数据通过 Ajax 异步加载。

常见的 SPA 构建工具包括：

• Vue + Vue Router
• React + React Router
• Angular

构建完成后通常会输出一套静态文件（如 index.html、app.js、chunk-vendors.js 等），这些文件需要部署到 Web 服务上供浏览器访问。

二、Nginx 作为静态服务器的作用

Nginx 是一款高性能 Web 服务器，天然适合部署静态内容，特点包括：

• 支持高并发、资源占用低
• 配置简单，适配各类路径和 MIME 类型
• 可配合缓存、Gzip、反向代理等功能增强前端性能
• 非常适合构建 CDN 或内网部署方案

对于单页应用，我们只需让 Nginx 返回正确的 index.html 和静态资源即可。

三、基本部署配置

假设你的构建目录为 dist/，使用如下基本配置即可部署：

server {
    listen 80;
    server_name example.com;

    root /usr/share/nginx/html/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

说明：

• root 指向构建产物目录；
• index 指定默认首页；
• try_files 是关键，表示“如果找不到文件就回退到 index.html”，适配前端路由跳转。

四、防止刷新 404 的 history 路由兼容

前端框架的 history 模式路由，在直接访问二级路径时如 /user、/about，Nginx 会尝试找一个 user/index.html 或 /about.html 文件，导致 404。

因此必须配置：

location / {
    try_files $uri $uri/ /index.html;
}

这样，所有未匹配文件的路径都会自动返回 index.html，由前端框架接管路由。

五、跨域请求处理（前后端分离）

如果你的接口是分离部署的，比如前端跑在 example.com，后端在 api.example.com，则需要配置反向代理 + CORS 头。

示例：

location /api/ {
    proxy_pass http://api.example.com;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
}

对于 OPTIONS 预检请求，也可返回 204：

if ($request_method = 'OPTIONS') {
    return 204;
}

六、缓存优化配置

为了加速加载和减少带宽，可以配置缓存头和压缩：

location ~* \.(js|css|png|jpg|jpeg|gif|ico|woff2?)$ {
    expires 30d;
    access_log off;
    add_header Cache-Control "public";
}

开启 Gzip：

gzip on;
gzip_types text/css application/javascript application/json application/xml;
gzip_min_length 1k;

七、完整配置示例

这是一个适用于 Vue/React 应用的 Nginx 全配置示例：

server {
    listen 80;
    server_name www.example.com;

    root /usr/share/nginx/html/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://api.example.com;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods GET, POST, OPTIONS;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|woff2?)$ {
        expires 30d;
        access_log off;
        add_header Cache-Control "public";
    }

    gzip on;
    gzip_types text/plain application/javascript text/css application/json;
    gzip_min_length 1k;
}

总结

部署单页应用时，Nginx 提供了高效、灵活的解决方案。只需配置正确的资源目录、静态路由处理和前后端联调代理，就可以实现一个完整的 SPA 部署环境。

建议同时结合缓存策略与压缩技术，进一步提升访问速度和用户体验。