企业官网建设流程全解析

搞过后台管理系统的朋友应该都遇过这种诡异场景：A账号是普通运营，登出之后换成管理员登录，结果侧边栏还残留着普通运营那几个菜单；或者某个页面明明在路由表里写着，刷新一下直接白屏，被踢到404。这些问题十有八九都出在动态路由和路由重置上。再往后，做表单提交又冒出一堆幺蛾子——校验不生效、resetFields 清不掉红字、快速连点按钮发出多次请求，这里又牵扯到了 $ref 和表单验证流程。最近我在负责一个典型权限型中后台项目（我们内部叫它模拟项目X），上面这些问题几乎全踩了一遍，今天把处理思路和最终落地的代码整理出来，给同样卡在动态路由、路由重置、常量路由、$ref、表单验证流程上的朋友一个可以直接对照的参考。

1. 项目场景与整体思路：为什么会踩到动态路由和表单验证的坑

1.1 模拟项目X的需求：按角色渲染菜单与页面

模拟项目X是一个典型的多角色中后台管理系统，主要角色有三类：

• 超级管理员（admin）：可见所有菜单，包括用户管理、角色管理、系统配置、数据分析。
• 运营人员（operator）：只能看到数据分析、内容审核相关页面。
• 访客（guest）：只能看到首页仪表盘和基础资料页。

登录之后，左侧菜单必须根据角色动态渲染；直接敲 URL 访问没有权限的页面，必须被拦截下来；账号登出之后换另一个账号登录，绝对不能看到上一个账号遗留下来的菜单。这些需求靠写死的静态路由表很难满足，必须引入动态路由机制。

表单需求也分布在各个角落：登录表单、用户新增/编辑弹窗、角色配置弹窗、审核操作表单。每个表单都要做必填校验、格式校验、长度校验，提交时必须等校验通过才能发请求，关闭弹窗后要把表单状态彻底清干净。这些操作里最常用的工具就是 $ref 绑定表单实例，然后走一套标准的表单验证流程。

1.2 权限模型设计：常量路由保底，动态路由扩展

在设计权限路由时，我习惯把路由分成两层：

• 常量路由：所有登录用户都能访问，不依赖任何权限。包括登录页、404 页、首页仪表盘这些基础页面。它们不需要额外注册，在创建路由实例时就已经存在。
• 动态路由：依赖当前用户的角色权限，登录后根据用户角色临时生成。比如用户管理、角色管理、系统配置这些业务页面，只有特定角色能看到。

有人会问：那我能不能不搞动态路由，把全部页面都注册进路由表，显示菜单时再做权限过滤？可以，但有一个很明显的安全隐患：页面虽然不在菜单里，但路由本身是存在的，只要猜到路径就能直接访问。动态路由从路由表层面把无权限页面过滤掉，等于从入口处拦住越权访问，这是更稳妥的做法。常量路由和动态路由分开管理，也方便后续加页面、调权限时不容易互相污染。

1.3 为什么路由重置和表单验证往往一起出问题

表面上看，路由重置属于路由层，表单验证属于组件交互层，两个东西好像不搭界。但在实际项目里，它们经常在同一段登出流程、同一个弹窗提交逻辑里碰头，而且本质问题都一样：状态没有清理干净。

动态路由是全局的单例状态，注册到 router 实例后，不会因为组件销毁、页面切换而自动消失。登出时不主动重置路由，下一次登录做动态添加时，就会出现旧路由残留、同名路由覆盖、菜单混乱这些问题。表单校验状态是组件实例的内部状态，弹窗关闭后组件被销毁，但如果是常驻表单组件或者用 keep-alive 缓存的页面，校验红字和表单值就可能残留到下一次打开。理解了这一点，就会发现它们是同一类问题，处理的思路也很像：什么时候产生状态，就必须在什么时候清理状态。

2. 常量路由与动态路由的划分方案

2.1 路由表怎么组织最不容易乱

我见过不少项目把路由全部堆在一个 router.js 里，几十个路由配置横着排，看起来就很费劲。为了不后期维护时崩溃，建议把路由分成三个文件：

• src/router/index.js：负责创建 router 实例，挂载常量路由和全局守卫。
• src/router/routes.js：集中导出 constantRoutes（常量路由）和 asyncRoutes（动态路由模板）。
• src/store/modules/permission.js：负责动态路由的过滤、添加、重置。

常量路由的写法很直接，注意每个需要动态登录后才能访问的基础页面也放在这里，比如首页仪表盘：

// src/router/routes.js export const constantRoutes = [ { path: '/login', name: 'Login', component: () => import('@/views/Login/index.vue'), meta: { title: '登录', hidden: true } }, { path: '/', name: 'Dashboard', component: () => import('@/views/Dashboard/index.vue'), meta: { title: '首页仪表盘', icon: 'home' } }, { path: '/404', name: 'NotFound', component: () => import('@/views/Error/404.vue'), meta: { title: '页面不存在', hidden: true } } ]

动态路由模板是完整权限路由的“原始素材”，每个路由的 meta 里通过 roles 字段声明可见角色。这里用 Layout 作为父级组件承载侧边栏和顶栏，子路由才是真正的业务页面：

export const asyncRoutes = [ { path: '/system', name: 'System', component: Layout, meta: { title: '系统管理', icon: 'setting' }, children: [ { path: 'user', name: 'SystemUser', component: () => import('@/views/System/User/index.vue'), meta: { title: '用户管理', roles: ['admin'] } }, { path: 'role', name: 'SystemRole', component: () => import('@/views/System/Role/index.vue'), meta: { title: '角色管理', roles: ['admin'] } } ] }, { path: '/content', name: 'Content', component: Layout, meta: { title: '内容管理', icon: 'document' }, children: [ { path: 'audit', name: 'ContentAudit', component: () => import('@/views/Content/Audit/index.vue'), meta: { title: '内容审核', roles: ['operator'] } } ] } ]

这里有个容易踩的细节：父级 Layout 的 meta 里不要写 roles，或者写了也要注意，因为下面过滤逻辑在判断父级时如果父级没有 roles，就默认放行。但放行之后还要继续递归子级，子级如果全部被过滤掉，这个父级路由就只剩一个空壳 Layout，菜单渲染时会显示一个空分组，甚至点击后页面空白。所以过滤之后必须清理掉 children 为空的路由。

2.2 按角色过滤动态路由的过滤函数

过滤逻辑一般放在 permission store 里，核心是两层递归：判断当前路由是否允许当前角色访问，然后逐层处理它的 children。

// src/store/modules/permission.js import { constantRoutes, asyncRoutes } from '@/router/routes' function hasPermission(roles, route) { if (route.meta && route.meta.roles) { return roles.some(role => route.meta.roles.includes(role)) } return true } export function filterAsyncRoutes(routes, roles) { const res = [] routes.forEach(route => { const tmp = { ...route } if (hasPermission(roles, tmp)) { if (tmp.children) { tmp.children = filterAsyncRoutes(tmp.children, roles) if (tmp.children.length === 0) { return // 子路由全部被过滤，父级也没必要保留 } } res.push(tmp) } }) return res }

这段代码为什么必须用递归而不是简单的 filter？因为动态路由大多是多层嵌套结构，父级路由本身没有页面逻辑，只是承载 Layout 和菜单分组。只有深入到最底层的子路由，才能真正判断角色权限。递归过滤后，再判断顶层路由是否还保留着有效子级，这一步很多人会漏，漏掉的结果就是菜单里多出一大堆空分组。

2.3 路由与菜单的双向关联

动态路由生成后，左侧菜单一般直接由生成后的路由表递归渲染，不要另外维护一份菜单配置，否则动态路由一改，菜单和实际页面权限就对不上。菜单树和路由树的对应关系应该是：用 filterAsyncRoutes 过滤后的结果作为菜单数据源，meta.title 作为菜单名称，meta.icon 作为菜单图标，children 递归渲染成子菜单。

递归菜单组件写起来不复杂，核心是判断当前节点是否还有可显示的 children。有一个小细节：如果 children 里全部是 meta.hidden 为 true 的路由，这个菜单节点也应该隐藏，否则会出现一个点了没反应的菜单项。所以递归渲染时，过滤逻辑最好和菜单显示逻辑共用同一套判断，避免不一致。

3. 动态路由添加与重置的落地实现

3.1 addRoute 的两种挂载方式

Vue Router 4 提供了 router.addRoute 方法，用来动态追加路由，有两种常见用法。

第一种是直接挂载一个顶层路由：

router.addRoute({ path: '/system', name: 'System', component: Layout, children: [...] })

第二种是给已有的父级路由追加子路由，比如在某个 Layout 下动态挂一个新的子页面：

router.addRoute('System', { path: 'menu', name: 'SystemMenu', component: () => import('@/views/System/Menu/index.vue'), meta: { title: '菜单管理', roles: ['admin'] } })

项目里通常把过滤后的结果循环 addRoute 挂到顶层。注意：如果动态路由是一个带 Layout 父级的多层结构，一次 addRoute 顶层路由，Vue Router 会自动把它内部的 children 一并注册，所以不需要逐个挂子路由。我见过有人在循环里先 addRoute 父级再 addRoute 每个子级，结果路由重复注册，刷出警告，这没必要。

生成路由并添加的完整流程放在 permission store 的 generateRoutes 里：

async generateRoutes(roles) { let accessRoutes = filterAsyncRoutes(asyncRoutes, roles) accessRoutes.forEach(route => { router.addRoute(route) }) this.routes = constantRoutes.concat(accessRoutes) this.addedRoutes = accessRoutes return accessRoutes }

这里有一个时效性问题：addRoute 完成之后，如果当前导航还在 beforeEach 里，目标路由可能依然匹配不上。所以守卫里生成完动态路由，必须重新执行一次导航，具体写法在第五章细说。

3.2 登出时如何彻底清除动态路由

这是整个动态路由方案里最容易翻车的环节。Vue Router 添加的路由是全局单例，页面即使刷新，只要不重置，动态路由就还静静躺在路由表里。登出不清理，下一个账号登录时这些路由依然存在，菜单和权限就会瞬间混乱。

清理思路有很多种，我推荐的是“登记名字、逐个移除”的方案。在生成动态路由时，把顶层路由的名字记下来，登出时遍历这些名字调用 router.removeRoute：

// permission store 额外维护两个集合 const addedRouteNames = new Set() function recordRouteNames(routes) { routes.forEach(route => { if (route.name) { addedRouteNames.add(route.name) } }) } function resetRouter() { addedRouteNames.forEach(name => { if (router.hasRoute(name)) { router.removeRoute(name) } }) addedRouteNames.clear() }

这里只记录顶层路由名字就够了，因为 removeRoute 移除一个顶层路由时，它关联的整棵子树都会被移除。如果动态路由里还混着一些散落的独立页面路由（不挂在 Layout 下），同样把它们的 name 登记进去，登出时一并移除。

为什么不用 router.getRoutes() 去遍历找动态路由？因为这个方法返回的是全部扁平化记录，想要精确区分哪些是常量路由、哪些是动态添加的，就得维护一份常量路由 path 或 name 列表，反而更麻烦。直接在自己可控的生成流程里把 names 记下来，是最不容易出错的做法。

3.3 路由重置的边界情况：刷新、角色切换

路由重置最典型的场景是登出，但角色切换时也需要处理。比如同一个用户被管理员改了角色，下次登录时应按新角色生成动态路由。如果代码里只是简单判断“动态路由已生成就不再重复生成”，用户可能会一直用旧权限，甚至因为旧路由没清，新路由 addRoute 时出现同名覆盖警告。

处理方案有两个方向：

• 强制重新登录：修改角色成功后，调用 logout 清空所有状态，再跳到登录页重新登录。
• 在重新拉取用户信息时先 resetRouter，再重新执行 generateRoutes。

我更推荐先调用 resetRouter 再重新生成，因为体验上更顺滑，用户不需要重新输入密码。但要注意时序：必须先移除旧路由，再添加新路由，否则新旧路由可能短暂共存。另外，重置路由后，原本基于旧路由缓存的路由记录（比如 keep-alive 组件）可能残留，最好一并清理相关缓存，否则用户切角色后还可能看到旧组件内容。

4. $ref 与表单验证流程

4.1 $ref 在 Vue 3 组合式 API 中的正确打开方式

Vue 2 时代我们在 options API 里写 this.$refs.formName 就能拿到表单组件实例；到了 Vue 3 组合式 API，this 没了，改成了用 ref 声明引用：

<template> <el-form ref="formRef" :model="form" :rules="rules"> <el-form-item label="用户名" prop="username"> <el-input v-model="form.username" /> </el-form-item> <el-form-item label="邮箱" prop="email"> <el-input v-model="form.email" /> </el-form-item> </el-form> </template> <script setup> import { ref, reactive } from 'vue' const formRef = ref(null) const form = reactive({ username: '', email: '' }) const rules = { username: [ { required: true, message: '请输入用户名', trigger: 'blur' } ], email: [ { type: 'email', message: '请输入正确的邮箱地址', trigger: ['blur', 'change'] } ] } </script>

在模板里写 ref="formRef" 后，formRef.value 就指向 el-form 组件实例，可以直接调用实例暴露出来的 validate、resetFields、clearValidate 等方法。这里有一个很容易忽略的前提：el-form 这类组件必须在内部通过 defineExpose 暴露这些方法你才能在外面调用。Element Plus 的 el-form 已经帮我们封装好了，但如果你是自己写的自定义组件，不上 defineExpose，外面拿到的实例就是空的，调用方法时会直接报 undefined。

4.2 一步不落的标准校验流程

表单验证的标准流程可以概括成四个环节：定义校验规则、给表单项绑定 prop、触发校验、根据结果决定是否发请求。

第一，校验规则必须写在 rules 对象里，并且字段名一定要和 form 里的属性名保持一致。第二，el-form-item 上必须绑定对应 prop，否则校验规则无法和表单项关联，这是最常见的“规则写了但不生效”的原因。第三，提交时调用组件实例的 validate 方法，它返回一个 Promise：

async function handleSubmit() { if (!formRef.value) return try { await formRef.value.validate() // 校验通过，可以发请求 } catch (error) { // 校验不通过，错误信息已经显示在对应表单项下 return } }

有些文档里会写 validate 的回调形式，Element Plus 3.x 也兼容回调，但 promise 形式更适合配合 async/await 阅读和维护。需要注意一点：Element Plus 的 validate 在校验失败时 reject 的错误对象是一个字段集合对象，主要用来排查，生产环境直接把 catch 留空返回即可。

如果想要更好的提示体验，可以给提交按钮加 loading 状态，防止用户在校验期间或请求期间重复点击。这个细节我会在第五章展开。校验通过的下一步再走请求逻辑，整个流程才能保证“先校验，再提交”。

4.3 resetFields 与 clearValidate 的边界

表单提交成功后，尤其弹窗表单，需要清理表单状态。很多新人会直接调用 resetFields，发现有些表单项字段没清空或红字还在，其实是因为这两个方法职责不同：

注意一点：resetFields 重置的是“表单初始值”。如果组件刚渲染时 form 里 username 初始值是 ''，那调用 resetFields 后它始终回到 ''。如果初始值是从接口拉回来的数据，resetFields 并不会把字段重置为空，而是重置回组件挂载时的初始值。所以弹窗打开时，要重置成空表单，最好手动把 form 的字段重新赋值，再配合 resetFields 或 clearValidate 清掉红字。

function handleOpenDialog() { nextTick(() => { formRef.value.clearValidate() // 先清掉红字 }) Object.assign(form, { username: '', email: '' }) }

为什么用 nextTick？因为弹窗如果是懒渲染（首次打开才渲染表单），直接调用 ref 可能拿不到实例，必须等下一轮渲染结束后才能安全操作。

5. 路由守卫、权限按钮与表单提交的联动设计

5.1 守卫里的完整登录与动态路由生成流程

路由守卫是把动态路由、用户信息、登录状态串联起来的关键环节。模拟项目X里的 beforeEach 流程是这样的：

判断 token 是否存在。没有则跳登录页，有则继续。如果有 token 但还没拉取用户信息和动态路由，就生成动态路由；生成完重新导航一次目标路由，保证匹配。

router.beforeEach(async (to, from, next) => { const userStore = useUserStore() const permissionStore = usePermissionStore() if (!userStore.token) { if (to.path === '/login') { return next() } return next(`/login?redirect=${encodeURIComponent(to.fullPath)}`) } if (to.path === '/login') { return next('/') } if (permissionStore.routesGenerated) { return next() } try { await userStore.getUserInfo() const accessRoutes = await permissionStore.generateRoutes(userStore.roles) accessRoutes.forEach(route => router.addRoute(route)) permissionStore.setRoutesGenerated(true) // 动态路由刚刚添加，当前目标可能还没匹配上，必须重新导航 return next({ ...to, replace: true }) } catch (error) { await userStore.resetToken() return next('/login') } })

这里最关键的一步是next({ ...to, replace: true })。首次访问某个需要动态路由的页面时，beforeEach 已经执行到动态路由生成，但 Vue Router 是在导航完成后才用新路由表匹配目标，此时直接 next() 会发现找不到该路由而跳 404。重新导航一次，让路由表包含新动态路由后再匹配，就能正确命中页面。

5.2 按钮级权限怎么和动态路由配合

动态路由解决了页面级权限，但一个页面上有些按钮也不该所有人都能看见。比如用户管理页，管理员能看到“新增用户”“删除用户”，运营人员可能只能看不能操作。按钮级权限通常用自定义指令实现，我在项目里封装了一个 v-permission：

// src/directives/permission.js import { useUserStore } from '@/store/modules/user' export default { mounted(el, binding) { const roles = useUserStore().roles const requiredRoles = binding.value if (requiredRoles && !roles.some(role => requiredRoles.includes(role))) { el.parentNode && el.parentNode.removeChild(el) } } }

使用方式：<el-button v-permission="['admin']">新增用户</el-button>。

按钮权限和路由权限是两层防线，两者都要做。路由权限拦的是整页访问，按钮权限拦的是页内操作。不要想着用按钮权限替代路由权限，因为用户完全可以通过地址栏访问页面，这时按钮权限根本不会触发。

5.3 提交表单时的加载态与防重复

表单验证通过后，发请求阶段很容易出现另一种常见问题：用户快速连点提交按钮，导致同一请求发出多次。规避方法是在校验通过后立刻给按钮加 loading，并在请求完成后解除：

async function handleSubmit() { if (submitting.value) return try { await formRef.value.validate() } catch { return } submitting.value = true try { await createUser(form.value) ElMessage.success('添加成功') dialogVisible.value = false } finally { submitting.value = false } }

模板里给按钮绑定 :loading="submitting"。注意 submitting 必须在发起请求前先置为 true，而不是在请求函数内部才置，否则两次点击间会有空窗期。这个模式在动态路由重置后重新登录时也同样适用，比如登出按钮也可以加 loading，防止用户连点触发多次登出逻辑。

6. 常见问题与排查技巧实录

6.1 刷新后白屏、404问题

动态路由最大的坑就是刷新后路由表里没有目标路由。因为刷新会重建整个应用，store 内存状态被清空，动态路由需要重新生成。如果 beforeEach 里判断“routesGenerated”的逻辑写得不对，会出现几种现象：

• 刷新后直接白屏，没有任何报错。
• 刷新后跳转 404。
• 刷新后停留登录页但 token 明明还在。

排查思路很简单：在 beforeEach 里加日志，确认刷新后是否进入了“生成动态路由”的分支。如果没有，说明你早早在本地缓存里存了一个“已生成路由”的标记，刷新后直接跳过了生成逻辑。正确的做法是：标记只能保存在内存里，刷新后必须重新拉取用户信息并重新生成路由。刷新后 store 被清空，本身就是重新生成动态路由的时机，不要试图用 localStorage 保存这个标记来优化，那样只会带来状态不一致。

6.2 重复添加路由的告警处理

如果控制台出现 “Route with name 'xxx' already exists” 警告，多半是动态路由被重复添加。Vue Router 4 对重复添加同名路由的处理是覆盖，但会抛出警告，同时旧路由的某些子路由可能残留，导致菜单出现异常项。

解决方式：在 generateRoutes 前先 resetRouter，或者在 addRoute 前判断 router.hasRoute(route.name)，已存在就跳过或先 removeRoute。我在项目里更倾向于每次生成前都 resetRouter 一次，保证路由表绝对干净，再重新添加。

6.3 表单校验不生效、重置不干净的排查路径

表单校验不生效的常见原因按出现频率排序：

1. 表单项没有绑定 prop，规则根本不会关联到该字段。
2. rules 对象里的字段名和 form 的属性名不一致，多一个字母都不行。
3. 规则里的 trigger 写的和用户交互时机不匹配，比如用输入框但 trigger 写成 change，输入时就不会触发。
4. 表单字段是嵌套对象，比如 form.user.name，此时 el-form-item 的 prop 也要写成 "user.name"，漏点就会失效。

校验不通过还能提交的问题，通常是没有在 validate reject 时做 return，或者把 validate 写成了异步但没有 await。可以在 handleSubmit 里先打印 validate 结果来确认原因，不要直接跳到发请求的代码里排查。

重置不干净的问题，多数是混淆了 resetFields 和 clearValidate 的边界。虽然都是清理表单状态，但一个会把字段值恢复成初始值，一个只清提示。如果登录用户信息变化导致表单初始值需要动态变化，resetFields 可能根本不合用，这时最好手动重置字段再 clearValidate。

6.4 一页多表单和动态表单的 $ref 踩坑

当一个页面存在多个表单时，如果写多个 ref 名称，建议每个表单独立命名，比如 formRefA、formRefB，然后分别调用验证。但如果表单是在 v-for 里动态渲染的，ref 绑定会出现一个最容易踩的坑：同名 ref 在 v-for 中会变成数组，直接调用 formRef.value.validate() 会报错。

处理方式有两种。一种是给每个表单组件使用独立子组件，每个子组件内部维护自己的 formRef，这样父组件只需通过子组件实例调用它的提交方法，复杂度会被拆解。另一种是使用函数类型的 ref，动态收集实例：

<el-form v-for="item in formList" :key="item.id" :ref="el => setFormRef(el, item.id)" :model="item.form" :rules="rules" > </el-form>

const formRefMap = new Map() function setFormRef(el, id) { if (el) { formRefMap.set(id, el) } else { formRefMap.delete(id) } }

6.5 问题现象速查表

我做了这么多轮权限和表单功能，最大的体会不是某个 API 不会写，而是这些细节的组合时序。动态路由、常量路由、路由重置、$ref、表单验证流程，看起来是五个独立的技术点，但项目里它们永远绑在一起。建议你先把最小 demo 跑通，再迁移到大项目，能省掉一半的调试时间。最后再多说一句：路由重置一定要放在登出和重新登录之间的回调函数里最先执行，表单校验一定要在发请求之前挡住，这两个顺序错了，后续就是连环出 bug。