30.2 路由重复点击报错、白屏、刷新 404 问题

这三个问题是 Vue Router 在开发和生产中最常见的“坑”，每个都能让页面直接崩掉或无法访问。下面分别说明现象、原因和解决方案。

一、路由重复点击报错：`NavigationDuplicated`

现象
用户连续快速点击同一个导航链接，或者代码中重复执行 router.push('/same-path')，控制台抛出类似这样的错误：

Uncaught (in promise) NavigationDuplicated: Avoided redundant navigation to current location: "/xxx".

虽然这个错误默认不会导致页面崩溃（Vue Router 内部捕获了），但在未处理 Promise 拒绝的情况下，浏览器控制台会变红，或者在一些错误监控系统中触发报警，造成困扰。

原因
Vue Router 4 在检测到导航到当前完全相同路由（包括路径、参数、hash）时，会拒绝这次导航并抛出 NavigationDuplicated 错误。这是一种保护机制，避免不必要的重复渲染。但如果你没有捕获这个 promise 的拒绝，错误就会冒泡到控制台。

解决方案
有两种思路，选其一即可：

全局统一处理：在创建 router 后，重写 push 和 replace 方法，自动捕获异常。

   // router/index.js
   const originalPush = Router.prototype.push
   Router.prototype.push = function push(location) {
     return originalPush.call(this, location).catch(err => err)
   }

这种写法在 Vue Router 4 中需要调整，因为 Router 构造函数已改变。更推荐的方式是在调用处进行 try-catch 或使用 .catch(() => {})，但全局处理依然可行：可以重写 router.push 包装：

   const push = router.push
   router.push = function (...args) {
     return push.apply(this, args).catch(() => {})
   }

对每个导航调用进行静默处理：如果只是个别地方，直接在 push 后加 .catch(() => {})。但重复点击场景通常是全局问题，所以第一种方案更省心。

另外，还可以从 UI 侧入手，如给导航按钮增加防抖、点击后添加 loading 状态禁用重复点击，从根源上减少冗余导航。

二、白屏问题：页面一片空白，控制台无报错或有模块加载错误

现象
访问某个页面时，页面完全空白，DOM 中可能只有 <div id="app"></div> 而没有任何内容。控制台可能报错“Cannot read property ... of undefined”，或者显示异步加载组件失败。

常见原因与解决办法

路由懒加载配置错误

原因：import() 语法写错，或者组件路径不正确，导致 Webpack / Vite 无法正确解析分块。
解决：检查路由配置中的 component 是否为函数，如 component: () => import('@/views/User.vue')。注意路径是否正确，尤其是在使用别名 @ 时，要确保 vite.config.js 或 webpack 配置了正确的别名解析。如果组件文件移动过但路由配置未更新，白屏是必然的。

动态导入的资源加载失败

原因：构建后的 JS 分块（chunk）在部署时遗漏，或者 CDN 路径不对，导致浏览器请求 404。
解决：检查打包后的 dist 目录中是否包含相应的 chunk 文件，确认服务器部署时所有资源都已上传，且公共路径（base）配置正确。

路由守卫未放行

原因：全局守卫（router.beforeEach）中有逻辑忘记调用 next() 或 return true，导致导航永远挂起；或者只对某些条件 next()，其他情况没有返回值，也会造成白屏。
解决：确保守卫中所有分支都明确调用 next() 或 return true（在 Vue Router 4 中，建议 return false 取消导航，return true 或 return undefined 表示允许）。例如：

     router.beforeEach((to, from) => {
       if (token) {
         return true
       } else {
         return '/login'
       }
     })

异步组件加载失败无兜底

原因：使用 defineAsyncComponent 加载组件时，网络异常或组件文件 404 导致加载失败，没有设置 errorComponent，结果加载失败后无内容显示。
解决：为异步组件配置错误处理组件，甚至重试逻辑。在路由懒加载中也可以结合 webpack 的魔法注释和错误边界处理，但最简单的办法是确保资源可访问。

第三方库兼容性问题

原因：某个组件内部使用了与当前环境不兼容的 API 或被 Tree Shaking 误删，导致 JS 执行中断。这时白屏是代码错误导致整个 Vue 应用挂载失败。
解决：检查控制台错误，逐步排查。可以尝试用 <Suspense> 包裹可能出错的组件，配合 onErrorCaptured 捕获错误。

快速排查技巧

用 Vue DevTools 查看组件树是否挂载。
查看 Network 面板，确认所有 JS chunk 都返回 200。
将路由组件暂时改为同步引入测试，排除异步加载问题。
在入口文件 main.js 中添加 app.config.errorHandler 全局捕获错误并输出更详细信息。

三、刷新 404 问题：history 模式的通病

现象
项目线上运行正常，点击页面内的链接跳转也没问题，但直接在浏览器地址栏按回车、或刷新页面，浏览器显示 404（Nginx/Apache 的默认错误页）。

原因
Vue Router 的 history 模式使用 HTML5 History API（pushState、replaceState）来改变 URL 而不重新加载页面。页面内的导航都是前端接管，服务器并未感知。但是，当用户直接访问 https://example.com/user/123，这个请求会发到服务器。服务器若没有配置处理这个特定路径，它就会尝试寻找 /user/123 对应的物理文件（比如一个 HTML 或后端接口），找不到就返回 404。而在 hash 模式下，URL 形如 /#/user/123，服务器只会请求根路径，不会遇到此问题。

解决方案
必须让服务器对所有（或指定的）前端路由都返回同一个入口 HTML 文件（如 index.html），然后由前端接管路由解析。 具体操作因服务器不同而有所差异：

| 服务器 | 配置示例 |
|--------|----------|
| Nginx | 在 location 块中添加 try_files $uri $uri/ /index.html; |
| Apache | 使用 .htaccess 配置 RewriteRule .* index.html [L] （需启用 mod_rewrite） |
| Node.js (Express) | app.use(history({ index: '/index.html' })) 使用 connect-history-api-fallback 中间件 |
| 开发环境 (Vite) | Vite 已内置 history fallback，不需额外配置；如果是自定义静态服务器，可能需要配置 |

举个 Nginx 的完整配置片段：

location / {
  root /usr/share/nginx/html;
  index index.html;
  try_files $uri $uri/ /index.html;
}

注意：如果有真实的 API 路径（如 /api），应该在前面的 location 规则优先匹配，避免被 fallback 规则捕获返回了 HTML。

如果是 SPA 部署在子目录（比如 https://example.com/app/），需要设置 Vue Router 的 base 选项为 /app/，并确保服务器的 fallback 也考虑了这个前缀。例如 Nginx：

location /app {
  try_files $uri $uri/ /app/index.html;
}

总结：刷新 404 是服务器配置问题，不是 Vue 代码问题。只要部署时记住“任何合理的路径都返回入口文件”这个原则，就能彻底解决。

以上三个问题在项目中几乎必遇，提前了解和配置好，可以避免大量线上 bug 和排查时间。

30.2 路由重复点击报错、白屏、刷新 404 问题

一、路由重复点击报错：NavigationDuplicated

二、白屏问题：页面一片空白，控制台无报错或有模块加载错误

三、刷新 404 问题：history 模式的通病

一、路由重复点击报错：`NavigationDuplicated`