开发必读文档

基础响应格式

默认返回以下格式，如需修改请到 src/types/common/response.ts 文件修改

/** 基础响应 */
interface BaseResponse<T = unknown> {
  code: number; // 状态码
  msg: string; // 消息
  data: T; // 数据
}

网络请求默认返回 data 中的数据而不是整个响应体：

try {
  const { token, refreshToken } = await fetchLogin({
    userName: username,
    password,
  });
} catch (error) {
  if (error instanceof HttpError) {
    // 可以根据状态码进行不同的处理
    // console.log(error.code)
  }
}

菜单接口对接

在 .env 文件中切换权限模式：

# 权限模式【 frontend 前端模式 / backend 后端模式 】
VITE_ACCESS_MODE = backend

切换到后端模式后，打开浏览器控制台的 Network 面板，可以看到菜单接口返回的数据格式。

后端菜单接口返回格式：

{
  code: 200,
  msg: "success",
  data: [
    {
      name: 'Dashboard',
      path: '/dashboard',
      component: "/index/index",
      meta: {
        title: 'menus.dashboard.title',
        icon: 'ri:pie-chart-line'
      },
      children: [...]
    }
  ]
}

可通过控制台查看数据格式：

前端模式（asyncRoutes.ts）：

前端模式下，roles 字段用于权限过滤，通过用户信息接口返回的 roles 与菜单配置中的 roles 对比实现菜单过滤：

{
  name: 'Dashboard',
  path: '/dashboard',
  component: "/index/index",
  meta: {
    title: 'menus.dashboard.title',
    icon: 'ri:pie-chart-line',
    roles: ['R_SUPER', 'R_ADMIN'] // 只有这些角色可以访问
  }
}

注意： 后端模式下，菜单由后端根据用户角色返回，不需要配置 roles 字段。

表格分页接口对接

配置文件： src/utils/table/tableConfig.ts

系统会按优先级顺序自动查找后端返回的字段，支持多种常见字段名。如果后端使用的字段名不在配置列表中，可以在配置中添加自定义字段名。

export const tableConfig = {
  // 响应数据字段映射配置，系统会从接口返回数据中按顺序查找这些字段
  // 列表数据
  recordFields: ["list", "data", "records", "items", "result", "rows"],
  // 总条数
  totalFields: ["total", "count"],
  // 当前页码
  currentFields: ["current", "page", "pageNum"],
  // 每页大小
  sizeFields: ["size", "pageSize", "limit"],

  // 请求参数映射配置，前端发送请求时使用的分页参数名
  // useTable 组合式函数传递分页参数的时候用 current 跟 size
  paginationKey: {
    current: "current", // 当前页码
    size: "size", // 每页大小
  },
};

扩展示例： 如果后端使用其他字段名，可以在对应数组中添加：

recordFields: ["list", "data", "records", "items", "yourCustomField"];

页面切换一片空白

原因： 开启了路由切换动画，而 Vue 的 <Transition> 组件要求页面组件必须有单个根元素。如果组件存在多个根元素（包括注释节点），会导致动画失效并出现空白页面。

解决方法： 将所有内容包裹在单个容器元素中。

❌ 错误示例

<template>
  <!-- 多个根元素 -->
  <div>内容1</div>
  <span>内容2</span>
</template>

<template>
  <!-- 注释也会被视为根节点 -->
  <div>
    <div>内容1</div>
    <span>内容2</span>
  </div>
</template>

✅ 正确示例

<template>
  <div>
    <!-- 注释放在根元素内部 -->
    <div>内容1</div>
    <span>内容2</span>
  </div>
</template>

点击菜单页面自动刷新

原因： Vite 在开发模式下会自动进行依赖预构建优化。当首次使用某些组件库的子模块时（如 Element Plus 的样式文件），Vite 会检测到新的依赖并重新优化，导致页面刷新。

识别方法： 打开编辑器启动台，如果看到类似提示说明遇到了这个问题：

[vite] new dependencies optimized: element-plus/es/components/tooltip/style/index

解决方法： 在 vite.config.ts 中将控制台提示的依赖添加到 optimizeDeps.include 配置中：

export default defineConfig({
  optimizeDeps: {
    include: [
      "element-plus/es/components/tooltip/style/index",
      "element-plus/es/components/message/style/index",
      // 根据控制台提示添加其他依赖
    ],
  },
});

添加配置后需要重启开发服务器。此问题只在开发环境出现，生产环境不受影响。

路由配置错误

如果路由配置存在问题（如字段缺失、格式错误、组件路径不存在等），系统会在浏览器控制台给出详细的错误提示。

调试建议： 打开浏览器控制台（F12）查看错误信息，根据提示检查路由配置。

打包说明

• 完整版项目：约 8.4MB
• 精简版项目：约 4.7MB

项目默认开启 gzip 压缩，关闭 gzip 时实际打包体积约 3.7MB，开启后产物体积更小（浏览器请求时会优先加载 .gz 文件）。

如需修改压缩配置，请在 vite.config.ts 中调整 viteCompression 插件参数。