本教程旨在解决 Vercel 上部署单页应用 (SPA) 时，在访问多层级 URL（如 /projects/home）时遇到的资产（CSS、JS、图片等）加载失败问题。核心在于理解 Vercel 的路由重写机制与 HTML 中相对/绝对路径的差异。通过正确配置 vercel.json 确保所有非文件请求重定向至 index.html，并修正 HTML 中资产引用为绝对路径，从而实现 SPA 在任意深度 URL 下的稳定运行。
Vercel 上单页应用的路由挑战
单页应用 (spa) 的核心特点是所有路由操作都在客户端进行，浏览器地址栏的变化并不会触发服务器重新加载页面，而是由 javascript 动态更新页面内容。然而，当用户直接访问一个深层级的 url（例如 https://example.com/projects/home）或刷新页面时，浏览器会向服务器请求这个特定的路径。对于一个传统的服务器，它会尝试查找 projects/home 目录下的 index.html 或相关文件。但对于 spa，我们希望服务器始终返回主入口文件 index.html，然后由客户端路由接管。
Vercel 通过 vercel.json 配置文件提供了强大的路由重写 (rewrites) 功能，可以实现这一目标。一个常见的 SPA 配置如下：
{ "rewrites": [ { "source": "/:path*", "destination": "/index.html" } ] }
这个配置的含义是：所有请求（/:path*，捕获任何路径）都将被重写到 /index.html。这意味着无论用户访问 https://example.com/、https://example.com/projects 还是 https://example.com/projects/home，Vercel 都会将 index.html 文件作为响应返回。
资产加载失败的根本原因
尽管上述 vercel.json 配置能够确保所有路径都返回 index.html，但许多开发者仍然会遇到 CSS、JavaScript 或图片等资产加载失败的问题，尤其是在访问深度 URL 时。例如，当访问 https://example.com/projects/home 时，页面虽然加载了，但样式错乱或功能缺失。
问题的根源在于 HTML 中资产引用的路径类型：相对路径与绝对路径。
- 相对路径：如 asset/style.css。这种路径是相对于当前 URL 的。如果当前 URL 是 https://example.com/projects/home，浏览器会尝试加载 https://example.com/projects/home/asset/style.css。显然，这个路径通常是不存在的，因为你的 asset 目录通常位于网站的根目录下（即 https://example.com/asset/style.css）。
- 绝对路径：如 /asset/style.css。这种路径是相对于网站的根目录的。无论当前 URL 是 https://example.com/projects 还是 https://example.com/projects/home，浏览器都会尝试加载 https://example.com/asset/style.css，这是正确的路径。
当你的 vercel.json 将所有请求重写到 index.html 后，如果 index.html 中使用了相对路径引用资产，那么在深层 URL 下，浏览器会根据深层 URL 构造错误的资产请求路径，导致 404 错误。
解决方案：使用绝对路径引用资产
解决这个问题的关键非常简单：将 HTML 文件中所有对外部资产的引用从相对路径改为绝对路径。
例如，如果你在 index.html 中有如下引用：
<link rel="stylesheet" href="asset/style.css" /> <script src="js/main.js"></script> @@##@@
你需要将它们修改为：
<link rel="stylesheet" href="/asset/style.css" /> <script src="/js/main.js"></script> @@##@@
注意路径前新增的斜杠 /。这个斜杠表示路径从网站的根目录开始。
示例与注意事项
假设你的项目结构如下：
your-spa-project/ ├── public/ │ ├── index.html │ ├── asset/ │ │ └── style.css │ └── js/ │ └── main.js └── vercel.json
在 public/index.html 中，确保你的资产引用是绝对路径：
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>My SPA</title> <!-- 正确的绝对路径引用 --> <link rel="stylesheet" href="/asset/style.css" /> </head> <body> <div id="app"></div> <!-- 正确的绝对路径引用 --> <script src="/js/main.js"></script> </body> </html>
同时，你的 vercel.json 保持以下配置即可：
{ "rewrites": [ { "source": "/:path*", "destination": "/index.html" } ] }
注意事项：
- Vercel 部署目录： 确保你的 index.html 和所有静态资产（如 asset、js、images 文件夹）都位于 Vercel 部署的根目录或其子目录下。如果你的项目构建后会输出到 dist 或 build 目录，那么 Vercel 的 Root Directory 配置应指向该目录。
- 开发环境与生产环境： 在本地开发时，如果你使用 webpack-dev-server 或类似的工具，它们通常会自动处理路径问题。但部署到 Vercel 这类静态托管平台时，必须严格遵循绝对路径原则。
- 动态生成路径： 如果你的 SPA 是用 React、Vue、Angular 等框架构建的，并且通过 publicPath 或 baseUrl 等配置项来管理资产路径，请确保这些配置在生产环境中正确设置为 / 或空字符串，以便生成绝对路径。例如，在 Vue CLI 中，vue.config.js 的 publicPath 应设置为 /。
- trailingSlash 配置： vercel.json 中的 trailingSlash: false 配置通常用于移除 URL 末尾的斜杠，与本教程讨论的资产加载问题关系不大，但可以根据个人偏好配置。
总结
在 Vercel 上部署单页应用时，解决深度 URL 下资产加载失败的问题，关键在于两点：
- 配置 vercel.json 的 rewrites 规则，将所有非文件请求重写到 index.html，确保 Vercel 始终返回 SPA 的入口文件。
- 在 index.html 中使用绝对路径（以 / 开头）引用所有静态资产，确保浏览器无论在哪个 URL 深度下都能正确找到并加载这些资源。
通过理解并实施这两点，你的单页应用将能够在 Vercel 上实现稳定、可靠的部署，无论用户通过何种方式访问其内部路由。
评论（已关闭）
评论已关闭