Vue3项目中Vue-Router在生产环境无法正常工作

问题现象 #

本地localhost运行时Vue-Router正常工作，AppBar显示正常；项目构建部署后，AppBar消失，路由功能完全失效。

（生产环境异常状态）

（本地正常的AppBar状态）

以下是常见的排查和解决方向：

• 路由模式配置问题
  如果使用了history模式（createWebHistory()），生产环境服务器必须配置请求重定向到index.html，否则直接访问路由路径或刷新页面会出现404，导致路由组件无法加载，连带AppBar失效。

  • 临时解决方案：改成hash模式（createWebHashHistory()），无需服务器配置即可正常工作。
  • 永久解决方案：配置服务器重定向，比如Nginx添加规则：

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

• 路径大小写不匹配
  本地开发环境（Windows/macOS默认不区分文件大小写）不会报错，但生产服务器（多为Linux系统）严格区分大小写。如果路由中配置的路径（如/About）和组件文件路径（如about.vue）大小写不一致，构建后会找不到组件，导致路由失效。

  • 解决：统一路由路径和组件文件的大小写，保持完全一致。

• 构建基础路径(base URL)错误
  如果项目部署在服务器的子目录下，未配置正确的base路径，会导致构建后的资源（JS/CSS）加载失败，组件无法正常渲染。

  • Vite项目：在vite.config.js中设置base: '/你的子目录名/'；
  • Vue CLI项目：在vue.config.js中设置publicPath: '/你的子目录名/'；
  • 若部署在根目录，直接设为base: '/'即可。

• 路由懒加载路径错误
  使用路由懒加载时（如() => import('../views/Home.vue')），如果相对路径层级写错，本地开发可能通过热重载容错，但构建后会出现组件加载失败的错误，导致路由无法正常工作。

  • 解决：检查懒加载的组件路径，确保层级正确，也可以使用基于src目录的绝对路径（如@/views/Home.vue）避免层级错误。

• AppBar依赖的路由状态异常
  如果AppBar组件依赖$route或全局状态（如Pinia/Vuex）来控制显示，生产环境下可能因为打包优化（如Tree-shaking）导致相关逻辑被误删，或者状态初始化时机错误。

  • 解决：检查AppBar中的路由监听逻辑（如watch($route, ...)），确保在组件挂载后再访问路由对象；同时确认全局状态的初始化逻辑在生产环境下能正常执行。

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