[VitePress] 部署到 Vercel 后直接访问 url 出现 404 或者卡住的问题

2026年3月16日 · JavaScript

我将文档用 VitePress 部署到 Vercel 后，发现第一次直接访问是没有问题的，但当选择了子路径或者重新刷新之后，页面就会跳到 404 或者直接卡住，console 中出现无限循环的报错。

原因是 VitePress 中配置了 clearUrl 用于去除 url 中的后缀

export default defineConfig({
  // ...
  cleanUrls: true, // 去掉 .html 后缀
  // ...
});

而 Vercel 默认不处理这一种情况，以至于出现上述问题。

解决方法是在根目录新增一个 vercel.json :

{
  "cleanUrls": true,
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}