SPA 刷新非首页报 404

首屏能进、刷新就白屏，问题一定不在前端路由库，而在服务器不认识这条路。

为什么会 404

history 模式下 /order/123 是前端路由，服务器磁盘上并没有 order/123/index.html 这个文件。客户端跳转不经过服务器，所以一切正常；一旦刷新或直接粘贴链接，浏览器会向服务器要 /order/123，Nginx 找不到文件就返回 404。

hash 模式（/#/order/123）不会有这个问题，因为 # 后面的内容根本不会发给服务器——这也是很多老项目坚持用 hash 的真实原因。

解决：所有未命中的路径都交给 index.html

server {
    # ... 其他配置 ...

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

    # 项目部署在子目录时，兜底文件也要带子目录
    # location /admin/ {
    #     try_files $uri $uri/ /admin/index.html;
    # }
}

try_files 依次尝试三件事：$uri（原路径对应的文件）→ $uri/（当作目录找其下的 index）→ /index.html（内部重定向到首页，返回 200）。前端路由拿到 URL 后自己渲染对应页面。

顺序很重要：静态资源要放在兜底之前

如果 location / 的兜底写在前面，且没有更精确的匹配，JS/CSS/图片不存在时也会返回 index.html，浏览器收到 Content-Type: text/html 的「JS 文件」直接报语法错误。表现是控制台出现 Uncaught SyntaxError: Unexpected token '<'。

标准的写法是用前缀匹配把静态资源单独放出来，^~ 让它不被正则 location 抢走：

# 静态资源：命中就返回，命中不了就真 404，不要兜底到 index.html
location ^~ /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

location ~* \.(?:js|css|png|jpg|jpeg|gif|svg|woff2?|ttf|ico)$ {
    expires 30d;
    try_files $uri =404;
}

# 其余路径交给前端路由
location / {
    try_files $uri $uri/ /index.html;
}

try_files $uri =404 里的 =404 是关键：静态资源不存在就明确返回 404，而不是吐一个 HTML 出去。

index.html 一定不能被缓存

兜底依赖 index.html 是最新版本。如果它被缓存了，用户拿到的还是旧 HTML，里面引用的旧 hash 文件名（app.a1b2c3.js）早被新构建删除，一刷新就是全屏白板 + 一堆 404。

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

带 hash 的静态资源可以放心长缓存，index.html 必须每次回源——这是缓存策略里唯一不能反的组合。

部署在子路径时的三个连带问题

项目访问地址是 https://example.com/admin/ 时，不只是 Nginx 要改：

位置	要改什么	漏改的表现
Nginx	location /admin/ { try_files ... /admin/index.html; }	刷新 404
构建配置	base: '/admin/'（vite）或 （webpack）