企业官网建设流程全解析

如果你用 Vue 做项目，路由这件事迟早会成为你技术方案里绕不开的核心环节。尤其当组件越拆越细、页面越来越多之后，路由已经不只是"跳转链接"那么简单，它承担了状态管理、权限控制、页面缓存、异常兜底甚至部署策略的一部分职责。这篇内容我想从实际项目经历出发，聊聊 Vue Router 在不同阶段会遇到的典型场景，从基础配置到权限控制，再到线上环境常见的坑，基本上是跟着我自己的踩坑顺序写的，希望能给正在搞 Vue 路由的朋友一些能直接落地的参考。

1. 为什么每个 Vue 项目最终都要面对路由设计

1.1 路由不只是"地址和页面的映射表"

很多初学者会把路由理解为"URL 对应哪个组件"，这个理解方向没错，但只停留在表面上。真实项目里，路由其实是一个应用状态的分布式存储层——用户从哪个页面进来、能访问哪些页面、某个页面需要携带什么参数、刷新后状态能不能恢复，这些都跟路由设计直接相关。

我接手过好几个中期项目，最常见的问题就是路由写得太随意：所有页面一股脑注册在静态路由表里，权限靠组件内部判断，跳转靠router.push硬编码，参数全靠 query 传。表面上看项目能跑，但一旦涉及"用户未登录访问订单页""分享链接到详情页""从列表页进入编辑页但刷新后数据丢失"这些场景，问题就全暴露出来了。

Vue Router 设计得好，相当于给应用提前做好了导航层面的架构：谁是公开页，谁需要登录，谁需要特定角色，页面之间靠什么参数互联，路由切换时哪些状态要保留，异常路由怎么兜底，这些都应该在路由层就定下来，而不是散落在各个组件里"随机应变"。

1.2 Vue Router 3 和 Vue Router 4 怎么选

这是个绕不开的问题。Vue 2 生态搭配的是 Vue Router 3，Vue 3 搭配的是 Vue Router 4。如果你新开项目，现在基本不会再选 Vue 2 了，直接 Vue 3 + Vue Router 4 是默认组合。

Vue Router 4 相比 3 有几个感知很强的变化：

• 不再导出new Router()，而是改用createRouter和createWebHistory
• 路由模式不再写mode: 'history'，而是通过createWebHistory()函数决定
• 移除了*通配符路由，捕获所有路由改用自定义路径正则
• router-link的tag属性被移除，自定义标签要用v-slot实现
• 组件内导航守卫beforeRouteEnter等 API 保留，但类型推导更严格

这些变化不复杂，但如果你网上搜教程，很容易搜到 Vue Router 3 的旧代码，复制进 Vue 3 项目里直接报错。我建议新项目认准官网的 Vue Router 4 文档，示例代码基本都对得上。

2. 从基本配置到项目骨架落地

2.1 安装和初始化

先讲最基础的，假设你已经有一个 Vue 3 项目，安装路由只需要一条命令：

npm install vue-router@4

然后在src下建一个router目录，新建index.js，写最基础的配置：

import { createRouter, createWebHistory } from 'vue-router' import Home from '../views/Home.vue' const routes = [ { path: '/', name: 'Home', component: Home }, { path: '/about', name: 'About', // 路由懒加载，后面会细说 component: () => import('../views/About.vue') } ] const router = createRouter({ history: createWebHistory(), routes }) export default router

然后在main.js里注册：

import { createApp } from 'vue' import App from './App.vue' import router from './router' createApp(App).use(router).mount('#app')

这是最基础的骨架。注意createWebHistory()意味着路由走 HTML5 History 模式，URL 里没有#，好看，但部署到服务器时需要配置 fallback，否则用户直接访问https://example.com/about会 404。这个问题到后面打包部署部分我会详细讲，属于新手踩坑高发区。

2.2 层级路由设计：嵌套路由与独立页面的取舍

实际项目的页面结构不会像上面这么扁平。比如一个后台管理系统，通常有顶部导航、侧边栏、内容区三层结构，侧边栏切换时只有内容区变化，这种情况下嵌套路由是正解。

const routes = [ { path: '/admin', component: () => import('../layouts/AdminLayout.vue'), children: [ { path: 'dashboard', name: 'AdminDashboard', component: () => import('../views/admin/Dashboard.vue') }, { path: 'users', name: 'AdminUsers', component: () => import('../views/admin/Users.vue') } ] }, { path: '/login', name: 'Login', component: () => import('../views/Login.vue') } ]

父组件AdminLayout.vue里要放一个<router-view />，子路由渲染的位置就是它。这样设计的好处是布局组件只加载一次，切换子路由时只替换内容区，不会整个布局重新渲染，性能和体验都好很多。

但要注意一个点：独立页面和嵌套页面的边界。登录页、404 页、全屏预览页这些不需要布局的页面，应该放在嵌套路由外面，否则你会在一个带侧边栏的布局里渲染一个登录页，逻辑和样式都会很别扭。

2.3 命名路由与命名视图的使用场景

命名路由是我个人非常推荐在项目里推行的一个习惯。什么意思？就是在路由配置里给每个路由一个唯一的name，跳转时用名字跳，而不是写死路径：

// 不推荐 router.push('/admin/users?page=1') // 推荐 router.push({ name: 'AdminUsers', query: { page: 1 } })

好处是路径重构时不需要全局搜索字符串。比如/admin/users改成/admin/members，如果你全项目用了命名路由，只需要改路由配置文件一处即可，其他地方的跳转代码完全不用动。我维护过那种路径字符串散落得到处都是的旧项目，改一次路径要全局搜索替换，还经常漏改，非常痛苦。

命名视图解决的是另一个问题：一个页面有多个路由出口。比如一个布局页有 header、sidebar、content 三个区域，你想让某个路由同时控制这三个区域的渲染，就可以用到命名视图：

const routes = [ { path: '/dashboard', components: { default: () => import('../views/Dashboard.vue'), header: () => import('../components/DashboardHeader.vue'), sidebar: () => import('../components/DashboardSidebar.vue') } } ]

对应的模板里：

<router-view /> <router-view name="header" /> <router-view name="sidebar" />

这个功能在实际项目中用到的频率不算高，但遇到那种"一个路由要同时驱动多个区域变化"的场景，比如某些复杂的报表页面，能省掉很多手动状态同步的代码。

3. 页面跳转参数传递：query、params 与动态路由的边界

3.1 query 和 params 的区别

Vue Router 传参是面试高频题，也是实际开发中最容易用错的地方。两者最核心的区别：

• query：参数拼接在 URL 的?后面，比如/user?id=1。刷新页面后参数还在，因为它在 URL 里。
• params：参数通过路由配置里的动态字段传递，比如路由配置/user/:id，跳转时{ name: 'User', params: { id: 1 } }，最终 URL 是/user/1。

这里有个很多人踩过的坑：用params跳转时，如果只写了name+params，但路由配置里没有对应的动态字段，那么params会在刷新页面后丢失。比如：

// 路由配置 { path: '/user', name: 'User', component: User } // 跳转 router.push({ name: 'User', params: { id: 1 } })

URL 会变成/user，没有?id=1也没有/1，刷新后route.params.id就是 undefined。很多新手在这里卡很久，明明跳转的时候能拿到参数，一刷新就没了，原因就是 params 只存在于内存中，没有体现在 URL 上。需要持久化的参数，要么用动态路由字段，要么用 query，不要用这种方式传 params。

3.2 动态路由匹配与参数监听

动态路由匹配是详情页的标准解法，比如文章详情、商品详情，路径格式大致是/article/:id：

const routes = [ { path: '/article/:id', name: 'ArticleDetail', component: () => import('../views/ArticleDetail.vue') } ]

组件里通过route.params.id获取文章 ID，然后请求接口。这里有个细节很多人不知道：从/article/1跳转到/article/2，组件实例会被复用，也就是说created和mounted不会重新执行，你如果只在created里请求数据，会发现页面内容没变化。

解决办法是监听路由参数：

import { watch } from 'vue' import { useRoute } from 'vue-router' const route = useRoute() watch( () => route.params.id, (newId, oldId) => { if (newId !== oldId) { // 重新请求数据 fetchArticle(newId) } }, { immediate: true } )

或者用 Vue Router 内置的beforeRouteUpdate守卫，在组件内做处理：

async beforeRouteUpdate(to, from) { if (to.params.id !== from.params.id) { await this.fetchArticle(to.params.id) } }

这两种方式都行，我自己的习惯是选项式 API 项目用beforeRouteUpdate，组合式 API 项目用watch，代码结构更简洁。

3.3 路由参数为对象或数组时的处理

query 传参时，如果值是一个对象或数组，URL 上会怎么体现？很多人的第一反应是直接JSON.stringify塞进去，但 Vue Router 其实内置了处理逻辑。

在 Vue Router 4 中，query 的值可以是对象或数组：

router.push({ name: 'List', query: { filter: { type: 'all', status: 'active' }, tags: ['a', 'b'] } })

URL 会变成类似/?filter=%7B%22type%22%3A%22all%22%2C%22status%22%3A%22active%22%7D&tags=a&tags=b的编码格式。

对应地，从route.query里取出来时，Vue Router 会自动反序列化对象，数组也能正常还原。但要注意 URL 长度限制和可读性问题，复杂过滤条件塞在 URL 里会导致 URL 又长又难读，分享给别人也容易出问题，必要时还是考虑用 Pinia 这类状态管理器来维护筛选状态，路由 query 只保留像page、keyword这种真正需要分享和刷新的轻量参数。

4. 路由守卫：从登录拦截到异步权限控制的进阶路径

4.1 全局前置守卫与登录态校验

聊完传参，接着讲路由守卫。这是路由从"页面导航工具"升级为"应用架构组件"的关键一环。

全局前置守卫beforeEach最常见的用途是登录校验。核心逻辑就三件事：判断目标页面是否需要登录、判断用户是否登录、未登录则跳转到登录页：

router.beforeEach((to, from) => { const isLoggedIn = localStorage.getItem('token') if (to.meta.requiresAuth && !isLoggedIn) { return { name: 'Login', query: { redirect: to.fullPath } } } return true })

这里有两个细节值得展开。

第一个是返回登录页后要记住用户想去的页面。上面代码里query: { redirect: to.fullPath }就是干这个的，登录成功后跳回route.query.redirect指向的页面，而不是每次登录完都丢回首页，这个细节对用户体验影响很直接。

第二个是守卫里不要主动读 Pinia。有朋友在beforeEach里用useUserStore()获取登录状态，但如果在 Pinia 还没安装完成时就触发守卫，会拿不到 store 实例。稳妥做法是在main.js里把pinia先安装，再安装router，或者在守卫里直接读 localStorage / sessionStorage 这类持久化数据做判断。

4.2 动态路由与权限菜单的实现思路

后台管理系统差不多都会遇到权限控制：不同角色看到的菜单不同，能访问的页面也不同。业界比较成熟的方案是前端只注册公共路由（登录页、404 页），登录成功后根据用户角色从后端拉取可访问的页面列表，动态注册到路由表里。

具体到实现，Vue Router 4 提供了router.addRoute()方法，可以动态添加路由：

// 登录成功后 const userMenus = await fetchUserMenus() // 将后端返回的菜单数据格式化成路由对象 const dynamicRoutes = userMenus.map(menu => ({ path: menu.path, name: menu.name, component: () => import(`../views/${menu.component}`) // 注意动态 import 的坑 })) // 动态添加 dynamicRoutes.forEach(route => { router.addRoute('AdminLayout', route) })

这里有个很隐蔽的坑：动态 import 的路径不能完全用变量拼接。Vite 和 Webpack 在打包时是静态分析import()参数的，import(../views/${menu.component})这种写法在打包阶段无法确定具体模块，打包后可能会报错"无法解析模块"。

我验证过可行的做法有两种：

一种是用import.meta.glob（Vite 专用）：

const viewModules = import.meta.glob('../views/**/*.vue') const component = viewModules[`../views/${menu.component}.vue`]

另一种是在配置文件里维护一个组件映射表：

const componentMap = { 'admin/Dashboard': () => import('../views/admin/Dashboard.vue'), 'admin/Users': () => import('../views/admin/Users.vue') } const component = componentMap[menu.component]

第二种代码写起来累一点，但明确可控，没有打包器的黑魔法，我推荐团队协作项目用映射表方案。import.meta.glob虽然方便，但团队成员不熟悉的话容易写错路径格式，排查起来麻烦。

4.3 组件内守卫的三个时机

除了全局守卫，Vue Router 还提供了组件内守卫，适合处理"只对当前页面生效的导航逻辑"：

• beforeRouteEnter：进入路由前执行，此时组件实例还没创建，所以不能访问this，但可以在next回调里拿到实例。
• beforeRouteUpdate：路由参数变化但组件复用时执行，比如详情页从 ID 1 切到 ID 2。
• beforeRouteLeave：离开路由前执行，适合做"表单未保存是否确认离开"这类交互。

实际项目里我用得最多的是beforeRouteLeave，比如一个表单页，用户填了一半不小心点了侧边栏跳到其他页面，这时代价很大。在守卫里拦截一下：

// 组合式 API 写法 onBeforeRouteLeave(() => { if (formStore.isDirty) { const confirmed = window.confirm('当前页面有未保存的内容，确定要离开吗？') if (!confirmed) return false } return true })

返回false就取消导航，非常干净。用这种守卫比在侧边栏组件里监听路由变化要可靠得多，因为守卫是路由层面的拦截，不依赖 UI 组件的状态。

5. 常见疑难：打包后布局异常、路由跳转组件渲染不显示

5.1 打包后发现样式、布局异常

这个热搜词排得很前，说明遇到的人不少。先说结论：Vue 项目打包后布局异常，绝大多数原因不在路由本身，而是静态资源路径和路由模式设置的组合问题。

典型场景是：本地开发一切正常，npm run build后丢到服务器，发现页面白屏、CSS 加载不出来、图片 404。最常见的根源是 Vite 配置里的base路径。

默认配置下，Vite 打包生成的静态资源引用路径是绝对路径/assets/xxx.js，如果你的项目部署在域名根路径，比如https://example.com/，那没问题。但如果你部署在子路径下，比如https://example.com/admin/，浏览器解析/assets/xxx.js时会去域名根目录找，自然就 404 了。

解决办法是在vite.config.js里设置base: './'（相对路径），或者设置成你实际的部署子路径：

// vite.config.js export default defineConfig({ base: './', // 或 '/admin/' // ... })

另外，路由的history也需要配合。还是拿子路径部署举例，createWebHistory()默认根路径是/，你部署在/admin/下，就需要写成createWebHistory('/admin/')，否则路由路径和真实路径对不上，刷新会 404。

5.2 路由跳转后组件内容不渲染的排查链路

"router vue3 路由跳转 组件内容渲染不显示"也是热搜里的高频问题。我遇到过很多次，这里完整走一遍排查链路。

第一步：确认 URL 变了但内容没变。

• 如果 URL 没变，说明跳转指令本身没生效，检查是否用了<a href="/xxx">而不是<router-link to="/xxx">。在 SPA 里用原生a标签跳转，浏览器会重新加载页面，但这不算路由跳转，也不会触发 Vue 组件渲染。

第二步：看控制台有没有报错。 按 F12 打开控制台，常见的报错：

• Uncaught (in promise) NavigationDuplicated—— 重复跳转到同一路由，Vue Router 3 会报这个错，4 已确认不再是 error，但如果你项目里还有人写router.push不加catch，可能影响后续代码。推荐跳转统一封装，catch掉重复导航。
• Cannot read properties of undefined (reading 'xxx')—— 通常是路由配置的组件没正确导入，或者组件内部访问了不存在的属性。

第三步：确认<router-view>位置对不对。 如果嵌套路由配置了，但父组件里没有<router-view />，子路由组件就没地方渲染。这个看着低级，但当我一手滑把根组件的<router-view>删了的时候，整个页面就是空白的，排查了十分钟才反应过来。

第四步：检查是否有同名的路由 name 冲突。 Vue Router 4 注册同名路由时，后者会覆盖前者，但行为可能不符合预期。比如你注册了一个/user/list和/user/detail，结果两个都叫User，跳转时{ name: 'User' }只会跳到最后注册的那个。我在项目里就遇到过一次，两个模块的人各自注册了名为List的路由，结果点菜单永远跳到别人的页面。排查方式：打印router.getRoutes()，看看有没有同名路由，顺便检查路由的name是否全局唯一。

5.3 刷新页面 404 的问题

这个坑基本每个用 History 模式的人都会碰到一次。本地开发时刷新没问题，因为开发服务器做了 fallback，不管什么路径都给你返回index.html。但部署到 Nginx 后，静态服务器找不到/about这个真实文件，直接返回 404。

Nginx 的标准配置是在location /里加 try_files：

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

意思是：先尝试 URL 对应的真实文件，找不到就返回/index.html，让 Vue Router 接管路由解析。

如果你用了子路径部署，比如/admin/，Nginx 配置要对应调整：

location /admin/ { alias /var/www/myapp/; try_files $uri $uri/ /admin/index.html; }

类似的问题在 Apache、Caddy 等服务器上也有对应配置，思路一致：单页应用的所有 URL 都应该 fallback 到入口 HTML。记住这个原则，换什么服务器都能举一反三。

6. 路由性能优化与代码组织的最佳实践

6.1 路由懒加载与分包策略

大型项目如果不做路由懒加载，首屏会加载所有页面的 JS，那将是灾难性的慢。Vue Router 支持组件写函数形式，实现按需加载：

// 不懒加载 component: Home // 懒加载 component: () => import('../views/Home.vue')

Vite 会自动把懒加载的路由组件拆分成单独的 chunk，用户访问时才加载对应页面的代码。

如果你的页面里有些第三方库特别大，比如富文本编辑器、ECharts、Excel 导出库，还可以用 Webpack/Vite 的注释语法做更细的分包：

component: () => import(/* webpackChunkName: "editor" */ '../views/Editor.vue')

但在 Vite 里注释有所不同，Vite 使用的是/* @vite-ignore */等方式，且 chunk 命名一般通过build.rollupOptions.output.manualChunks配置。对于大多数项目，最省心的还是保持"默认分包 + 按需引入第三方库"，不要过度优化。我见过团队为了优化首屏，把路由拆得特别碎，结果每个 chunk 都只有几 KB，HTTP 请求数量暴增，反而拖慢了加载速度。

6.2 meta 字段：路由信息的配置中心

给路由加meta字段是我非常推荐的项目规范。只要是跨页面共享的、跟页面身份相关的信息，都可以放进去：

{ path: '/admin/users', name: 'AdminUsers', component: () => import('../views/admin/Users.vue'), meta: { title: '用户管理', icon: 'user', roles: ['admin', 'operator'], keepAlive: true, hidden: false } }

比如：

• 网页标题：在全局守卫里统一读取to.meta.title设置document.title
• 侧边栏菜单：遍历路由表生成菜单，meta.hidden控制是否展示
• 权限判断：meta.roles声明哪些角色能访问
• 页面缓存：配合<keep-alive>的include，通过meta.keepAlive决定是否缓存页面

统一用 meta 管理这些信息，避免在组件里写死页面标题、菜单逻辑硬编码到视图层，后期维护会舒服很多。

6.3 keep-alive 与路由缓存

回到热搜词里那个"组件内容渲染不显示"，还有一个容易被忽略的原因是<keep-alive>和路由配合不当。

当路由组件被缓存时，组件实例会被保留，切换回来自动恢复之前的状态，这通常是好事。但如果你缓存的组件里有定时器、WebSocket、地图实例这类资源，离开页面时没有在onDeactivated或beforeRouteLeave里清理，回到页面就会看到"内容不刷新"或"功能异常"。

经验是：缓存要按需开启，不要一股脑全缓存。我的做法是在根组件的<router-view>外层配合meta.keepAlive动态决定是否缓存：

<template> <router-view v-slot="{ Component }"> <keep-alive :include="keepAliveComponents"> <component :is="Component" /> </keep-alive> </router-view> </template> <script setup> import { computed } from 'vue' import { useRoute } from 'vue-router' const route = useRoute() const keepAliveComponents = computed(() => { return route.meta.keepAlive ? [route.name] : [] }) </script>

这只是最简单的一种联动写法，真实项目里缓存列表通常是从路由表中聚合出来的，再加上用户关闭标签页时清除缓存的逻辑。总之核心思路是：meta 里声明这个页面是否需要缓存，路由层控制 keep-alive 的 include 列表。这样规则透明，新人接手也能看懂。

6.4 滚动行为与过渡效果的细节

路由切换时，默认情况下浏览器的滚动位置会保留。用户从列表页往下翻了 500px，点进详情页再返回，希望回到原来的位置，这时候就需要用滚动行为来控制。

Vue Router 4 支持通过scrollBehavior配置全局滚动行为：

const router = createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { // 浏览器前进后退时恢复到原来位置 if (savedPosition) { return savedPosition } // 普通跳转回到顶部 return { top: 0 } } })

还可以配合el属性滚动到指定元素位置：

scrollBehavior(to) { if (to.hash) { return { el: to.hash, top: 80 } } return { top: 0 } }

这些细节用户感知度很高，但实现成本极低，值得加。

过渡动画方面，可以用<transition>包裹<router-view>：

<router-view v-slot="{ Component }"> <transition name="fade" mode="out-in"> <component :is="Component" /> </transition> </router-view>

注意mode="out-in"很重要，没有它会出现旧页面和新页面同时存在的闪烁。但也要注意：如果同时用<transition>和<keep-alive>，顺序是先transition再keep-alive：

<router-view v-slot="{ Component }"> <transition name="fade" mode="out-in"> <keep-alive> <component :is="Component" /> </keep-alive> </transition> </router-view>

顺序错了会导致缓存不生效或动画异常，这也是个隐蔽的坑。

7. 我这几年用路由的一点实际体会

聊到最后，想分享几个从实际项目里摸出来的经验。

第一个是路由文件一定要保持可读性。项目大了之后，路由表会很长，我的习惯是把路由按模块拆成多个文件，例如router/modules/user.js、router/modules/order.js，再在router/index.js里统一组装。这不是什么高级技巧，但对团队协作和代码 review 帮助很大，不然一个routes数组几百行，谁改谁都头疼。

第二个是跳转方法建议封装一层。项目里不要到处直接router.push，可以封装一个useNavigate之类的工具，统一处理埋点、权限校验、错误捕获。尤其在后端返回 401 时，可以在统一封装里拦截并跳转登录页，而不是每个业务页面自己去判断，能少写很多重复代码。

第三个是路由不是越复杂越好。Vue Router 能做很多事，但有些需求没有必要都塞给路由。比如多级菜单导航，如果层级特别深，路由配置会变得非常绕，我见过有人为了做三级菜单把路由嵌套到四层，结果meta继承、菜单生成全乱套。其实可以考虑用扁平路由 + 菜单数据单独管理的方案，路由只负责页面跳转，菜单结构由静态配置或后端返回的菜单树维护。每次新增页面时，对一个"路由表 + 菜单表"，工作量差不多，但心智负担会小很多。

第四个也是最后一个，路由守卫不是只写一次就完事的。权限规则、免登录白名单、跳转逻辑，都会随着业务迭代不断变化。建议每次改权限相关需求时，把router.beforeEach完整读一遍，确认整体链路没有因为某次改动留下逻辑漏洞。权限这种东西，出问题通常不是瞬间崩掉，而是某些用户在某些边界条件下能访问到本不该看到的页面，这类问题上线后很难发现，所以守卫代码务必保持简单直白，任何人接手都能一眼看懂。我自己早期的项目里就有一段写了三层 if 嵌套的守卫逻辑，几个月后自己回过去看都要捋半天，后来重构掉了，换成了明确的判断表，清爽得多。

Vue Router 是个基础又不基础的库。基础到每个项目都在用，不基础在于它和构建配置、部署策略、权限方案、组件缓存都纠缠在一起。这篇文章里的每一个坑，都是我实际踩过、排查过、最后沉淀下来的，希望对你手头的项目有直接的参考价值。如果你也在路由上踩过其他有意思的坑，欢迎在评论区聊一聊，很多问题只有真实碰过了才知道解决方案远不止一种。