若依单独开发页面时路由配置不生效

Question

在使用若依（RuoYi）框架进行单独页面开发时，常出现路由配置不生效的问题。典型表现为：已按规范在 `router/index.js` 中添加新路由，但访问路径时页面空白或跳转404。此问题多因未将新路由正确注入到异步路由（asyncRoutes）中，或菜单未在后台系统注册并分配权限所致。此外，若前端路由模式为 history 模式而服务端未做路径重定向配置，也会导致刷新页面后路由失效。

Answer 1

1. 问题背景与常见现象

在使用若依（RuoYi）框架进行单独页面开发时，开发者常遇到路由配置不生效的问题。典型表现为：已按规范在 router/index.js 中添加新路由，但访问路径时页面空白或跳转404。

• 前端控制台无明显报错信息
• 页面渲染区域为空白内容
• F5刷新后出现404错误（尤其在history模式下）
• 菜单栏未显示新增页面入口

这些问题虽然表象相似，但背后成因多样，涉及前端路由机制、权限系统集成及服务端配置等多个层面。

2. 路由加载机制解析

若依框架采用基于 Vue Router 的异步路由加载机制，核心流程如下：

1. 系统启动时加载基础路由（constantRoutes），包含登录、404等公共页面
2. 用户登录后，通过接口获取其权限菜单数据
3. 将菜单数据动态转换为路由对象，并注入到 asyncRoutes 中
4. 调用 router.addRoute() 方法注册新路由

// 示例：asyncRoutes 配置片段
const asyncRoutes = [
  {
    path: '/demo',
    component: Layout,
    children: [{
      path: 'index',
      name: 'DemoPage',
      component: () => import('@/views/demo/index'),
      meta: { title: '示例页面', icon: 'example' }
    }]
  }
]

3. 常见原因分类与排查路径

类别	具体原因	检测方式
前端配置	未正确导入组件或路径拼写错误	检查控制台是否报模块找不到错误
权限控制	菜单未在后台注册或角色未授权	查看“系统管理-菜单管理”中是否存在对应条目
路由注入	新路由未加入 asyncRoutes 数组	调试 permission.js 中的 generateRoutes 方法
服务端配置	history 模式下 Nginx 未设置 fallback	直接访问 URL 刷新是否返回 index.html

4. 解决方案深度剖析

4.1 确保路由正确注入 asyncRoutes

许多开发者误以为在 router/index.js 添加即可生效，实则需确保该路由被纳入权限路由体系。

// 正确做法：在 src/router/index.js 中定义并导出
export const asyncRoutes = [
  {
    path: '/custom-page',
    name: 'CustomPage',
    component: () => import('@/views/custom/index'),
    meta: { perms: ['system:custom:view'], title: '自定义页' }
  }
]
  

4.2 后台菜单注册与权限分配

若依采用前后端联动的权限模型，前端路由必须与后台菜单匹配。操作步骤如下：

1. 进入【系统管理】→【菜单管理】
2. 点击“新增”，填写路由名称、请求路径（如 /custom-page/index）
3. 设置组件路径（如 demo/index）
4. 关联至指定角色
5. 清空浏览器缓存并重新登录

5. history 模式下的服务端适配

当项目使用 history 路由模式时，URL 更加美观，但需要服务端支持路径回退至 index.html。

graph TD A[用户访问 /custom-page] --> B{Nginx 是否配置 rewrite?} B -- 是 --> C[返回 index.html] B -- 否 --> D[返回 404] C --> E[Vue Router 解析路由] E --> F[渲染目标组件]

Nginx 配置示例：

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