如何配置Nginx以解决非根目录下SPA静态资源路径失效问题？

本文共计719个文字，预计阅读时间需要3分钟。

必须同时配置 publicPath、router.base 和 Nginx 的 alias 路径，否则资源 404 或刷新白屏是必然结果。只需更改其中一项，资源访问问题即可解决。

Vue CLI / Vite 构建时 publicPath 必须带尾部斜杠

构建产物中 JS/CSS 的引用路径由 publicPath 决定。写成 '/admin'（缺末尾斜杠）会导致浏览器请求 /adminjs/app.abc.js —— 拼接错误，直接 404。

• vue.config.js 中设为：publicPath: '/admin/'（前后都带斜杠）
• Vite 项目在 vite.config.ts 中配置：base: '/admin/'
• 不能用 './' 或 ''，否则刷新时相对路径失效，静态资源加载失败

Vue Router 的 base 值必须与 publicPath 完全一致

前端路由基地址不匹配，会导致页面跳转正常，但刷新时 Vue Router 无法识别当前 URL，返回空白或错误路由。

• 初始化 router 时写死：base: '/admin/'，和 publicPath 字符串完全相同
• 不要动态拼接，比如 base: process.env.BASE_URL，除非环境变量值也严格等于 '/admin/'
• React Router 的 basename 同理，必须和构建 homepage 配置一致

Nginx 必须用 alias + 精准 location 匹配子路径

用 root 会把 /admin/ 拼进路径，导致实际查找 /opt/dist/admin/js/app.js；而文件真实位置是 /opt/dist/js/app.js。只有 alias 能做“整段替换”。

• location 块必须精确匹配路径前缀：location /admin/ { ... }（结尾斜杠不能少）
• alias 后路径也必须以 / 结尾：alias /opt/dist/;
• try_files 的 fallback 要写成 /admin/index.html，因为浏览器请求的是这个 URL，Nginx 内部才去读 /opt/dist/index.html

验证三者是否真正对齐的实操检查法

打开浏览器开发者工具 Network 面板，直接看资源请求：

• 访问 https://example.com/admin/，应返回 index.html（状态码 200）
• 查看 JS 请求，URL 应为 https://example.com/admin/js/app.xxx.js，响应内容是 JS 代码（不是 HTML）
• 手动请求 https://example.com/admin/js/app.xxx.js 和 https://example.com/admin/404-test，前者 200，后者也 200 且返回 index.html，说明 fallback 生效

最容易被忽略的是：Nginx 的 alias 和前端 publicPath 之间没有自动同步机制，改了任一端却忘了另一端，问题立刻复现。