企业官网建设流程全解析

做若依二次开发，路由跳转是第一道必过的坎。尤其是刚从纯前端项目切过来的朋友，经常会困惑：为什么菜单点得进去，但自己在页面里写this.$router.push却跳不过去？为什么跳过去了，参数却死活拿不到？为什么刷新一下，刚带过去的数据就没了？

这篇文章我会把若依前后端分离版本里的路由跳转和参数传递讲透，包括最常用的三种携带参数方式、列表页跳详情页的完整实操、以及几个典型的踩坑现场。不是单纯贴代码，还会把若依的动态路由机制、菜单表和前端路由是如何串联的讲清楚。理解了这套机制，你后面做菜单权限、按钮权限、详情页传值都会顺畅很多。

先说清楚：这是个超详细教程，我会把每一步该在哪个页面、点哪个按钮、看哪段代码都标出来。你跟着走一遍，基本就能把路由跳转这套逻辑摸熟。文章以若依前后端分离版（RuoYi-Vue）为例，Vue3 版本的差异我也会在对应位置单独说明。

1. 先把若依的路由机制搞清楚

1.1 你的页面路由到底是从哪来的

若依的前端路由和平常自己写 vue-router 有本质区别。你自己写项目，路由都是手写在router/index.js里；但若依不是，它的路由是后端通过菜单动态生成的。

整个流程是这样的：

1. 用户登录成功后，前端调用后端/getRouters接口，拿到当前用户有权限看到的菜单列表。
2. 这个菜单列表就是sys_menu表里组装出来的树形结构。
3. 前端拿到菜单后，在路由守卫中通过addRoute方法，把菜单逐条动态挂载到 vue-router 里。
4. 侧边栏组件再根据这套路由表递归渲染出菜单。

所以你会看到，若依的src/router/index.js里只有一部分固定路由（constantRoutes），比如登录页、404、首页等；剩下的业务页面路由全部是从后端动态加的（走的是store/modules/permission.js里的generateRoutes）。

这也是为什么很多新手第一次给若依加页面时，直接在router/index.js里写了一个路由，然后跳转过去却是空白或者 404。因为你还得去菜单管理里创建一个对应的菜单记录，并且把它分配给角色，前端才会生成真正可用的路由。

1.2 菜单管理里的字段和跳转的对应关系

你打开若依的系统管理 -> 菜单管理，新增一个菜单时，有几个字段是直接影响路由跳转的：

• 菜单类型：分为目录、菜单、按钮。只有“菜单”类型才会生成页面路由，“按钮”类型只是权限标识。
• 路由地址：就是 route 的 path。如果填了user，前端跳转路径就是/user。
• 组件路径：比如填system/user/index，实际对应的组件文件是src/views/system/user/index.vue。这个路径写错了，页面就渲染不出来。
• 路由名称：对应路由的 name，使用params传参时必须要用 name，所以这个字段也别乱填。
• 是否外链：如果路由地址填了一个完整的http链接，并且打开了外链开关，菜单点击后就会在浏览器新标签页打开，不走内部路由。
• 是否缓存：对应路由的keepAlive，决定这个页面在切换页签时会不会被缓存住。这个字段和后面要讲到的“页面数据残留”问题直接相关。

提示：如果你在菜单管理里新增或修改了菜单，前端一定要重新登录一次，或者让用户刷新页面重新拉取路由。因为动态路由是基于当前登录态缓存在内存里的，不重新拉取，菜单和路由不会更新。

1.3 路由守卫里发生了什么

若依的全局路由守卫在src/permission.js里。每次路由跳转，都会经过这个守卫做三步判断：

1. 是否登录？没登录就跳/login。
2. 已登录但没拿到用户信息？就调getInfo拉用户信息。
3. 已登录但没生成动态路由？就调getRouters拉菜单，然后addRoute动态挂载。

这就是为什么你手动在地址栏输入一个 URL，如果这个地址没有对应的菜单路由，会被直接丢到 404 页面。若依的 404 页面是根据path: '/:pathMatch(.*)*'匹配的，任何没注册的路径都会落到这里。

明白了这套机制，我们再回头看页面里的路由跳转，很多问题就都能对上号了。

2. 页面跳转的几种常规写法

2.1 模板里用 router-link 声明式跳转

最简单的方式是在模板里写router-link，适合那种“固定跳转到某个页面”的按钮。比如列表页里加一个“去详情”的文字链接：

<router-link :to="{ path: '/system/user/detail', query: { id: row.userId } }"> 查看详情 </router-link>

router-link最终会被渲染成<a>标签，点击行为等价于调用router.push。它的好处是直观，而且可以配合v-for动态生成。但实际在若依的表格操作列里，大家更喜欢用按钮加@click的方式，因为可以顺便处理权限、loading 等其他逻辑。

2.2 编程式跳转 push、replace、go

业务逻辑中真正高频使用的是编程式跳转。

Vue2 的写法：

this.$router.push('/system/user'); this.$router.push({ path: '/system/user', query: { id: 1 } }); this.$router.replace({ path: '/system/user', query: { id: 1 } }); this.$router.go(-1);

Vue3 + 组合式 API 的写法：

<script setup lang="ts"> import { useRouter } from 'vue-router'; const router = useRouter(); function goDetail() { router.push({ path: '/system/user/detail', query: { id: row.userId } }); } </script>

push和replace的区别在于：push会往历史记录栈里压入一条新记录，用户点浏览器的返回按钮可以回到上一个页面；replace则是把当前记录替换掉，用户返回时会跳过当前页。在若依里，编辑提交成功后通常会这样收尾：

// 编辑完列表回列表页，用 replace 避免用户按返回又回到编辑页 this.$router.replace('/system/user');

go的常用场景是返回上一页，比如详情页右上角的“返回”按钮，直接this.$router.go(-1)。

2.3 新窗口打开和菜单外链

若依里还有一个比较特殊的需求：点击按钮新开浏览器标签页打开详情页。这个不能再用router.push，它只能在同一页面内跳转。我们需要拿路由地址拼成完整的 URL，再调用window.open：

import { defineComponent } from 'vue'; const handleDetail = (row) => { // 通过路由解析出完整跳转地址 const routeData = this.$router.resolve({ path: '/system/user/detail', query: { id: row.userId } }); window.open(routeData.href, '_blank'); };

菜单外链则更简单。若依的侧边栏组件sidebar/index.vue里有一段handleLink逻辑：它会判断菜单项的 path 是不是以http开头，如果是，直接把整个路径交给window.open或window.location.href；如果不是，才走router.push。所以你配置菜单外链时，只要在菜单管理的“路由地址”里填完整 URL，并打开外链开关即可，前端会自动处理。

3. 携带参数：query、params、动态路由到底怎么选

3.1 query 方式：URL 可见，刷新不丢

query方式是把参数拼在 URL 的问号后面。跳转代码：

// 跳转时 this.$router.push({ path: '/system/user/detail', query: { id: row.userId, name: row.userName } });

跳转后，浏览器地址栏会变成/system/user/detail?id=1&name=zhangsan。

目标页面接收：

// Vue2 this.$route.query.id; this.$route.query.name; // Vue3 import { useRoute } from 'vue-router'; const route = useRoute(); route.query.id; route.query.name;

query最大的优势是页面刷新后参数还在，因为参数都体现在 URL 上。这很适合详情页、列表页跳转这类需要“用户刷新后仍保持状态”的场景。

它的缺点也很明显：参数全都暴露在 URL 里。如果你传的是用户的某个状态码还好，如果传的是完整的表单对象、甚至带中文长文本的 JSON 字符串，URL 会变得很丑陋且容易被截断。

3.2 params 方式：URL 不可见，但刷新会丢

params方式是把参数放在路由对象内部，不体现在 URL 上。跳转代码：

this.$router.push({ name: 'SystemUserDetail', params: { id: row.userId, user: row } });

这里有个硬性规定：使用 params 时，必须用 name 指定目标路由，不能用 path。因为 params 匹配是基于路由 name 的，你写path的时候，router 根本不知道你要匹配哪个路由对象，params 会被忽略。

目标页面接收：

this.$route.params.id; this.$route.params.user;

params的优势是参数不会暴露在 URL 里，也避免了超长 URL 的问题。但它的致命伤是：页面一刷新，params 就没了。因为刷新时路由对象是重新解析的，而 params 只存在于内存中的路由记录里，刷新之后浏览器只会根据 URL 重新找路由，URL 里又没有参数，自然就丢了。

所以我的建议是：如果参数是关键的标识符（比如主键 ID），优先用 query；如果传的是对象，考虑序列化后用 query，或者干脆只传 ID，到目标页再调一次接口查详情。

3.3 动态路由参数：最优雅的详情页方案

动态路由参数是指在路由表里就把参数位置定义好。例如在views对应的路由中配置：

{ path: 'detail/:id', name: 'UserDetail', component: () => import('@/views/system/user/detail/index.vue') }

那么跳转时可以直接写：

this.$router.push(`/system/user/detail/${row.userId}`);

或者：

this.$router.push({ path: `/system/user/detail/${row.userId}` });

目标页面接收：

this.$route.params.id;

这种方式的 URL 是/system/user/detail/1，对用户更友好，而且刷新不丢参数。如果你需要多个参数，可以定义多个路径段：detail/:id/:type。

但要注意，若依的菜单是后端动态生成的，动态路由参数这段 path 不是想改就能随便改的。你在菜单管理里配置“路由地址”时，直接填detail/:id是不行的，因为菜单管理生成的 path 会被拼到父级路由下，再带上冒号，路由匹配很容易出问题。真实项目中，我见过不少人为了支持这种路径，选择不在菜单里配这个详情页，而是直接在router/index.js的constantRoutes里手动注册，或者用隐藏菜单（路由地址依然配置，但菜单显示为否）然后配合权限控制来使用。

更稳妥的做法：在若依里把动态详情页做成“不在菜单树里出现”的二级路由，例如在父路由的children中手动加一条{ path: 'detail/:id', component: ... }，菜单管理里不配这条。这样既能享受动态路由参数的优势，又不会破坏若依的菜单-路由生成逻辑。

3.4 三种方式对比

4. 实操：列表页跳详情页，参数完整传递

4.1 场景设定

以若依自带的用户管理为例：在“用户管理”列表页，点“详情”按钮，跳转到user/detail页面，并在详情页显示当前用户 ID、用户名、手机号等信息。

4.2 先确认目标页面已经能被路由识别

如果你要跳转的目标页面在菜单管理里已经有了菜单记录，并且目录层级也对得上，那直接用path跳过去就行。比如，系统管理 -> 用户管理对应的菜单 path 是/system/user，组件路径是system/user/index，那么它的详情页我建议放在同级目录下，组件路径写成system/user/detail/index.vue。

接着在菜单管理里新增一条菜单记录：

• 上级菜单：选“用户管理”
• 菜单类型：菜单
• 路由地址：detail
• 组件路径：system/user/detail/index
• 路由名称：UserDetail
• 是否缓存：根据你希望详情页刷新后是否保留状态来定

保存后重新登录，或者在浏览器控制台执行window.location.reload()让前端重新拉取路由。如果此时你手动访问/system/user/detail不报 404，说明路由已经挂载成功。

提示：这里的“路由地址”填detail，最终完整路径就是/system/user/detail。若依会自动把父子菜单的 path 拼接起来，不需要你在子菜单里写全路径。

4.3 列表页按钮跳转

找到src/views/system/user/index.vue，在操作列里加一个“详情”按钮，并绑定点击事件：

<el-button v-hasPermi="['system:user:query']" type="primary" link @click="handleDetail(scope.row)" >详情</el-button>

事件方法：

// Vue2 写法 handleDetail(row) { this.$router.push({ path: '/system/user/detail', query: { id: row.userId } }); } // Vue3 写法 const router = useRouter(); const handleDetail = (row) => { router.push({ path: '/system/user/detail', query: { id: row.userId } }); };

点击按钮，浏览器地址栏会变成/system/user/detail?id=xxx，说明跳转成功，query 参数已经带过去了。

4.4 详情页接收参数并回显

在src/views/system/user/detail/index.vue的created钩子里读取参数：

// Vue2 created() { const id = this.$route.query.id; this.getDetail(id); }, methods: { getDetail(id) { // 调用后端的 detail 接口 getUserById(id).then(res => { this.form = res.data; }); } } // Vue3 import { useRoute } from 'vue-router'; const route = useRoute(); onMounted(() => { const id = route.query.id; getDetail(id); });

这段代码的逻辑是：跳转时只传了一个 ID，目标页拿到 ID 后，再调一次后端接口把详情数据拉回来。这也是若依项目里最主流的做法，比直接传整个对象更安全、更可靠。因为直接把对象塞给 params，一刷新就没了，而且如果对象里有敏感字段，暴露在内存在某些场景下也不合适。

4.5 编辑页带整行数据跳转的取舍

有些朋友图省事，点“编辑”的时候想把整行数据用params传过去：

this.$router.push({ name: 'UserEdit', params: { row: row } });

这个写法在跳转瞬间是能拿到数据的，页面也能正常渲染。但问题来了：用户停留在编辑页，手一抖按了 F5，参数全部丢失，页面变成空白或报错。而且你通过菜单页签点回来的时候，如果中间有别的操作导致路由被重新创建，同样会遇到参数丢失。

所以我的建议：

• 编辑/查看详情，永远只传主键 ID，到目标页再查一次数据。
• 如果确实需要传临时对象，请使用sessionStorage或pinia/vuex暂存，目标页在created里读取后立即清掉，避免内存堆积。

例如用 sessionStorage 暂存：

// 跳转前 sessionStorage.setItem('cache_form_data', JSON.stringify(row)); this.$router.push('/system/user/edit'); // 目标页读取 const cached = sessionStorage.getItem('cache_form_data'); if (cached) { this.form = JSON.parse(cached); sessionStorage.removeItem('cache_form_data'); }

这种方案既保留了传对象的便利性，又扛得住刷新。缺点是数据存在浏览器会话里，关闭标签页会丢，但这个场景本来就符合“临时编辑状态”的预期。

5. 若依场景下的进阶问题与避坑

5.1 多页签 TagsView 跳转与参数恢复

若依顶部有类似 IDE 的页签栏（TagsView）。你从一个页面跳到另一个页面，前一个页面会被缓存起来（前提是菜单开启了“是否缓存”）。这带来一个典型问题：从列表 A 跳到详情 B，再退回 A，A 里之前滚动的位置、搜索条件都还在，这是缓存带来的便利；但从详情 B 返回时如果用的是go(-1)，A 页面的created不会重新触发，如果 A 有需要刷新的数据，就会展示旧数据。

如果你希望 A 页面每次从详情返回时都重新拉取数据，可以在 A 页面的activated钩子里做刷新，而不是依赖created：

activated() { // 从其他缓存页面返回时，重新拉取列表数据 this.getList(); }

同时，若依在菜单管理里对“是否缓存”的开关实际上控制的是keep-alive的include列表。只有组件 name 和路由 name 对得上，缓存才生效。如果你发现某个页面怎么配缓存都不生效，先检查组件里export default { name: 'Xxx' }是否正确，并且和菜单管理里的路由名称保持一致。

5.2 路由跳转后组件内容渲染不显示

这是很多朋友遇到的经典问题：路由跳转过去了，URL 没毛病，菜单也高亮了，但内容区域空白。排查顺序是这样：

1. 先看控制台有没有报错。最常见的报错是Cannot find module或Failed to resolve component，十有八九是菜单管理里的“组件路径”填错了，或者文件压根没创建。比如组件路径填system/user/detail/index，那你必须有src/views/system/user/detail/index.vue这个文件。
2. 如果控制台没有报错，页面是空白但 F12 里能看到组件已经渲染了，可能是组件内部的布局高度为 0，或者在created里某个接口报错导致后续渲染中断。
3. 还有一种情况：目标组件确实渲染了，但被keep-alive缓存住了，展示的是旧内容。这时按 F12 看看代码里router-view外层是否被<keep-alive>包裹，若依的主布局里确实有这个包裹，所以请检查菜单的缓存开关。
4. 再有一种隐蔽的情况，是路由地址大小写问题。若依里定义路径用的是小写，但你在代码里跳转时用了大写，或者路由 name 大小写不一致。vue-router 匹配时，路径大小写不敏感，但name 的匹配是严格区分大小写的。如果 name 对不上，跳转会报No match错误。

5.3 Vue3 版本和 TypeScript 下的注意点

若依的 Vue3 版本（RuoYi-Vue3）默认是 TypeScript 项目。很多从 Vue2 迁移过来的同学会习惯性写this.$router.push(...)，结果报Property '$router' does not exist on type ...。原因很简单：组合式 API 里没有this指向组件实例的上下文，必须显式引入：

import { useRouter, useRoute } from 'vue-router'; const router = useRouter(); const route = useRoute(); router.push({ path: '/system/user/detail', query: { id: row.userId } });

另外，route.query返回的类型是LocationQuery，所有参数值都会被推断为string | null | string[]。如果你的 TS 项目开启了严格模式，直接把route.query.id当作number用会报类型错误，需要处理一下：

const id = Number(route.query.id as string) || 0;

同理，动态路由参数route.params.id也会被推断为string | string[]，也需要做类型转换。

5.4 动态脚本与 XSS 隐患的提醒

若依的表单设计器支持动态脚本配置，这属于它比较高级的能力。但如果你的页面里把路由跳转的目标地址设计成“用户可配置”的，例如某个菜单能配置跳转到任意 URL，请务必校验这个 URL 的协议和域名白名单，防止被恶意脚本构造javascript:协议地址。若依的安全框架本身对存储型 XSS 有过滤，但它主要过滤的是表单输入里常见的<script>标签，对 URL 跳转这类场景，前端所有页面代码里，所有跳转目标尽量通过router来管理，不要直接location.href = 用户输入。

6. 常见问题排查速查表

6.1 问题现象与解决方案对照

6.2 排查思路总结

遇到路由跳转问题，我建议按这个顺序走：

先看地址栏。如果 URL 和你预期不一样（少了参数、多了乱码），说明是参数传递写法不对。再看控制台。有没有红色报错，报错信息往往已经告诉你是路由没匹配上、组件没找到还是 TS 类型错误。再看 Network。如果你的目标页需要调接口，但接口没发出来，说明参数解析那步就已经挂了。最后再怀疑缓存。把菜单管理的“是否缓存”关掉试试，排除 keep-alive 的干扰。

6.3 几个值得长期坚持的编码习惯

我在若依项目里写了很久路由跳转，踩了无数坑之后，总结出几个比较重要的习惯。

第一个，跳转标准统一。一个项目里，列表到详情只传 ID，编辑页只传 ID，暂存数据一律走 sessionStorage。不要这个页面用 params，那个页面用 query，后面维护的人会疯掉。

第二个，目标页做好参数兜底。任何路由参数都有可能为空或异常，读取之后先判断，比如：

const id = this.$route.query.id; if (!id) { this.$msg.error('缺少必要参数，请从列表页进入'); return; }

这个习惯能帮你减少大量“用户直接在地址栏乱填 URL 导致白屏”的工单。

第三个，路由跳转后记得处理 loading。若依列表页自带 loading，但你的详情页如果是手动router.push跳转的，建议在按钮或页面里加一个 loading 状态，防止接口慢的时候用户以为页面卡死了。

第四个，也是最重要的一条，除非特殊需求，否则不要绕过若依的菜单权限体系去创建路由。直接在constantRoutes里写死的路由，所有登录用户都能访问，绕过了按钮权限和后端菜单过滤，这在项目安全评审时通常过不了。

我个人在实际操作中的体会是：若依的路由跳转并不难，难的是理解“菜单-权限-路由”这三者之间的联动关系。只要把菜单管理和前端动态路由这两层关系摸透了，后面写详情页、编辑页、外链跳转，都只是套模板的问题。而且你会发现，趁着项目规模还不大的时候把跳转规范和参数约定定下来，后面几百个页面铺开时，维护成本会低很多。