企业官网建设流程全解析

接手过不少若依（RuoYi）二次开发的需求，也带过不少刚接触这个框架的同事。几乎每个刚上手的人都会卡在同一个问题上：在列表页点一下“详情”按钮，怎么跳到另一个页面，还顺手把当前行的 ID 传过去？有的同事照着普通 Vue 项目的写法，this.$router.push一套，结果目标组件路径报错、菜单 404、刷新丢参数，各种问题接踵而来。今天我就把若依框架里路由跳转和携带参数这件事，从头到尾掰开了讲清楚。

这篇教程以若依前后端分离版（Vue 2 + Vue Router 3）为例，后面也会单独说 Vue 3 + TypeScript 版本的区别。如果你是刚拉下来若依代码、正在做二次开发的，或者被路由跳转相关问题折磨过，这篇文章应该能直接帮你解决问题。

1. 先搞清楚若依的路由体系：为什么它和普通 Vue 项目不一样

很多人在若依里做路由跳转翻车，根源不是不会写$router.push，而是没搞懂若依这套动态路由机制。普通 Vue 项目的路由是前端写死的，若依不一样，它的菜单和路由表是从后端动态拉取的，登录用户的角色不同，看到的菜单不同，实际注册到前端路由表里的路由也不同。

1.1 动态路由从哪里来：菜单表到前端路由的完整链路

若依前端启动时，路由分为两部分。一部分是constantRoutes，写在src/router/index.js里，比如登录页/login、首页/index、404 页面等，这部分不依赖权限，所有人都会加载。另一部分是动态路由，它走的是这样一条链路：

1. 用户登录成功，前端拿到 token
2. 前端调用后端接口getRouters，也就是我们常说的“获取路由信息”
3. 后端根据当前登录用户的角色，去数据库的sys_menu表里查出该角色有权限访问的菜单
4. 后端把菜单树转成前端路由格式的 JSON 返回
5. 前端拿到 JSON 后，通过formatRoutes方法把字符串形式的组件路径转换为真正的组件加载函数，再调用router.addRoutes（Vue Router 3）或router.addRoute（Vue Router 4）动态注册到路由表里
6. 侧边栏菜单和实际可访问的路由，这个时候才真正生效

所以，你在若依里尝试跳转到一个路由地址，但发现 404，第一个要想到的原因就是：当前这个路由地址不在后端返回的动态路由表里，也不在constantRoutes里。这就是若依和普通 Vue 项目最大的区别——路由表不是静止的，是登录后才能确定的。

1.2 菜单表里那些字段到底控制了什么

若依的菜单管理页面（系统管理 -> 菜单管理）里，有几个字段直接决定路由行为，新手经常在这里踩坑，我列个表说明：

这里面最关键的是“路由地址”和“组件路径”。路由地址决定你$router.push时填什么 path，组件路径决定这个 path 会被渲染成哪个 .vue 文件。这两个字段拼错了，跳转就大概率白屏或 404。

1.3 跳转时目标路由必须“真实存在”

理解了动态路由机制以后，你就明白一个核心原则：在若依里做任何路由跳转，目标路由必须已经注册到路由表中。这个目标路由可以是后端菜单配置出来的动态路由，也可以是你手动写在constantRoutes里的静态路由。

我见过很多同事在自定义页面之间跳转时卡住，就是因为目标详情页根本没有配置菜单，也没有写入任何路由表，前端当然匹配不到。后面第 4 节我会专门讲这个问题的排查思路。

2. 五种最常用的带参跳转写法与适用场景

基础机制搞清楚了，下面进入正题：若依里路由跳转到底怎么写，参数怎么带。我按实际开发中的使用频率，把常用写法全部过一遍，每种都会说清楚适用场景和坑点。

2.1 query 方式：URL 可见，刷新不丢，最推荐

query 方式是最推荐、最省心的传参方式，实际开发中我大概有八成场景都在用它。写法如下：

// 跳转方：从列表页跳转到详情页 this.$router.push({ path: '/system/user/detail', query: { id: row.userId, name: row.userName } })

跳转之后的 URL 会变成类似/system/user/detail?id=1&name=admin的格式，参数直接暴露在地址栏里，刷新页面参数也不会丢。

接收方在组件里这样取：

// 接收方：详情页 const id = this.$route.query.id const name = this.$route.query.name

query 方式的好处非常明显：刷新不掉参、URL 可以直接复制给别人访问、后端也方便记录访问日志。它的“缺点”只是参数在地址栏可见，不适合传敏感信息，但绝大多数业务场景根本不需要担心这一点。我在若依项目里做列表跳详情、列表跳编辑、通知公告跳转详情等场景，统一用 query。

在若依自带的代码里，这种写法也很常见。比如从用户管理点“分配角色”，跳转到分配页面时，就会带上userId作为 query 参数。你可以打开若依的system/user/index.vue找到相关代码做参考。

2.2 params 方式：URL 不可见，但刷新即失，需谨慎

params 方式的特点是参数不会出现在 URL 里，看起来“更干净”，但代价是刷新页面后参数就没了。

// 跳转方 this.$router.push({ name: 'UserDetail', params: { id: row.userId } })

接收方：

const id = this.$route.params.id

这里有两个关键注意点，很多人在这里摔过：

第一，用 params 方式跳转，push 的对象里必须写name，不能写path。如果你写成{ path: '/system/user/detail', params: { id: 1 } }，params 会被 Vue Router 静默忽略，目标页面的this.$route.params.id就是 undefined。这是 Vue Router 的老规则，文档里写了但很多人没注意。

第二，刷新后 params 会丢失。原因是刷新页面相当于重新加载当前 URL，而 params 参数不在 URL 里，路由重新解析时自然就没有了。如果你的详情页刷新后需要拿到 id 去调接口，用 params 就会直接报错或者拿到一堆空数据。

我的建议是：params 只用来传递“这次会话内部临时用一下、刷新后重新获取”的数据，比如某个查询条件、某个标记位。核心业务参数（比如主键 ID）一律用 query 或动态路由参数。

2.3 动态路由参数：/detail/:id 的语义化写法

还有一种方式是动态路由参数，也就是在路由配置的 path 里写:id这种占位符。如果你的目标路由是自己写在constantRoutes里的，可以这样配置：

// src/router/index.js { path: '/system/user/detail/:id', component: () => import('@/views/system/user/detail.vue'), meta: { title: '用户详情' } }

跳转时：

// 方式一：字符串拼接 this.$router.push(`/system/user/detail/${row.userId}`) // 方式二：对象写法 this.$router.push({ path: `/system/user/detail/${row.userId}` })

接收：

const id = this.$route.params.id

这种方式 URL 上是/system/user/detail/1这种格式，语义化最好，也方便用户记忆和收藏。但放到若依场景里有一个限制：如果你的详情页路由是后端菜单配置出来的，那么“路由地址”字段可以填detail/:id这种形式，我验证过是可以用的，但配置起来相对少一些，而且很多初学者会把:id这个占位符和 query 参数搞混。

我的个人经验是：详情页这种需要长期访问、可能要收藏分享的页面，如果是我自己的项目，优先用/detail/:id这种写法；但如果我在若依这种半成品框架上做开发，为了跟现有菜单体系保持一致、减少沟通成本，我还是更倾向 query 方式。

2.4 新窗口打开并传参：$router.resolve 的正确姿势

有时候我们希望在新标签页打开详情页，这个需求在若依里也经常出现。新手最容易犯的错误是直接写window.open('/system/user/detail?id=1')，结果打开一个白屏页面。

原因很简单：若依是单页应用（SPA），直接通过window.open传入一个内部路由路径，浏览器会重新加载这个地址，如果能加载那也是一个页面白壳子，因为动态路由还没注册，而且服务器如果没有配置 history 回退，直接访问内部路径会返回 404。

正确的写法是先通过$router.resolve解析出完整的可访问地址，再交给window.open：

// 跳转方 const route = this.$router.resolve({ path: '/system/user/detail', query: { id: row.userId } }) window.open(route.href, '_blank')

这样window.open拿到的是一个带完整路径的可访问 URL，新标签页打开后就能正常渲染详情页。注意新窗口打开页面时，页面会重新走一遍登录 -> 加载动态路由的流程，所以目标详情页如果是通过动态菜单注册出来的，需要保证当前用户有权限访问这个路由，否则新标签页可能回跳到登录页。

另外还有一个细节：window.open如果是在一层嵌套很深的异步回调里调用，可能会被浏览器拦截弹窗。建议把它放在用户点击事件的同步调用链里，或者先调用window.open拿到句柄，再跳转赋值 URL。

2.5 若依菜单管理里的“路由参数”：静态参数的隐藏用法

很多若依使用者不知道，菜单管理里面有一个“路由参数”输入框。它的作用是：给这个菜单对应的页面预置一批静态参数，跳转进入后可以直接从$route.query里拿出来。

举个例子，你在菜单管理里给某个菜单配置了路由参数：

{ "id": 1, "type": "system" }

保存后，前端渲染侧边栏并点击这个菜单进入页面，在页面里就可以直接读到：

const id = this.$route.query.id // 输出 1 const type = this.$route.query.type // 输出 system

这个字段适合给“多个菜单共用一个组件、但组件需要根据参数显示不同数据”的场景。比如你有一个报表页面，配置了三个菜单项，分别用路由参数{ reportId: 1 }、{ reportId: 2 }、{ reportId: 3 }指向同一个组件路径，组件内部根据reportId加载不同报表，这就省去了写很多重复页面的麻烦。

3. 接收参数的正确姿势：不只是 this.$route.xxx 那么简单

参数带过去了，接收方怎么写也有讲究。简单场景直接this.$route.query.id就完了，但真实项目中会遇到页面缓存、二次进入不刷新、参数类型不对等问题，这一节讲清楚。

3.1 三种接收参数的核心写法

先理清两个最基础的概念：this.$router和this.$route。

• this.$router是路由实例，负责跳转，主要方法有push、replace、resolve等
• this.$route是当前路由信息，负责读取，包含path、query、params、meta、fullPath等字段

接收参数对应的就是$route：

// 读取 query 参数 const id = this.$route.query.id // 读取 params 参数 const id = this.$route.params.id // 读取动态路由参数（也是 params） const id = this.$route.params.id // 读取完整路径 const fullPath = this.$route.fullPath

这里有个小坑需要提醒：URL 里的 query 参数全部是字符串。如果跳转时传的是数字，this.$route.query.id取出来后也是字符串。比如列表页query: { id: 1 }，详情页取到的是"1"而不是数字1。如果你拿着这个 id 去跟接口返回的数字做===严格比较，或者参与一些数字运算前没转换，就可能出现莫名其妙的 bug。建议取参数后第一时间处理：

const id = Number(this.$route.query.id) || '' // 或者 const id = String(this.$route.query.id ?? '')

3.2 从列表跳详情页并基于参数加载数据的完整范例

我以若依最典型的“用户列表 -> 用户详情”场景，给出一套完整可复用的模板。

列表页（src/views/system/user/index.vue），为表格的操作列加一个“详情”按钮：

<el-table-column label="操作" align="center"> <template #default="scope"> <el-button type="primary" link @click="handleDetail(scope.row)" >详情</el-button> </template> </el-table-column>

按钮的点击方法：

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

详情页（src/views/system/user/detail.vue），在created里读取参数并请求接口：

export default { name: 'UserDetail', data() { return { id: null, loading: false, detailData: {} } }, created() { this.id = this.$route.query.id if (this.id) { this.getDetail() } }, methods: { getDetail() { this.loading = true getDetailApi(this.id) .then(res => { this.detailData = res.data }) .finally(() => { this.loading = false }) } } }

这里我习惯写if (this.id)做一层判断，防止有人直接手敲 URL 访问详情页但没有带 id，导致接口请求一个空值而报错。

3.3 二次进入同一页面组件不刷新：keep-alive 缓存引发的经典问题

这是若依路由跳转里最经典、问得最多的一个问题，也是热搜词里“router vue3 路由跳转组件内容渲染不显示”背后常见的真实原因。

若依的AppMain主区域组件使用了 keep-alive 缓存机制，被缓存的页面组件在二次进入时不会重新执行created和mounted生命周期，而是从缓存直接恢复。这就导致一个问题：你从列表页第一次点详情（id=1），详情页正常显示。返回列表，再点另一行（id=2），预计详情页显示新数据，但页面还是 id=1 的旧内容，完全没有刷新。

排查这个问题时，你可能会在created里打印this.$route.query，发现确实已经变成 id=2 了，但页面数据没变。这就是缓存和生命周期的问题。

解决方案有几个，按推荐程度排序：

方案一：监听$route变化，在变化时重新加载数据（推荐）

watch: { '$route': { handler(to) { this.id = to.query.id this.getDetail() }, immediate: true } }

immediate: true表示组件创建时立即执行一次，替代了created里的初始化逻辑。这种做法兼容两种场景：首次进入和后续带新参数进入。我建议直接把这种写法固化到自己的页面模板里，省得每次都要判断有没有缓存问题。

方案二：在若依路由配置里排除详情页的缓存

详情页的组件里设置name，并在路由 meta 或菜单配置层面控制它不进 keep-alive。RuoYi 的AppMain.vue里有一个cachedViews数组，它来源于路由的meta.keepAlive。如果你在菜单管理里把详情页的“是否缓存”关闭，那每次进入都会重建组件。但这个方案我一般不建议，因为重建组件会牺牲一些性能，而且导航回列表时详情页状态会丢。

方案三：在详情页销毁前清除对某个参数的依赖

如果你只是偶尔遇到缓存问题，也可以用beforeRouteLeave钩子，在离开前把详情页数据清空，下次再进入时至少是空白状态而不是旧数据。但这样做体验一般，不如方案一直接。

3.4 封装一个统一跳转方法，减少重复代码

如果你在项目里有很多页面之间要互相跳转，每次都要写this.$router.push({ path: ..., query: ... })，重复代码一多，后面要统一改逻辑就会很痛苦。

我习惯在src/utils下封装一个统一跳转方法，比如src/utils/router-helper.js：

/** * 统一页面跳转方法 * @param {Object} vm 组件实例（this） * @param {Object} target 目标路由对象 { path, query, params } * @param {String} targetType _self 当前窗口 | _blank 新窗口 */ export function navigateTo(vm, target, targetType = '_self') { if (!target.path && !target.name) { console.error('[router-helper] 缺少路径参数') return } if (targetType === '_blank') { const route = vm.$router.resolve(target) window.open(route.href, '_blank') } else { vm.$router.push(target) } }

使用的时候：

import { navigateTo } from '@/utils/router-helper' // 当前窗口打开 navigateTo(this, { path: '/system/user/detail', query: { id: row.userId } }) // 新窗口打开 navigateTo(this, { path: '/system/user/detail', query: { id: row.userId } }, '_blank')

这样统一收口的好处是：以后想在跳转时加全局埋点、要做跳转白名单校验、要统一处理 noPermission 等逻辑，只要改一个文件就行。

4. 高频报错与坑位排查：路由跳转翻车实录

这一节总结我在若依项目里实际遇到过的路由跳转问题，把完整的排查思路写出来，而不是直接给答案。掌握排查链路，比记住单一答案有用得多。

4.1 跳转后组件内容不渲染，页面空白

这个现象在热搜词里出现过，具体表现是：点击跳转后 URL 变了，但主区域一片空白，或者控制台报错。

我的排查链路是这样的：

第一步，打开浏览器 F12 -> Console，看有没有报错信息。最常见的一种报错是类似于Cannot read property 'xxx' of undefined，这种通常是因为目标组件里created读取this.$route.query.xxx，但跳转时根本没传这个参数，或者参数名不一致。解决方法是检查跳转方和接收方的参数名是否严格一致。

第二步，确认目标路由是否真的存在。在跳转前，先打开侧边栏菜单，看能不能手动点击进入目标页面。如果手动也进不去，大概率是路由配置问题：组件路径不对、文件不存在、路径大小写不匹配。其中大小写问题在 Vue 3 + Vite 环境尤其突出。我在若依 Vue 3 版本中遇到过views/System/User/index.vue和system/user/index路径大小写不一致导致模块加载失败的情况，因为 Vite 对路径解析是大小写敏感的，Linux 构建环境下尤其明显。

第三步，查看 Network 面板。跳转后看是否发出请求加载了目标 chunk 文件，比如你的详情页被打包成了detail.[hash].js。如果 Network 里根本没有加载这个文件，那还是路由匹配问题；如果加载了但页面白屏，那就是组件内部抛了异常。

4.2 params 参数刷新丢失，页面报错

这是一个高频场景，也是 params 方式最主要的问题。排查思路很简单：

• 确认是不是用了 params
• 确认跳转方是不是写了name而不是path
• 确认跳转目标页面载后，是否发生了浏览器刷新

如果确认是刷新后报错，解决方案前面已经说过了：改用 query。如果你的业务场景真的不能把参数暴露在 URL 里，那就用 sessionStorage 缓存一份：

// 跳转方 sessionStorage.setItem('detailId', row.userId) this.$router.push({ path: '/system/user/detail' }) // 接收方 created const id = sessionStorage.getItem('detailId') if (!id) { // 没有参数，可能是直接访问 URL，做兜底 return }

这种方式的好处是参数不暴露在 URL 里，刷新后 sessionStorage 还在，参数不会丢。坏处是如果用户清浏览器缓存或新开标签页直接访问，参数就没有了，需要在代码里做兜底。

4.3 菜单跳转 404，刷新后无法访问

这个问题的典型场景是：用户收藏了详情页 URL，第二天直接输入 URL 打开；或者你在代码里$router.push一个自定义详情页，但目标页面没有配置菜单也没写静态路由。

排查思路是回到 1.1 节的链路：一个路由要被访问到，必须被注册到路由表里。动态菜单没配，静态路由没写，那 vue-router 就不认识这个路径，自然 404。

解决方案是：把这种“非菜单页面”加到constantRoutes里。以若依源码为例，在src/router/index.js中constantRoutes数组的末尾加一层：

{ path: '/system/user/detail', component: Layout, hidden: true, children: [ { path: '', component: () => import('@/views/system/user/detail.vue'), name: 'UserDetail', meta: { title: '用户详情' } } ] }

注意外层套一个Layout，因为若依除了登录页等极少数页面，几乎所有的页面都在Layout壳组件下渲染。hidden: true表示不显示在侧边栏，但路由是真实存在的。这样配置之后，不管是$router.push还是直接访问 URL，都能正常渲染。

4.4 新窗口打开白屏，地址栏却是正常路径

这个问题在 2.4 节已经说过核心原因：SPA 应用直接window.open内部路径不可行，必须用$router.resolve解析。我再补充一个容易忽略的细节：如果你的若依部署在二级目录下，比如通过 nginx 配置了/admin前缀，$router.resolve解析出来的 href 会带上这个前缀，直接window.open也会出问题。这种情况下要确认路由的base配置和服务器配置一致。

4.5 Vue 3 + TypeScript 版本中带参跳转的差异

现在很多人用的是若依的 Vue 3 版本，也就是RuoYi-Vue3。Vue 3 的路由跳转逻辑本质上和 Vue 2 一样，但 API 从选项式写法变成了组合式。

Vue 2 写法：

this.$router.push({ path: '/system/user/detail', query: { id: 1 } }) this.$route.query.id

Vue 3 + Composition API 写法：

import { useRoute, useRouter } from 'vue-router' const route = useRoute() const router = useRouter() // 跳转 router.push({ path: '/system/user/detail', query: { id: 1 } }) // 接收 const id = route.query.id

在 TypeScript 环境下，很多人遇到的报错是route.query.id的类型是LocationQueryValue | LocationQueryValue[]，不是string。直接拿去传给接口会报类型错误。解决方案：

const id = String(route.query.id ?? '') // 或者如果确定是单值 const id = route.query.id as string

另外 Vue Router 4 已经废弃了addRoutes，若依封装的时候用的是addRoute循环添加，这个差异不影响我们业务层面的跳转写法。

5. 写在最后的几个建议

在实际项目中，我个人的习惯是：若依里的页面跳转和传参，能走 query 就走 query，这不仅是为了刷新不丢参数，更是为了方便排查问题——URL 上什么参数一目了然，后端日志里也能看到完整的访问路径，出了问题定位很快。

如果你要从列表跳到详情页，并且详情页需要长期收藏、分享给其他人访问，推荐使用/detail/:id这种动态路由参数，URL 更美观也更语义化。但前提是你愿意在constantRoutes里为这些页面单独维护路由，并且处理好刷新后的路由注册顺序。

另外一个小技巧：跳转前最好先在代码里打一个日志，把this.$route.query或者this.$route.params打印出来看一眼。很多时候页面白屏不是跳转的问题，而是接收方在参数还没到位的情况下就去调了接口，后端返回错误直接把页面渲染搞崩了。先确认参数有没有正确到达，再去查组件内部逻辑，排查效率会高很多。

最后强调一句，无论 Vue 2 还是 Vue 3 版本，若依的路由跳转本质上就是 Vue Router 的标准用法。你把动态路由机制搞懂了，把“目标路由必须存在”和“参数名必须一致”这两个原则记住，后面遇到再花哨的跳转需求也就是几行代码的事。