Vercel SPA路由与资源加载：解决深层URL访问问题

1. Vercel 单页应用（SPA）路由基础

单页应用（spa）的特点是所有路由切换都在客户端完成，服务器端实际上只提供一个入口文件（通常是index.html）。当用户在浏览器中直接访问应用的深层路径（例如 /projects/home）或刷新页面时，浏览器会向服务器请求该url。由于服务器并没有 /projects/home 这个实际的文件或目录，因此需要一个机制来将所有此类请求都导向到 index.html，由客户端路由来处理后续的页面渲染。

在 Vercel 中，这通常通过 vercel.json 文件中的 rewrites（重写）规则来实现。最常见的 SPA 重写规则如下：

{
  "trailingSlash": false,
  "rewrites": [
    { 
      "source": "/:path*", 
      "destination": "/index.html" 
    }
  ]
}

• "trailingSlash": false: 这个配置项用于控制 URL 末尾斜杠的行为。设置为 false 意味着 Vercel 会移除 URL 末尾的斜杠（例如 /about/ 会被重定向到 /about）。
• "rewrites": 定义了请求路径如何被重写。
  • "source": "/:path*": 这是一个通配符模式，表示匹配任何路径。: 表示捕获路径段，* 表示匹配零个或多个字符。因此，它会匹配除了静态文件之外的所有传入请求。
  • "destination": "/index.html": 表示将匹配到的请求重写到 /index.html。

这条规则的含义是：对于任何不直接对应 Vercel 部署的静态文件的请求，都将其内部重写到 index.html。这样，无论是访问根路径 /、一级路径 /projects 还是深层路径 /projects/home，服务器都会返回 index.html 的内容，然后由 SPA 的客户端路由（如 React Router, Vue Router, History API等）接管并渲染对应的组件。

2. 深层URL访问与资源加载失败的根本原因

尽管上述 vercel.json 配置看起来完美地解决了 SPA 路由问题，但在实际部署中，尤其是在直接访问或刷新深层 URL 时，你可能会遇到页面样式丢失、脚本不执行等问题。例如，当访问 kor.nz/projects/home 时，页面可能无法正确加载 asset/style.css。

这并非 vercel.json 配置的错误，而是由于浏览器解析相对路径的机制。当你在 index.html 中引用静态资源时，如果使用相对路径，如：

@@##@@

浏览器会根据当前页面的 URL 来解析这些相对路径。

• 如果当前 URL 是 kor.nz/，浏览器会尝试加载 kor.nz/asset/style.css。
• 如果当前 URL 是 kor.nz/projects，浏览器会尝试加载 kor.nz/projects/asset/style.css。
• 如果当前 URL 是 kor.nz/projects/home，浏览器会尝试加载 kor.nz/projects/home/asset/style.css。

问题在于，你的静态资源（style.css, main.js, logo.png 等）通常都部署在网站的根目录下（例如，public/asset/style.css 最终部署到 /asset/style.css）。当浏览器尝试请求 kor.nz/projects/home/asset/style.css 时，Vercel 发现这个路径下并没有对应的静态文件。根据我们前面配置的 rewrites 规则，所有未匹配的路径都会被重写到 index.html。因此，浏览器收到的响应不是 style.css 的内容，而是 index.html 的内容，导致样式无法加载，页面显示异常。

3. 解决方案：使用绝对路径引用静态资源

解决这个问题的关键在于，确保无论用户从哪个 URL 深度访问页面，浏览器都能正确地向服务器请求到静态资源在服务器上的实际位置。这可以通过将 HTML 中所有静态资源的相对路径改为绝对路径来实现。

修改前：

@@##@@

修改后（添加前导斜杠 /）：

CodiumAI

AI代码测试工具，在IDE中获得重要的测试建议

下载

@@##@@

通过在路径前添加 /，你告诉浏览器这是一个相对于网站根目录的路径。

• 无论当前 URL 是 kor.nz/、kor.nz/projects 还是 kor.nz/projects/home，当浏览器看到 /asset/style.css 时，它总是会请求 kor.nz/asset/style.css。
• Vercel 在处理请求时，会优先查找是否存在匹配的静态文件。如果 asset/style.css 确实存在于部署的根目录下的 asset 文件夹中，Vercel 会直接提供该文件，而不会触发 rewrites 规则。

这样，即使是深层 URL 的刷新或直接访问，页面也能正确加载所有所需的样式、脚本和图片，确保 SPA 的正常运行。

4. 完整的 vercel.json 配置示例与注意事项

对于大多数简单的 SPA，以下 vercel.json 配置结合绝对路径的资源引用是完全足够的：

{
  "trailingSlash": false,
  "rewrites": [
    { 
      "source": "/:path*", 
      "destination": "/index.html" 
    }
  ]
}

注意事项：

• Vercel 的请求处理优先级： Vercel 在处理请求时，会遵循一定的优先级：
  1. 静态文件服务： 首先尝试匹配并直接提供部署的静态文件（例如 /asset/style.css）。
  2. 重定向（Redirects）： 如果有匹配的重定向规则，则执行重定向。
  3. 重写（Rewrites）： 如果请求不是静态文件且没有匹配重定向，则应用重写规则。 正是因为静态文件服务优先于重写，所以当资源路径正确（绝对路径）时，Vercel 会直接提供文件，而不会将其重写到 index.html。
• 开发环境与生产环境： 在本地开发时，开发服务器通常会处理好路由和资源加载，所以可能不会立即发现这个问题。但部署到 Vercel 等平台后，这个问题就会显现。务必在生产环境进行充分测试。
• 构建工具： 如果你使用现代前端构建工具（如 Webpack, Parcel, Vite 等），它们通常会提供配置选项来自动处理资源路径，例如通过配置 publicPath 或 base URL 来确保所有资源引用都是正确的绝对路径。对于简单的 Vanilla JS 应用，则需要手动检查和修改。
• API 路由与特殊路径： 如果你的应用包含 Vercel Functions (Serverless Functions) 或其他特殊路径（如 /_next 用于 Next.js 应用），你可能需要更复杂的 rewrites 或 routes 配置来排除这些路径，确保它们不会被重写到 index.html。例如：

  {
    "rewrites": [
      {
        "source": "/:path((?!api|_next).*)", // 排除 /api 和 /_next 路径
        "destination": "/index.html"
      }
    ]
  }

  但对于纯客户端 SPA，上述简单配置通常已足够。

总结

在 Vercel 上部署单页应用并确保深层 URL 正常工作，关键在于两点：

1. Vercel 配置层面： 使用 vercel.json 的 rewrites 规则将所有非静态文件请求重写到 index.html，确保服务器总能返回 SPA 的入口文件。
2. HTML 资源引用层面： 在 index.html 中引用所有静态资源（CSS, JavaScript, 图片等）时，务必使用绝对路径（以 / 开头），以确保浏览器无论在哪个 URL 深度都能正确请求到这些资源在服务器上的实际位置。

理解并正确应用这两个方面，就能有效解决 Vercel SPA 在深层 URL 访问时遇到的资源加载问题。