单页应用（SPA）History模式在Nginx中的Rewrite重定

单页应用（SPA）因其流畅的用户体验，已成为现代 Web 开发的主流范式。其中，HTML5 History 模式（pushState/replaceState）让 URL 看起来与传统多页应用无异，但这也给服务器配置带来了一个经典难题：用户直接访问或刷新一个非根路径时，Nginx 找不到对应的物理文件，从而返回 404。本文将从原理出发，逐步拆解 Nginx 中针对 SPA History 模式的 rewrite 重定向配置，涵盖 try_files、rewrite 指令、静态资源路由隔离、缓存策略以及常见排错方法。

一、SPA History 模式为何需要服务器端重定向

1.1 前端路由的工作方式

SPA 应用只有一个 HTML 入口文件（通常为 index.html），所有页面切换由 JavaScript 通过 History API 改变 URL 并动态渲染组件。当用户通过 /about 这样的链接进入网站时，如果路径匹配到了前端路由，浏览器会正确显示内容。但问题出在“直接访问”或“刷新”——此时浏览器向服务器请求 /about，Nginx 会尝试寻找 /about 这个文件或目录，显然不存在，于是返回 404。

1.2 核心矛盾：物理路径 vs 虚拟路径

Nginx 默认行为是与物理文件系统一一对应。SPA 的 History 模式则创建了虚拟路径（即前端路由），这些路径只在浏览器端有意义。服务器需要将所有不匹配静态资源的请求都指向 index.html，由前端路由接管后 JS 再判断应该渲染哪个组件。

因此，配置的关键就是：当请求不是针对实际存在的静态文件（如 js、css、图片）时，一律重定向到 index.html。

二、最推荐的方案：try_files 指令

2.1 基础配置模板

Nginx 的 try_files 指令能够按顺序检查文件是否存在，如果都不存在则执行最后一个参数（通常是一个 fallback URI）。对于 SPA 应用，典型配置如下：

server {
    listen 80;
    server_name example.com;
    root /path/to/dist;  # 前端打包后的目录

    index index.html;

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

$uri：尝试原始请求路径对应的文件。
$uri/：尝试作为目录处理（自动补 index.html）。
/index.html：以上都失败时，返回 index.html。

这种配置简洁高效，且不需要使用 rewrite 指令。Nginx 在内部会先检查文件是否存在，只有不存在时才 fallback，对性能影响极小。

2.2 必须注意：静态资源分离

如果前端构建产物的静态资源（如 js、css、图片）也存放在同一目录，上述 try_files 配置会自动为它们服务。但有些项目将静态资源放在 CDN 或另一个 location 下，此时需要独立处理。例如：

location /static/ {
    root /path/to/dist;
    expires 30d;
}

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

这样可以确保静态资源请求被优先匹配到 /static/ 位置，不会误被 fallback 到 index.html。而且还能为静态资源单独设置过期时间。

三、rewrite 指令作为备选方案

3.1 使用 rewrite … last 实现内部重定向

虽然 try_files 是官方推荐做法，但在某些复杂场景（如需要配合正则匹配、多级路由或遗留配置）下，也可以使用 rewrite 指令。常见写法：

location / {
    rewrite ^/(?!index.html|static|api|favicon.ico)(.*)$ /index.html last;
}

这里使用正则前瞻 (?!...) 排除掉不需要重写的路径（如 index.html 本身、静态资源目录、API 接口等）。last 标志表示终止当前 rewrite 模块的处理，并再次进行 location 匹配（最终会匹配到 /index.html）。

缺点：正则写起来容易出错，且一旦遗漏某些静态资源路径，会导致死循环或 500 错误。try_files 更简洁安全。

3.2 rewrite 与 try_files 的取舍

try_files：直接基于文件是否存在判断，语义明确，性能更优，适合绝大多数场景。
rewrite：适合需要复杂条件判断的场景，例如根据 User-Agent 返回不同 fallback 页面，或对特定路径做额外处理。

在 SPA 路由场景下，除非有特殊需求，否则优先使用 try_files。

四、常见陷阱与风险规避

4.1 相对路径错误导致资源加载失败

当请求 /about 被 fallback 到 /index.html 后，浏览器会以 /about 为基准解析页面中的相对路径。例如，如果 index.html 引用了 ./js/app.js，浏览器会请求 /about/js/app.js，而实际文件在 /js/app.js。解决方法：

在 index.html 的 <head> 中添加 <base href="/" />，强制所有相对路径以根目录为基准。
或者打包时使用绝对路径（如 /js/app.js）。

4.2 死循环与 500 Internal Server Error

如果 try_files 的 fallback URI 指向了自身（如 try_files $uri /index.html 且 /index.html 本身也不存在），Nginx 会进入内部循环，最终返回 500。确保 /index.html 真实存在于 root 目录中。

4.3 API 路由冲突

如果后端 API 也部署在同一域名下（如 /api/），需要单独配置 location 将其 proxy_pass 到后端服务，而不要 fallback 到 index.html：

location /api/ {
    proxy_pass http://backend:3000/;
}

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

五、验证配置的正确性

5.1 本地测试

使用 nginx -t 检查语法，确认无误后 nginx -s reload。然后尝试以下路径：

http://example.com/ → 应正常返回 index.html
http://example.com/about → 应返回 index.html（页面由前端路由渲染）
http://example.com/js/app.js → 应返回实际 JS 文件，不是 index.html
http://example.com/nonexistent.css → 应返回 404（如果该文件不存在，Nginx 应返回正确状态码，而不是 fallback 给 index.html）

注意：对于不存在的静态文件，默认 try_files $uri $uri/ /index.html 也会 fallback 到 index.html，这实际上可能不是你想要的。如果希望不存在的资源返回 404，可以改用先检查 $uri 再 fallback：

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

但这个配置无法区分“请求的是某个不存在的 js 文件”还是“请求的是前端路由”。实际项目中，更好的做法是将静态资源放在单独的 location 中，并对它们关闭 fallback：

location ~* .(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
    try_files $uri =404;  # 文件不在就 404
}

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

六、缓存策略的配合

6.1 对 index.html 禁用缓存

由于 index.html 是 SPA 的入口，前端打包后通常带内容 hash 的静态资源，而 index.html 本身不变（或通过版本号管理），但为了确保用户每次请求都能获取最新版本的 SPA，建议对 index.html 设置不缓存：

location = /index.html {
    add_header Cache-Control "no-store, no-cache, must-revalidate";
}

注意：这个 location 要放在通用 location / 之前，因为 Nginx 按优先级匹配。

6.2 静态资源的强缓存

对于带内容 hash 的文件（如 app.a1b2c3.js），可以设置长缓存时间（如 1 年），因为文件名变化即表示内容变化。配置示例见上一节。

七、多级子路径场景（部署在非根目录）

如果 SPA 部署在某个子路径下（如 /app/），配置略有不同：

location ^~ /app/ {
    alias /path/to/dist/;
    try_files $uri $uri/ /app/index.html;
}

注意：try_files 的 fallback URI 必须带上子路径前缀，并且 index.html 需要位于 /path/to/dist/index.html。同时，前端构建时也需通过 publicPath 配置指定子路径。

八、总结

SPA History 模式在 Nginx 下的核心配置思路是：将所有不匹配静态资源的路径请求指向 index.html，由前端路由接管。推荐使用 try_files $uri $uri/ /index.html 作为首选方案，它简单、安全、性能好。如果需要更细粒度的控制，可以结合 location 匹配和 rewrite 指令。注意避免静态资源被错误 fallback，合理设置 base 标签，以及对 API 和静态资源做独立 location 处理。通过上述配置，即可在 Nginx 上完美支持 SPA 的 History 模式，让用户刷新或直接访问任意路由都不再出现 404。

延伸阅读