部署在Vercel上的Vite Web应用页面跳转异常求助

问题背景 #

开发了一款基于d3.js和Vite的太阳系探索Web应用，包含两个页面：

• 展示太阳系主体及运行机制的首页
• 提供行星3D模型体验的子页面

部署到Vercel并设置Vite为框架后，访问子页面时出现异常：页面仅刷新、URL变更但无内容，或直接返回404错误（错误信息：error -404: NOT_FOUND Code: NOT_FOUND ID: bom1:bom1::zqx2z-1728391679444-2646df531e05）。

问题根源 #

这是单页应用（SPA）前端路由在生产环境部署的典型问题：

• SPA的路由逻辑由前端JS处理，服务器默认会把所有子路径请求当作独立文件查找，找不到就返回404
• Vercel默认配置未对SPA前端路由做fallback处理，导致直接访问或刷新子路由时出错

解决方案 #

1. 添加Vercel路由重写配置 #

在项目根目录创建或修改vercel.json文件，添加以下配置，让所有请求都 fallback 到index.html，交给前端路由处理：

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

2. 检查前端跳转逻辑 #

确保页面跳转使用前端路由方式，而非原生a标签的默认跳转：

• 如果用原生JS实现跳转，需阻止a标签默认行为，使用history.pushState或history.replaceState更新URL并渲染对应页面
• 示例代码（阻止a标签默认行为）：

document.querySelectorAll('a[href^="/"]').forEach(link => {
  link.addEventListener('click', (e) => {
    e.preventDefault();
    const path = link.getAttribute('href');
    history.pushState({}, '', path);
    // 这里添加渲染对应页面的逻辑，比如切换组件/加载3D模型页面
    renderPage(path);
  });
});

3. 重新部署验证 #

将修改后的vercel.json和前端代码提交到GitHub，触发Vercel自动重新部署。部署完成后测试：

• 从首页跳转至子页面，确认能正常加载3D模型页面
• 直接访问子页面URL，确认不再返回404
• 刷新子页面，确认页面能正常渲染

内容的提问来源于stack exchange，提问作者Yash