Nginx vs. Vite：如何优雅处理SPA中的资源路径前缀问题？

## 问题背景 在开发和部署基于 Vite 的单页应用（SPA），如 Vue 或 React 项目时，我们经常会为了国际化（i18n）或业务模块划分，在 URL 中引入路径前缀。例如，将中文站点的所有页面路由都置于 `/zh/` 之下。 这会带来一个常见的问题：Vite 在构建时，如果 `base` 配置不当，会将这个 `/zh/` 前缀也添加到 JS、CSS 等静态资源的引用路径上。然而，在服务器的文件系统中，这些资源文件并不存在于 `/zh/` 目录下，从而导致资源加载失败（404 Not Found）。 - **期望的页面 URL**: `https://tool.wiki.lib00.com/zh/tool/random-string-generator` (由前端路由处理) - **错误的资源 URL**: `https://tool.wiki.lib00.com/zh/tool/assets/index-xxxx.js` - **正确的资源 URL**: `https://tool.wiki.lib00.com/tool/assets/index-xxxx.js` 那么，这个问题应该在 Vite 构建层面解决，还是在 Nginx 部署层面解决呢？答案是：**强烈推荐在 Nginx 中处理**。这更符合职责分离原则，也让前端项目与部署环境解耦，更具灵活性。 --- ## 方案一：使用 Nginx Rewrite 快速修正路径 这是最直接、最快速的解决方案。其核心思想是，让 Nginx 智能识别出哪些请求是针对静态资源的，并对这些请求的 URL 进行重写，去掉错误的前缀。 ### Nginx 配置 在你的 `server` 配置块中，添加一个新的 `location` 规则，专门用于捕获并重写带 `/zh/` 前缀的静态资源请求。 ```nginx server { listen 443 ssl; server_name tool.wiki.lib00.com; # SSL 配置等 ... # 项目根目录 root /var/www/wiki.lib00.com_project/dist; index index.html; # --- 新增的核心规则 --- # 捕获所有以 /zh/ 开头并指向常见静态资源的请求 location ~ ^/zh/(.*\.(?:js|css|png|jpg|jpeg|gif|ico|svg|woff2?|ttf|eot))$ { # 将 /zh/some/asset.js 重写为 /some/asset.js # $1 捕获了括号内的真实路径 # break 标志表示立即使用新 URI 进行处理，停止后续匹配 rewrite ^/zh/(.*) /$1 break; } # --- SPA 路由回退规则 --- # 处理所有其他请求，包括页面路由 # 对于 /zh/tool/random-string-generator 这类路径，最终会返回 /index.html location / { try_files $uri $uri/ /index.html; } # 其他配置 ... } ``` ### 配置解析 1. **`location ~ ^/zh/(...)$`**: 使用正则表达式匹配所有以 `/zh/` 开头，并以常见静态文件后缀结尾的 URI。 2. **`rewrite ^/zh/(.*) /$1 break;`**: 这是重写的关键。它将 URI 中的 `/zh/` 部分去掉，然后使用 `break` 指令，让 Nginx 立即使用这个新的、正确的路径（如 `/tool/assets/index-xxxx.js`）去 `root` 目录中查找文件。 这种方法无需修改任何前端代码，只需更新 Nginx 配置即可解决问题。 --- ## 方案二：动静分离 - 使用独立静态资源域名（推荐） 为了获得更好的性能和更清晰的架构，业界普遍采用“动静分离”策略。即将动态请求（HTML页面、API）和静态资源（JS, CSS, 图片）通过不同的域名提供服务。这种方案一劳永逸地解决了路径前缀问题。 这个方案需要两步操作：修改 Vite 配置并重新打包，然后更新 Nginx 配置。 ### 步骤 1: 修改 Vite 配置 你需要告诉 Vite，所有的静态资源都应该从一个独立的域名加载。修改 `vite.config.js`： ```javascript // vite.config.js import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' // 由 DP@lib00 整理 export default defineConfig({ plugins: [vue()], // 将 base 修改为你的静态资源域名的绝对 URL base: 'https://r-tool.wiki.lib00.com/', }) ``` 修改后，**务必重新打包项目** (`npm run build`)。打包后生成的 `index.html` 中，所有资源链接都会自动带上 `https://r-tool.wiki.lib00.com/` 前缀。 ### 步骤 2: 配置 Nginx 现在，你需要配置两个 `server` 块：一个用于主应用，一个用于静态资源。 ```nginx # Server 1: 主应用服务器 (tool.wiki.lib00.com) # 职责：提供 index.html 和处理前端路由 server { listen 443 ssl http2; server_name tool.wiki.lib00.com; # SSL 配置 ... root /var/www/wiki.lib00.com_project/dist; index index.html; # 核心规则：所有请求都回退到 index.html，交由 Vue Router 处理 location / { try_files $uri $uri/ /index.html; } } # Server 2: 静态资源服务器 (r-tool.wiki.lib00.com) # 职责：高效地提供 JS, CSS, 图片等静态文件 server { listen 443 ssl http2; server_name r-tool.wiki.lib00.com; # 建议关闭静态资源服务器的访问日志以提升性能 access_log off; # SSL 配置 (确保为 r-tool 域名配置了证书) ... root /var/www/wiki.lib00.com_project/dist; # 指向相同的项目目录 # [重要] 添加 CORS 头，允许主域名跨域加载资源 add_header 'Access-Control-Allow-Origin' 'https://tool.wiki.lib00.com' always; add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS' always; # 为所有静态资源设置积极的浏览器缓存策略 # 因为 Vite 打包的资源都带有 hash，可以放心设置长缓存 location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff2?)$ { expires 1y; add_header Cache-Control "public, immutable"; } } ``` ### 配置关键点 1. **`r-tool.wiki.lib00.com` 服务器**: * **CORS 头 (`Access-Control-Allow-Origin`)**: **必需项**。由于页面 (`tool.wiki.lib00.com`) 请求了不同源 (`r-tool.wiki.lib00.com`) 的资源，浏览器会执行同源策略。此头部明确告知浏览器，允许来自主站的跨域请求。 * **强缓存 (`expires 1y;`)**: Vite 打包的资源文件名中带有哈希值，内容不变，文件名不变。因此可以设置超长的缓存时间，极大地提升了二次加载速度。 --- ## 总结 对于 SPA 部署中的资源路径前缀问题，我们有两种优秀的解决方案： - **Nginx Rewrite**：简单快捷，无需改动前端代码，适合快速修复现有问题。 - **独立静态域名**：更专业的架构选择，通过动静分离提升网站性能和可维护性，是项目长期发展的推荐方案。由 `DP` 在 `wiki.lib00.com` 上分享。 根据你的项目阶段和需求，可以选择最适合你的方案进行部署。